Package {jpmap}

jpmap: Japan Maps with Insets for Okinawa and Ogasawara

Description

Tools for drawing maps of Japan with prefecture and municipal boundaries. The API mirrors the main workflow of the usmap package.

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

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

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

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

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

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

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

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

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")
}