Package 'jpmap'

Retrieve Disputed-Territory Island And Reef Shapes

Description

Returns cartographic island/reef shapes for disputed territories or disputed maritime/EEZ-status areas discussed in Japan territorial-dispute references. These geometries are intentionally separate from the MLIT N03 administrative boundary data and are not authoritative legal boundary polygons.

Usage

jp_disputed_territories(
  territorial_disputes = TRUE,
  regions = c("prefectures", "prefecture", "municipalities", "municipality"),
  inset = TRUE,
  okinawa = TRUE,
  ogasawara = TRUE
)

Arguments

territorial_disputes	Which disputed-territory shapes to include. Use TRUE for all built-in shapes, FALSE for none, or a character vector containing one or more of "northern_territories", "okinotorishima", "senkaku", and "takeshima". Common aliases such as "kuril", "liancourt", "dokdo", and "diaoyu" are also accepted.
regions	Boundary level whose columns should be mirrored: prefectures or municipalities.
inset	Inset behavior. Use TRUE to move Okinawa and Ogasawara, FALSE for literal projected locations, or a character vector containing "okinawa" and/or "ogasawara".
okinawa	Whether Okinawa should be moved when inset includes it.
ogasawara	Whether Ogasawara should be moved when inset includes it.

Value

An sf data frame.

Source

Territory list based on https://en.wikipedia.org/wiki/Territorial_disputes_of_Japan. Shapes are derived from Natural Earth 1:10m land polygons and OpenStreetMap geometry.

Examples

jp_disputed_territories()
jp_disputed_territories(c("senkaku", "takeshima"))

---

Retrieve Japan Map Data

Description

Reads Japan administrative boundary data and returns an sf object.

Usage

jp_map(
  regions = c("prefectures", "prefecture", "municipalities", "municipality"),
  include = c(),
  exclude = c(),
  data_year = NULL,
  inset = TRUE,
  okinawa = TRUE,
  ogasawara = TRUE,
  territorial_disputes = TRUE,
  data_dir = NULL
)

Arguments

regions	Boundary level: prefectures or municipalities.
include	Regions to include by code, English name, or Japanese name.
exclude	Regions to exclude by code, English name, or Japanese name.
data_year	Boundary data year. The newest appropriate available file is used by default. For example, national prefecture maps prefer a national file, while one-prefecture municipal requests can use a matching prefecture file.
inset	Inset behavior. Use TRUE to move both Okinawa and Ogasawara, FALSE for no movement, or a character vector containing "okinawa" and/or "ogasawara" to move selected island groups.
okinawa	Whether Okinawa should be moved when inset includes it.
ogasawara	Whether Ogasawara should be moved when inset includes it.
territorial_disputes	Whether to include disputed-territory island/reef shapes. Use FALSE to exclude them, or a character vector containing one or more of "northern_territories", "okinotorishima", "senkaku", and "takeshima".
data_dir	Optional directory containing jpmap_boundaries_YYYY.gpkg.

Value

An sf data frame.

Examples

if (nrow(available_jpmap_data()) > 0) {
  jp_map("prefectures")
  jp_map("prefectures", okinawa = FALSE)
  jp_map("prefectures", territorial_disputes = FALSE)
  jp_map("municipalities", include = "Okinawa")
  jp_map("prefecture")
  jp_map("municipality", include = "Okinawa")
}

---

Join User Data to a jpmap Boundary Object

Description

jp_map_join() attaches columns from a user data frame to an sf object returned by jp_map(). It is designed for common Japan-map keys, including pref_code, jis_code, and municipality_code, and keeps leading zeroes from getting in the user's way.

Usage

jp_map_join(
  map,
  data,
  by = NULL,
  values = NULL,
  unmatched = c("warning", "error", "ignore"),
  multiple = c("error", "first")
)

Arguments

map	An sf object returned by jp_map().
data	A data frame with one row per region to join.
by	Join column. If NULL, jpmap guesses from common columns such as jis_code, municipality_code, pref_code, prefecture, prefecture_ja, municipality, and municipality_ja. To join columns with different names, use a named character vector such as c("pref_code" = "code"), where the name is the map column and the value is the data column.
values	Optional column expected to exist after joining. This is useful when checking data before passing it to a plotting function.
unmatched	What to do when user data rows do not match the map, or map regions do not receive a data row. One of "warning", "error", or "ignore".
multiple	What to do when data has duplicate join keys. One of "error" or "first".

Value

An sf object with non-geometry columns from data joined to map.

Examples

