Package 'maplore'

Add a tooltip that puts each value in context

Description

Adds a tooltip to a layer that shows, on hover (or tap on touch screens), a feature's value together with where it stands among all features: its rank, the share of features with a lower value, the difference with the average, and a small distribution strip with the feature marked.

Usage

add_context_tooltip(
  map,
  layer_id,
  column,
  name_column = NULL,
  label = column,
  weight = NULL,
  unit = "features",
  locale = "en-US",
  digits = 1,
  prefix = "",
  suffix = "",
  diff_suffix = NULL,
  color = NULL,
  highlight = TRUE,
  highlight_color = "#1f2328",
  labels = context_labels()
)

Arguments

map	A map created with mapgl::maplibre() or mapgl::mapboxgl().
layer_id	ID of the layer to summarise: a polygon layer (such as mapgl::add_fill_layer()) or a point layer (such as mapgl::add_circle_layer() or mapgl::add_symbol_layer()). Its source must be an sf object or inline GeoJSON added in R; vector tile sources are not supported.
column	Name of the numeric column to show.
name_column	Optional column with feature names, shown as the tooltip's title.
label	Name of the variable shown in the panel. Defaults to column.
weight	Optional numeric column used to weight the average, for example population.
unit	Name for the features, shown as "14 of 528 unit".
locale	Locale for number formatting, such as "en-US" or "es-AR".
digits	Number of decimals for values. Values of a million or more are abbreviated, such as ⁠12.4M⁠.
prefix, suffix	Text added before and after each value, such as "$" or "%".
diff_suffix	Text added after the difference between the view and the overall average. NULL (the default) uses suffix, except when suffix contains "%": a difference between percentages is in percentage points, so the points label is used instead.
color	Color for the feature's marker on the distribution strip. NULL (the default) uses the layer's own color scale when it is an interpolate() or step_expr() on column, and blue otherwise.
highlight	If TRUE, outlines the feature under the pointer.
highlight_color	Color of that outline.
labels	Panel texts, as returned by context_labels().

Details

Use it instead of the layer's own tooltip argument: with both, two tooltips are shown.

Value

The modified map object.

Examples

## Not run: 
library(mapgl)

maplibre(center = c(-64, -38.5), zoom = 3.4) |>
  add_fill_layer(
    id = "deptos",
    source = ar_departments,
    fill_color = interpolate(
      column = "growth",
      values = c(-10, 0, 10),
      stops = c("#b2182b", "#f7f7f7", "#2166ac")
    )
  ) |>
  add_context_tooltip(
    layer_id = "deptos",
    column = "growth",
    name_column = "department",
    label = "Population growth",
    unit = "departments",
    suffix = "%"
  )

## End(Not run)

---

Add a search box over the layer's own features

Description

Adds a search box that suggests features of a layer as you type, matching a column such as a name. Choosing a suggestion moves the map to the feature and outlines it. Matching ignores case and accents, so "cordoba" finds "Córdoba". Unlike mapgl::add_geocoder_control(), which searches places around the world, this searches your data.

Usage

add_feature_search(
  map,
  layer_id,
  search_column,
  detail_column = NULL,
  placeholder = NULL,
  max_results = 8,
  locale = "en-US",
  position = "top-right",
  width = 240,
  highlight_color = "#1f2328",
  labels = context_labels()
)

Arguments

map	A map created with mapgl::maplibre() or mapgl::mapboxgl().
layer_id	ID of the layer to search. Its source must be an sf object or inline GeoJSON added in R.
search_column	Column to search, such as the feature names.
detail_column	Optional column shown next to each suggestion to tell apart features with the same name, such as the province.
placeholder	Text shown in the empty search box. NULL (the default) uses the search_placeholder label, "Search…".
max_results	Maximum number of suggestions.
locale	Locale used to sort the suggestions alphabetically.
position	Corner for the search box: one of "top-left", "top-right", "bottom-left" or "bottom-right".
width	Width of the search box in pixels.
highlight_color	Color of the outline drawn around the chosen feature.
labels	Panel texts, as returned by context_labels().

Details

The search box works with the keyboard: arrow keys move through the suggestions, Enter chooses one and Escape closes them.

