README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  warning = FALSE
)
```

# jpgrid <a href="https://uchidamizuki.github.io/jpgrid/"><img src="man/figures/logo.png" align="right" height="139"/></a>

<!-- badges: start -->

[![CRAN status](https://www.r-pkg.org/badges/version/jpgrid)](https://CRAN.R-project.org/package=jpgrid) [![R-CMD-check](https://github.com/UchidaMizuki/jpgrid/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/UchidaMizuki/jpgrid/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/UchidaMizuki/jpgrid/branch/main/graph/badge.svg)](https://app.codecov.io/gh/UchidaMizuki/jpgrid?branch=main)

<!-- badges: end -->

[*The English version of the README is here.*](https://github.com/UchidaMizuki/jpgrid/blob/main/README.en.md)

jpgridは，日本産業規格JIS X 0410 [地域メッシュコード](https://www.jisc.go.jp/app/jis/general/GnrJISNumberNameSearchList?show&jisStdNo=X0410) （Grid Square Code）で定められた基準地域メッシュ (1次～3次) と分割地域メッシュ，および3次メッシュ1/10細分区画を利用するためのRパッケージです． 地域メッシュコードは，経度・緯度に基づいて，日本全国の地域に設定された正方形に近い地域区分です． 地域メッシュコードの詳細については，[統計局ページ](https://www.stat.go.jp/data/mesh/pdf/gaiyo1.pdf)を確認してください．

地域メッシュコードの概要を以下に示します．jpgridでは，`grid_80km`のように，メッシュの一片の長さで各地域メッシュコードを区別します．

```{r,echo=FALSE}
df <- tibble::tibble(`名称` = c("第1次地域区画 (1次メッシュ)", "第2次地域区画 (2次メッシュ)", "第3次地域区画 (3次メッシュ)", "2分の1地域メッシュ", "4分の1地域メッシュ", "8分の1地域メッシュ", "3次メッシュ1/10細分区画"),
                     `一片の長さ` = c("約80km", "約10km", "約1km", "約500m", "約250m", "約125m", "約100m"),
                     `桁数` = c(4, 6, 8, 9, 10, 11, 10))
knitr::kable(df)
```

jpgridは，Rパッケージの[jpmesh](https://github.com/uribo/jpmesh)より高速な処理を可能とするために開発されたものです． jpgridとjpmeshとの主な違いとして以下が挙げられます．

1.  メッシュコードに，メッシュサイズ (`grid_80km`など) が明示的に与えられます．
2.  国土にかからない (海上の) メッシュにも対応しています．
3.  n次隣接メッシュの抽出・メッシュ間の (線分) 経路上のメッシュ抽出や距離算出などの複雑な処理が可能です．

## インストール方法

CRANからインストールが可能です．

``` r
install.packages("jpgrid")
```

開発版はGitHubからインストールしてください．

``` r
# install.packages("devtools")
devtools::install_github("UchidaMizuki/jpgrid")
```

## 使用方法

```{r,message=FALSE}
library(jpgrid)
library(tidyverse)

JGD2011 <- 6668
```

### ジオメトリの地域メッシュコードへの変換

`geometry_to_grid()`により，`sf`オブジェクトを地域メッシュコードに変換することができます． また，`grid_as_sf()`により地域メッシュ（`grid`クラス）を含むデータを`sf`オブジェクトに変換できます．

```{r,message=FALSE}
geom_chiba <- rnaturalearth::ne_states(country = "japan",
                                       returnclass = "sf") |> 
  filter(name == "Chiba")
grid_chiba <- geometry_to_grid(geom_chiba, "10km") |> 
  first() |> 
  grid_as_sf(crs = sf::st_crs(geom_chiba))

grid_chiba |> 
  ggplot() +
  geom_sf(data = geom_chiba) +
  geom_sf(fill = "transparent") +
  geom_sf_text(aes(label = as.character(grid)),
               size = 2)