if (requireNamespace("dplyr", quietly = TRUE) &&
    nrow(available_jpmap_data()) > 0) {
  data("jp_prefecture_gdp")

  gdp <- jp_prefecture_gdp |>
    dplyr::select(pref_code, gdp_per_capita_jpy)

  joined <- jp_map("prefecture") |>
    jp_map_join(gdp, by = "pref_code")

  "gdp_per_capita_jpy" %in% names(joined)
}

---

Draw an Interactive Japan Map with leaflet

Description

jp_map_leaflet() creates a simple interactive web map from jpmap boundaries. It uses literal longitude/latitude geography because Leaflet web tiles expect WGS84 coordinates. Use plot_jpmap() when you want the static Okinawa and Ogasawara inset layout.

Usage

jp_map_leaflet(
  regions = c("prefectures", "prefecture", "municipalities", "municipality"),
  include = c(),
  exclude = c(),
  data = data.frame(),
  values = NULL,
  by = NULL,
  data_year = NULL,
  territorial_disputes = TRUE,
  data_dir = NULL,
  palette = "Blues",
  fill = "grey92",
  color = "grey35",
  weight = 1,
  opacity = 1,
  fill_opacity = 0.75,
  na_color = "#D9D9D9",
  label = NULL,
  popup = NULL,
  tiles = TRUE,
  legend = TRUE,
  fit_bounds = TRUE,
  simplify_tolerance = NULL,
  disputed_fill = NULL,
  disputed_color = NULL,
  disputed_dots = FALSE,
  disputed_dot_radius = 5,
  ...
)

Arguments

regions	Boundary level: prefectures or municipalities.
include	Regions to include by code, English name, or Japanese name.
exclude	Regions to exclude by code, English name, or Japanese name.
data	Optional data frame to join to the map before drawing.
values	Optional column to use for polygon fill colors.
by	Optional join column passed to jp_map_join().
data_year	Boundary data year. The newest appropriate available file is used by default.
territorial_disputes	Whether to include disputed-territory island/reef shapes. Use FALSE to exclude them, or a selected character vector.
data_dir	Optional directory containing jpmap_boundaries_YYYY.gpkg.
palette	Palette name or color vector passed to Leaflet palette functions when values is supplied.
fill	Polygon fill color used when values is NULL.
color	Polygon outline color.
weight	Polygon outline weight.
opacity	Polygon outline opacity.
fill_opacity	Polygon fill opacity.
na_color	Fill color for missing values.
label	NULL for default region labels, FALSE for no labels, a column name, or a character vector with one value per map row.
popup	NULL for default popups, FALSE for no popups, a column name, or a character vector with one value per map row.
tiles	Whether to add default OpenStreetMap tiles.
legend	Whether to add a legend when values is supplied.
fit_bounds	Whether to zoom the widget to the map bounds.
simplify_tolerance	Optional tolerance passed to sf::st_simplify() before drawing polygons. This is useful for smaller website widgets.
disputed_fill	Optional fill color for disputed-territory shapes. When NULL, the ordinary map fill is used.
disputed_color	Optional outline color for disputed-territory shapes. When NULL, the ordinary map outline is used.
disputed_dots	Whether to draw circle markers on disputed-territory shapes.
disputed_dot_radius	Radius for disputed-territory circle markers.
...	Additional arguments passed to leaflet::leaflet().

Value

A leaflet htmlwidget.

Examples

if (requireNamespace("leaflet", quietly = TRUE) &&
    requireNamespace("dplyr", quietly = TRUE) &&
    nrow(available_jpmap_data()) > 0) {
  data("jp_prefecture_gdp")

  gdp <- jp_prefecture_gdp |>
    dplyr::select(pref_code, prefecture, gdp_per_capita_jpy)

  jp_map_leaflet(
    "prefecture",
    data = gdp,
    values = "gdp_per_capita_jpy",
    popup = "prefecture"
  )
}

---

Join Data to a jpmap Map

Description

Joins user data to a Japan map object. This is a compact wrapper around jp_map_join() kept for plotting workflows that call it internally.

Usage

jp_map_with_data(map, data, values = NULL, by = NULL)

Arguments

map	An sf object returned by jp_map().
data	A data frame containing a matching administrative code or name column.
values	Optional value column to check after joining.
by	Optional join column. If omitted, jpmap guesses from common columns.

Value

An sf object.

---

GDP per capita by Japanese prefecture

Description

A sample data frame containing 2021 prefecture GDP per capita values.

Format

A data frame with 47 rows and 6 variables:

pref_code

Two-digit Japanese prefecture code.

prefecture

Prefecture name in English.

year

Reference year.

gdp_per_capita_jpy