Value

The modified map object.

Examples

## Not run: 
library(mapgl)

maplibre(center = c(-64, -38.5), zoom = 3.4) |>
  add_fill_layer(id = "deptos", source = ar_departments, fill_color = "#9ecae1") |>
  add_feature_search(
    layer_id = "deptos",
    search_column = "department",
    detail_column = "province"
  )

## End(Not run)

---

Add a ranking of the features in view

Description

Adds a panel listing the features in view with the highest (or lowest) values, updated as the map is panned and zoomed. Each entry shows the value, a bar on the scale of the whole layer and the feature's rank among all features; clicking on a name moves the map to it.

Usage

add_view_ranking(
  map,
  layer_id,
  column,
  name_column,
  label = column,
  n = 5,
  order = c("desc", "asc"),
  title = NULL,
  unit = "features",
  locale = "en-US",
  digits = 1,
  prefix = "",
  suffix = "",
  position = "top-right",
  width = 240,
  color = NULL,
  highlight_color = "#1f2328",
  collapsible = TRUE,
  collapsed = NULL,
  labels = context_labels()
)

Arguments

map	A map created with mapgl::maplibre() or mapgl::mapboxgl().
layer_id	ID of the layer to summarise: a polygon layer (such as mapgl::add_fill_layer()) or a point layer (such as mapgl::add_circle_layer() or mapgl::add_symbol_layer()). Its source must be an sf object or inline GeoJSON added in R; vector tile sources are not supported.
column	Name of the numeric column to rank by.
name_column	Column with the feature names to list.
label	Name of the variable shown in the panel. Defaults to column.
n	Number of features to list.
order	"desc" (the default) lists the highest values first; "asc", the lowest.
title	Title of the panel. NULL (the default) uses the ranking_highest or ranking_lowest label.
unit	Name for the features, shown as "14 of 528 unit".
locale	Locale for number formatting, such as "en-US" or "es-AR".
digits	Number of decimals for values. Values of a million or more are abbreviated, such as ⁠12.4M⁠.
prefix, suffix	Text added before and after each value, such as "$" or "%".
position	Corner for the panel: one of "top-left", "top-right", "bottom-left" or "bottom-right".
width	Width of the panel in pixels.
color	Color for the bars. NULL (the default) uses the layer's own color scale when it is an interpolate() or step_expr() on column, and blue otherwise.
highlight_color	Color of the outline drawn around a feature when hovering over its name.
collapsible	If TRUE, adds a button to collapse the panel down to its title and the first name.
collapsed	Whether the panel starts collapsed. NULL (the default) starts collapsed on maps narrower than 480 pixels, such as on phones.
labels	Panel texts, as returned by context_labels().

Details

Which features count as "in view" follows the same rules as add_view_summary().

Value

The modified map object.

Examples

## Not run: 
library(mapgl)

maplibre(center = c(-64, -38.5), zoom = 3.4) |>
  add_fill_layer(
    id = "deptos",
    source = ar_departments,
    fill_color = interpolate(
      column = "growth",
      values = c(-10, 0, 10),
      stops = c("#b2182b", "#f7f7f7", "#2166ac")
    )
  ) |>
  add_view_ranking(
    layer_id = "deptos",
    column = "growth",
    name_column = "department",
    label = "Population growth 2022-2035",
    unit = "departments",
    suffix = "%"
  )

## End(Not run)

---

Add an "in this view" summary panel to a map

Description

Adds a panel that summarises the features of a layer that are currently visible and compares them with the whole layer: how many are in view, their average (or median, or total), the highest and lowest values, and a histogram of the visible values over the distribution of all values. The panel updates as the map is panned and zoomed.

Usage

add_view_summary(
  map,
  layer_id,
  column,
  label = column,
  name_column = NULL,
  stat = c("mean", "median", "sum"),
  weight = NULL,
  weight_label = weight,
  title = NULL,
  unit = "features",
  locale = "en-US",
  digits = 1,
  prefix = "",
  suffix = "",
  diff_suffix = NULL,
  position = "top-left",
  width = 260,
  color = NULL,
  highlight_color = "#1f2328",
  bins = 20,
  style = c("full", "compact", "mini"),
  show_area = NULL,
  area_unit = c("km2", "mi2"),
  collapsible = TRUE,
  collapsed = NULL,
  labels = context_labels(),
  compact = NULL
)