```

また，`grid_city_2020`には，市区町村別の1 kmメッシュコードが格納されています．

```{r}
grid_city_2020 |> 
  filter(str_starts(city_code, "121")) |> 
  grid_as_sf(crs = JGD2011) |> 
  ggplot(aes(fill = as_factor(city_name_ja))) +
  geom_sf() +
  scale_fill_brewer("City",
                    palette = "Set2")
```

### 文字列・数値からの地域メッシュコードの生成

文字列・数値から地域メッシュコードを生成するためには`parse_grid()`を使用します．

-   `grid_size = "80km"`のようにメッシュサイズを指定します．
    -   `grid_size = NULL`の場合はメッシュサイズが自動的に決定されます．
-   デフォルト（`strict = TRUE`）では，メッシュコードの桁数が所定の桁数であることを要求します．

```{r}
x <- c("53394526313", "5339358633", "533945764", "53394611", "523503", "5339", NA)

parse_grid(x, grid_size = "80km")
parse_grid(x, grid_size = "125m")
parse_grid(x)

parse_grid(x, "80km",
           strict = FALSE)
parse_grid(x, "125m",
           strict = FALSE)
parse_grid(x, 
           strict = FALSE)
```

### 地域メッシュコードのサイズの変換

地域メッシュコードのメッシュサイズを粗くする場合には，`grid_convert()`を使用します． また，`grid_subdivide()`により，地域メッシュコードの細分化を行います．

-   `grid_subdivide()`は，元のメッシュに含まれるメッシュを要素にもつリストを出力します．
-   500 mメッシュ・100 mメッシュ間の変換に対応しています．

```{r}
grid_500m <- parse_grid("533945764", "500m")

grid_convert(grid_500m, "1km")

grid_100m <- grid_subdivide(grid_500m, "100m")
grid_100m

tibble(grid_100m = grid_100m[[1]]) |> 
  grid_as_sf(crs = JGD2011) |>  
  ggplot() +
  geom_sf() +
  geom_sf_text(aes(label = as.character(grid_100m)))
```

### 経度・緯度から地域メッシュコードへの変換

`coords_to_grid()`は，経度・緯度を地域メッシュコードに変換します．

```{r}
tibble(X = c(139.7008, 135.4375), # 経度
       Y = c(35.68906, 34.70833)) |>  # 緯度
  mutate(grid_100m = coords_to_grid(X, Y, "100m"),
         grid_125m = coords_to_grid(X, Y, "125m")) |> 
  knitr::kable()
```

### 地域メッシュコードから経度・緯度への変換

`grid_to_coords()`は，地域メッシュコードを経度・緯度に変換します．

```{r}
tibble(grid = parse_grid(c("5339452660", "5235034590"), "100m")) |> 
  mutate(grid_to_coords(grid)) |> 
  knitr::kable()
```

### 隣接メッシュの算出

`grid_neighborhood()`関数は，隣接するメッシュを算出します．

-   `n`を指定することでn次隣接メッシュの算出が可能
-   `type = "von_neumann"`でノイマン近傍, `type = "moore"`でムーア近傍を指定可能

```{r}
neighborhood <- parse_grid("644142", "10km") |> 
  grid_neighborhood(n = c(0:2),
                    type = "von_neumann",
                    simplify = FALSE)

neighborhood[[1]] |> 
  grid_as_sf(crs = JGD2011) |> 
  
  ggplot(aes(fill = as.factor(n))) +
  geom_sf() +
  geom_sf_text(aes(label = as.character(grid_neighborhood)))
```

```{r}
neighborhood <- parse_grid("644142", "10km") |> 
  grid_neighborhood(n = c(0:2),
                    type = "moore",
                    simplify = FALSE)

neighborhood[[1]] |> 
  grid_as_sf(crs = JGD2011) |> 
  ggplot(aes(fill = as.factor(n))) +
  geom_sf() +
  geom_sf_text(aes(label = as.character(grid_neighborhood)))
```

### メッシュの連結成分を取得

`grid_components()`関数は，メッシュの連結成分を算出し，クラスターIDを返します．

-   `grid_neighborhood()`関数と同じく`n`と`type`を指定できます．

```{r}
set.seed(1234)