GDP per capita in Japanese yen.

gdp_per_capita_usd_ppp

GDP per capita in U.S. dollars at PPP.

source

Source note.

Source

OECD 2021 regional GDP per-capita values as tabulated at https://en.wikipedia.org/wiki/List_of_Japanese_prefectures_by_GDP_per_capita.

---

Selected U.S. military installations in Japan

Description

A sample data frame containing selected U.S. military installations in Japan with longitude/latitude coordinates and public approximate personnel figures where those figures have a clear source.

Format

A data frame with 17 rows and 12 variables:

base

Installation or command name.

branch

Primary U.S. military branch.

prefecture

Japanese prefecture.

municipality

Municipality or municipalities.

lon

Longitude in WGS84.

lat

Latitude in WGS84.

personnel

Approximate public personnel figure, when available.

personnel_scope

What the public figure counts.

personnel_geography

Whether the figure describes an installation, regional total, command, or broader installation community.

personnel_is_base_specific

Whether personnel is interpreted as a base-specific figure.

source_url

Source URL.

note

Caveat for use in examples.

Details

These values are intended for examples and are not an official personnel accounting. Some rows describe broader installation, regional, command, or community populations; see personnel_scope and personnel_geography.

Source

Public installation, command, and regional pages listed in the source_url column, including https://en.wikipedia.org/wiki/Misawa_Air_Base, https://en.wikipedia.org/wiki/Yokota_Air_Base, and https://en.wikipedia.org/wiki/Okinawa_Island.

---

Coordinate Reference System for jpmap

Description

Returns the projected coordinate reference system used by jpmap.

Usage

jpmap_crs()

Value

An sf::st_crs() object.

---

Manage jpmap Boundary Data

Description

Helpers for locating and building the GeoPackage boundary data used by jpmap. Boundary GeoPackage files can come from the separate jpmapdata package or from files built locally with jpmap_build_data().

Usage

jpmap_data_dir(create = TRUE)

available_jpmap_data(data_dir = NULL)

jpmap_build_data(
  year = 2024,
  prefecture = NULL,
  destdir = jpmap_data_dir(),
  url = NULL,
  overwrite = FALSE,
  quiet = FALSE,
  simplify_tolerance = NULL
)

Arguments

create	Whether to create the default data directory.
data_dir	Optional directory to scan for boundary data.
year	Boundary data year.
prefecture	Optional prefecture code, English name, or Japanese name. When supplied, only that prefecture's official MLIT N03 file is downloaded and built.
destdir	Directory where the generated GeoPackage should be written.
url	Optional source URL. By default, an MLIT N03 URL is constructed.
overwrite	Whether to overwrite an existing GeoPackage.
quiet	Whether to suppress messages from download and spatial reads/writes.
simplify_tolerance	Optional tolerance passed to sf::st_simplify().

Value

jpmap_data_dir() returns a path, available_jpmap_data() returns a data frame with year, pref_code, prefecture, source, and path, and jpmap_build_data() invisibly returns the generated file.

Source

MLIT National Land Numerical Information N03 administrative area data: https://nlftp.mlit.go.jp/ksj/gml/datalist/KsjTmplt-N03-2024.html.

Examples

jpmap_data_dir(create = FALSE)
available_jpmap_data()


jpmap_build_data(
  year = 2024,
  prefecture = "Ehime",
  destdir = tempdir(),
  overwrite = TRUE,
  quiet = TRUE
)

---

Transform Data to the jpmap Projection

Description

Transforms geographic data to the jpmap projected coordinate system. When inset = TRUE, Okinawa and Ogasawara are moved to visible inset locations. Use okinawa = FALSE, ogasawara = FALSE, inset = "okinawa", or inset = "ogasawara" to transport only one island group.

Usage

jpmap_transform(
  data,
  input_names = c("lon", "lat"),
  output_names = input_names,
  inset = TRUE,
  okinawa = TRUE,
  ogasawara = TRUE
)

Arguments

data	An sf object, sfc geometry vector, or data frame.
input_names	Longitude and latitude column names for data frames.
output_names	Output coordinate column names for data frames.
inset	Inset behavior. Use TRUE to move both Okinawa and Ogasawara, FALSE for no movement, or a character vector containing "okinawa" and/or "ogasawara" to move selected island groups.
okinawa	Whether Okinawa should be moved when inset includes it.
ogasawara	Whether Ogasawara should be moved when inset includes it.

Value

An object of the same general type as data.

Examples