Arguments

map	A map created with mapgl::maplibre() or mapgl::mapboxgl().
layer_id	ID of the layer to summarise: a polygon layer (such as mapgl::add_fill_layer()) or a point layer (such as mapgl::add_circle_layer() or mapgl::add_symbol_layer()). Its source must be an sf object or inline GeoJSON added in R; vector tile sources are not supported.
column	Name of the numeric column to summarise.
label	Name of the variable shown in the panel. Defaults to column.
name_column	Optional column with feature names, used to report the highest and lowest features in view.
stat	Statistic shown for the features in view: "mean" (the default), "median" or "sum". For "sum" the panel shows which share of the overall total is in view, which suits absolute values such as population or sales.
weight	Optional numeric column used to weight the mean or median, for example population. When given, the panel also shows the share of the total weight that is in view. It is not used by stat = "sum".
weight_label	Name of the weight shown in the panel. Defaults to weight.
title	Title of the panel. NULL (the default) uses the title label, "In this view".
unit	Name for the features, shown as "14 of 528 unit".
locale	Locale for number formatting, such as "en-US" or "es-AR".
digits	Number of decimals for values. Values of a million or more are abbreviated, such as ⁠12.4M⁠.
prefix, suffix	Text added before and after each value, such as "$" or "%".
diff_suffix	Text added after the difference between the view and the overall average. NULL (the default) uses suffix, except when suffix contains "%": a difference between percentages is in percentage points, so the points label is used instead.
position	Corner for the panel: one of "top-left", "top-right", "bottom-left" or "bottom-right".
width	Width of the panel in pixels.
color	Color for the histogram bars of the features in view. NULL (the default) uses the layer's own color scale when it is an interpolate() or step_expr() on column, and blue otherwise.
highlight_color	Color of the outline drawn around features when hovering over the histogram or the highest and lowest names.
bins	Number of histogram bins.
style	How much the panel shows: "full" (the default): count, value, comparison, highest and lowest, and histogram. "compact": only the count, the value and the comparison. "mini": three figures side by side: features in view, the value and the area of the view.
show_area	Whether to show the area of the Earth covered by the screen. NULL (the default) shows it in the "mini" style only. It is shown as a dash when part of the screen is not on the Earth: when the globe does not fill the screen, or the map is tilted towards the horizon.
area_unit	Unit for the area: "km2" (the default) or "mi2".
collapsible	If TRUE, adds a button to collapse the panel down to its title and value.
collapsed	Whether the panel starts collapsed. NULL (the default) starts collapsed on maps narrower than 480 pixels, such as on phones.
labels	Panel texts, as returned by context_labels().
compact	Deprecated: compact = TRUE is the same as style = "compact".

Details

The panel is also a way into the map: hovering over a histogram bar outlines the features in that range, and clicking on the name of the highest or lowest feature moves the map to it. When the layer is colored with mapgl::interpolate() or mapgl::step_expr() on the same column, the histogram uses the same colors, so it doubles as a legend.

All the work happens in the browser, so the panel works in static HTML, R Markdown and Quarto documents without Shiny.

A feature counts as "in view" when any part of it is on screen: for points, when the point is on screen. Features outside the layer's zoom range are not counted, and neither are features hidden by the layer's filter (in that case only features drawn on screen are counted, so very small features may be missed at low zoom).

On a clustered layer (cluster_options in mapgl::add_circle_layer()), every point in view is counted, whether it is drawn on its own or inside a cluster. Use the ID of the layer itself, not of its -clusters layer.

Value

The modified map object.

Examples

## Not run: 
library(mapgl)

maplibre(center = c(-64, -38.5), zoom = 3.4) |>
  add_fill_layer(
    id = "deptos",
    source = ar_departments,
    fill_color = interpolate(
      column = "growth",
      values = c(-10, 0, 10),
      stops = c("#b2182b", "#f7f7f7", "#2166ac")
    ),
    fill_opacity = 0.8
  ) |>
  add_view_summary(
    layer_id = "deptos",
    column = "growth",
    label = "Population growth 2022-2035",
    name_column = "department",
    weight = "pop_2022",
    weight_label = "population",
    unit = "departments",
    suffix = "%"
  )

