Skip to contents

Boundary Data Policy

Source: vignettes/boundary-data-policy.Rmd
boundary-data-policy.Rmd

jpmap separates functionality from large boundary files. The package provides the plotting, joining, transformation, and download helpers. Boundary GeoPackages can come from the companion jpmapdata package or from local files you build from official public sources.

Boundary Data Locations

jpmap checks:

  • GeoPackage files installed by the companion jpmapdata package;
  • GeoPackage files saved in jpmap_data_dir();
  • a custom data_dir when you pass one.

You can see the available GeoPackage files with:

library(jpmap)

available <- available_jpmap_data()[c("year", "pref_code", "prefecture", "source")]
row.names(available) <- NULL
available
#>   year pref_code prefecture    source
#> 1 2021      <NA>       <NA> jpmapdata
#> 2 2024        47    Okinawa jpmapdata

The website intentionally does not print the user-specific data directory. Run jpmap_data_dir(create = FALSE) locally when you need to inspect where your own generated boundary files are saved.

Official Municipal Boundaries

Municipality maps are based on Japan’s MLIT National Land Numerical Information N03 administrative area data:

Build one prefecture when you only need one prefecture:

jpmap_build_data(year = 2024, prefecture = "Ehime")

Build the national file only when you need all municipalities:

jpmap_build_data(year = 2024)

jpmap_build_data() converts the source archive to a GeoPackage with two layers, prefectures and municipalities.

Disputed-Territory Shapes

Disputed-territory shapes are politically sensitive because inclusion and exclusion are both meaningful map choices. Users can exclude them explicitly when that is the right display choice:

plot_jpmap("prefecture", territorial_disputes = FALSE)

You can also include selected areas:

plot_jpmap("prefecture", territorial_disputes = "senkaku")
plot_jpmap("prefecture", territorial_disputes = c("senkaku", "takeshima"))

The disputed-territory layer is a cartographic display layer. It is not a legal statement about sovereignty. The layer exists so users can make an explicit and documented display choice rather than relying on inconsistent small-island and reef handling across data sources.

Custom Boundary Roadmap

Future extensions should make it easier to work with user-supplied special boundary data, such as electoral districts, historical municipalities, school districts, and other research-specific geographies. These datasets should usually remain outside jpmap and jpmapdata because they are larger, more specialized, and often depend on a particular election, law, time period, or research design.

The intended direction is for jpmap to provide easy-to-use helpers for reading, checking, transforming, and plotting user-supplied sf, GeoPackage, or shapefile boundary data with the same Okinawa and Ogasawara inset behavior used by the built-in map workflows.

For now, users can already bring their own spatial data into the jpmap coordinate system with jpmap_transform().

Reproducibility

For a reproducible project, record:

  • the jpmap package version;
  • the boundary data year;
  • whether boundaries came from jpmapdata, local files, or a custom data directory;
  • whether territorial_disputes was FALSE, TRUE, or a selected character vector;
  • any simplification tolerance used when building local data.

For example:

sessionInfo()
available <- available_jpmap_data()[c("year", "pref_code", "prefecture", "source")]
row.names(available) <- NULL
available