if (requireNamespace("tibble", quietly = TRUE)) {
  places <- tibble::tribble(
    ~place, ~lon, ~lat,
    "Tokyo", 139.767, 35.681,
    "Naha", 127.681, 26.212,
    "Ogasawara", 142.191, 27.094
  )

  places |>
    jpmap_transform(output_names = c("x", "y"))
  places |>
    jpmap_transform(output_names = c("x", "y"), inset = "okinawa")
  places |>
    jpmap_transform(output_names = c("x", "y"), ogasawara = FALSE)
}

---

Plot a Japan Map

Description

Plots Japan prefecture or municipal boundaries using ggplot2.

Usage

plot_jpmap(
  regions = c("prefectures", "prefecture", "municipalities", "municipality"),
  include = c(),
  exclude = c(),
  data = data.frame(),
  values = NULL,
  labels = FALSE,
  label_color = "black",
  data_year = NULL,
  inset = TRUE,
  okinawa = TRUE,
  ogasawara = TRUE,
  territorial_disputes = TRUE,
  disputed_fill = NULL,
  disputed_color = NULL,
  disputed_linewidth = NULL,
  disputed_dots = FALSE,
  disputed_dot_fill = "#001040",
  disputed_dot_color = "white",
  disputed_dot_size = 1.25,
  disputed_dot_stroke = 0.2,
  inset_boxes = TRUE,
  inset_box_color = "grey50",
  inset_box_linewidth = 0.35,
  data_dir = NULL,
  xlim = NULL,
  ylim = NULL,
  x_breaks = ggplot2::waiver(),
  y_breaks = ggplot2::waiver(),
  x_labels = ggplot2::waiver(),
  y_labels = ggplot2::waiver(),
  fill = "grey92",
  color = "grey35",
  linewidth = 0.25,
  ...
)

Arguments

regions	Boundary level: prefectures or municipalities.
include	Regions to include by code, English name, or Japanese name.
exclude	Regions to exclude by code, English name, or Japanese name.
data	Optional data frame to join to the map.
values	Column name in data to use as the fill variable.
labels	Whether to draw region labels.
label_color	Label text color.
data_year	Boundary data year.
inset	Inset behavior. Use TRUE to move both Okinawa and Ogasawara, FALSE for no movement, or a character vector containing "okinawa" and/or "ogasawara" to move selected island groups. For filtered municipality maps such as plot_jpmap("municipality", include = "Okinawa"), the default plot frame is local and non-inset unless inset is supplied explicitly.
okinawa	Whether Okinawa should be moved when inset includes it.
ogasawara	Whether Ogasawara should be moved when inset includes it.
territorial_disputes	Whether to include disputed-territory island/reef shapes. Use FALSE to exclude them, or a character vector containing one or more of "northern_territories", "okinotorishima", "senkaku", and "takeshima".
disputed_fill	Optional fill color for disputed-territory shapes. When NULL, the ordinary map fill is used.
disputed_color	Optional outline color for disputed-territory shapes. When NULL, the ordinary map outline is used.
disputed_linewidth	Optional line width for disputed-territory shapes.
disputed_dots	Whether to draw dot markers on disputed-territory shapes.
disputed_dot_fill	Fill color for disputed-territory dot markers.
disputed_dot_color	Outline color for disputed-territory dot markers.
disputed_dot_size	Size for disputed-territory dot markers.
disputed_dot_stroke	Stroke width for disputed-territory dot markers.
inset_boxes	Whether to draw boxes around transported Okinawa and Ogasawara insets.
inset_box_color	Outline color for inset boxes.
inset_box_linewidth	Line width for inset boxes.
data_dir	Optional directory containing jpmap_boundaries_YYYY.gpkg.
xlim, ylim	Optional longitude and latitude limits for the plot frame.
x_breaks, y_breaks	Optional longitude and latitude axis breaks.
x_labels, y_labels	Optional longitude and latitude axis labels.
fill	Boundary fill color when values is not supplied.
color	Boundary line color.
linewidth	Boundary line width.
...	Additional arguments passed to ggplot2::geom_sf().

Value

A ggplot2 plot.

Examples

if (nrow(available_jpmap_data()) > 0) {
  plot_jpmap("prefecture")
  plot_jpmap("prefecture", ogasawara = FALSE)
  plot_jpmap("prefecture", territorial_disputes = FALSE)
  plot_jpmap(
    "prefecture",
    ogasawara = FALSE,
    xlim = c(122, 149),
    ylim = c(28.5, 47),
    x_breaks = seq(125, 145, 5),
    y_breaks = seq(30, 45, 5)
  )
  plot_jpmap("prefecture", inset_boxes = FALSE)
  plot_jpmap("municipality", include = "Okinawa")
}

---