## End(Not run)

---

Argentine departments with projected population growth

Description

The 528 departments (departamentos and partidos) of Argentina with their estimated population for 2022 and 2035 and the projected growth between both years. Department and province names are in Spanish, as in the official sources.

Usage

ar_departments

Format

An sf object with 528 rows and 7 columns:

id

Five-digit INDEC department code.

department

Department name.

province

Province name.

pop_2022

Estimated population, 2022.

pop_2035

Projected population, 2035.

growth

Projected population growth 2022-2035, in percent.

geometry

Department boundaries (WGS 84).

Source

• Geometries: Instituto Geográfico Nacional, via the Georef service of datos.gob.ar (CC BY 4.0), https://infra.datos.gob.ar/georef/departamentos.geojson.

• Population: INDEC, Estimaciones de población por sexo, departamento y año calendario 2022-2035, https://www.indec.gob.ar/ftp/cuadros/poblacion/base_estimaciones_pob_deptos_2022_2035.csv.

The "Islas del Atlántico Sur" department is not included because it has no population estimates.

---

Texts for the context components

Description

Returns the texts used by add_view_summary(), add_view_ranking(), add_context_tooltip() and add_feature_search(). Start from English or Spanish and override any text through ....

Usage

context_labels(lang = c("en", "es"), ...)

view_summary_labels(lang = c("en", "es"), ...)

Arguments

lang	Base language: "en" (English) or "es" (Spanish).
...	Texts to override, by name. Common: of, above, below, same, points, empty, go_to, collapse, expand. View summary: title, whole_map, average, median, sum, overall, highest, lowest, share, view, all. Ranking: ranking_highest, ranking_lowest, in_view, rank_overall. Context tooltip: rank, higher_than, average_of_all. Search: search_placeholder, search_none. Area: area_zoom_in.

Details

view_summary_labels() is the same function under its earlier name.

Value

A list of class context_labels.

Examples

context_labels("es")
context_labels("en", title = "Visible now")

---

Earthquakes in southern South America

Description

The 2,569 earthquakes of magnitude 4.5 or more recorded between 2016 and 2025 in southern South America (latitudes 20°S to 56°S, longitudes 76°W to 52°W). Earthquakes get deeper from west to east, following the Nazca plate as it sinks under South America.

Usage

earthquakes

Format

An sf object with 2,569 points and 6 columns:

id

USGS event id.

date

Date (UTC).

magnitude

Magnitude.

depth

Depth in kilometres.

place

Description of the location, as given by the USGS.

geometry

Epicentre (WGS 84).

Source

U.S. Geological Survey (USGS) Earthquake Catalog, public domain, https://earthquake.usgs.gov/earthquakes/search/.

---

Five prefectures of Japan: a shrinking, ageing population

Description

Five prefectures of Japan, from north to south (Hokkaido, Akita, Tokyo, Kyoto and Okinawa), with their population in 2020 (census) and 2024 (official estimate), the change between both years and the share of people aged 65 and over in 2024. Tokyo is the only one that grew; in Akita almost 40% of people are 65 or older.

Usage

jp_prefectures

Format

An sf object with 5 rows and 7 columns:

code

Official prefecture code (JIS X 0401).

prefecture

Prefecture name.

pop_2020

Population, 2020 census.

pop_2024

Population, 2024 estimate, rounded to thousands.

change

Population change 2020-2024, in percent.

aged_65

Share of the population aged 65 and over in 2024, in percent.

geometry

Prefecture boundaries (WGS 84).

Source

• Population: Statistics Bureau of Japan, Japan Statistical Yearbook 2026, tables 2-3 and 2-7, https://www.stat.go.jp/english/data/nenkan/. Created by editing those tables. Terms of use compatible with CC BY 4.0: https://www.e-stat.go.jp/en/terms-of-use.

• Boundaries: Natural Earth 1:10m Admin 1 states and provinces, public domain, https://www.naturalearthdata.com/.

---