grid_city_2020 |> 
  filter(str_starts(city_code, "121")) |> 
  slice_sample(prop = 0.5) |> 
  mutate(cluster = grid_components(grid,
                                   type = "von_neumann")) |> 
  grid_as_sf(crs = JGD2011) |> 
  ggplot(aes(fill = fct_shuffle(as_factor(cluster)))) +
  geom_sf(show.legend = FALSE) 
```

### メッシュ間の線分描画

`grid_line()`関数により，メッシュ間の線分上に存在するメッシュを抽出します．

```{r}
grid_from <- parse_grid(c("6441", "5339"), "80km")
grid_to <- parse_grid(c("5237", "5235"), "80km")

line <- grid_line(grid_from, grid_to)

tibble::tibble(grid = line[[1]]) |> 
  grid_as_sf(crs = JGD2011) |> 
  ggplot() +
  geom_sf() +
  geom_sf_text(aes(label = as.character(grid)))
```

メッシュの`list`を与えることで複数メッシュを通る場合に対応可能です．

-   `close = TRUE`で線分を閉じます．
-   `skip_na = TRUE`で`NA`をスキップします．

```{r}
grid_1 <- parse_grid(c("6441", "5339", NA, "5250"), "80km")
grid_2 <- parse_grid(c("6439", "5211", "4013", "6635"), "80km")

line <- grid_line(list(grid_1, grid_2), 
                  close = TRUE,
                  skip_na = TRUE)

tibble::tibble(grid = line[[1]]) |> 
  grid_as_sf(crs = JGD2011) |> 
  ggplot() +
  geom_sf() +
  geom_sf_text(aes(label = as.character(grid)))
```

### メッシュ間距離の算出

`grid_distance()`関数は，メッシュ間距離（大円距離）を算出します．

-   `grid_line()`と同様にメッシュの`list`で経路距離を算出可能です．

```{r}
grid_from <- parse_grid(c("6441", "5339"), "80km")
grid_to <- parse_grid(c("5237", "5235"), "80km")

distance <- grid_distance(grid_from, grid_to)

print(distance)
```

### その他

-   `grid_move()`関数により，東西南北方向の地域メッシュコードを算出可能です．
-   80kmメッシュの桁が負や三桁以上になる範囲外のメッシュについては，当該コードを`<-1>`，`<123>`のように表示し，既存メッシュと明確に区別できるようにしています．

## jpmeshとの処理速度の比較

本パッケージのメッシュ・緯度経度間の変換速度は，jpmeshパッケージと比べて数十～数百倍ほど高速です．

```{r,echo=FALSE,eval=FALSE}
X <- runif(1e1, 139, 140)
Y <- runif(1e1, 39, 40)

microbenchmark::microbenchmark(`jpgrid::coords_to_grid()` = coords_to_grid(X, Y, "1km"),
                               `jpmesh::coords_to_mesh()` = jpmesh::coords_to_mesh(X, Y,
                                                                                   mesh_size = 1),
                               setup = set.seed(1234)) |> 
  autoplot()

ggsave("man/figures/README-microbenchmark-coords-to-grid.png")
```

```{r,echo=FALSE,eval=FALSE}
X <- runif(1e1, 139, 140)
Y <- runif(1e1, 39, 40)
grid_jpgrid <- coords_to_grid(X, Y, "1km")
mesh_jpmesh <- jpmesh::coords_to_mesh(X, Y, 
                                      mesh_size = 1)

microbenchmark::microbenchmark(`jpgrid::grid_to_coords()` = grid_to_coords(grid_jpgrid),
                               `jpmesh::mesh_to_coords()` = jpmesh::mesh_to_coords(mesh_jpmesh),
                               setup = set.seed(1234)) |> 
  autoplot()

ggsave("man/figures/README-microbenchmark-grid-to-coords.png")
```

<img src="man/figures/README-microbenchmark-coords-to-grid.png" width="100%"/>

<img src="man/figures/README-microbenchmark-grid-to-coords.png" width="100%"/>