mapper: Plots data onto a map
In toponym: Analyze and Visualize Toponyms

mapper

R Documentation

Plots data onto a map

Description

This function plots a user-specific data frame onto a map.

Usage

mapper(mapdata, ...)

Arguments

mapdata

data frame. A user-specific data frame with coordinates.

...

Additional parameters:

color character string vector indicating, which color is assigned to each string. It is prioritized over colors based on the column color.
regions numeric. Specifies the level of administrative borders. By default 0 for displaying only country borders.
title character string. Text for the title of the plot.
legend_title character string. Text for the title of the legend. It is prioritized over titles based on column group.
show_legend logical. If TRUE, a legend with all unique strings in the column group will be displayed, provided there is a column group. If FALSE, no legend will be displayed. By default, TRUE.
frame data frame. Sets the frame of the map.
plot_size numeric. Specifies the value by which the size of the map is scaled.
toponym_path character string. Path name for downloaded data.

Details

This function's purpose is to allow users to provide data frames by the function top(), edited ones as well as own data frames.

The data frame must have at least two columns called latitude & longitude.

Data frames output by the function top() consist of, among others, a latitude, longitude, ⁠country code⁠ and group column.

If the input data frame has a column color, the function will assign every value in that column to the respective coordinates. However, if specified, the additional parameter color will be used instead of the column color (see above).

If the input data frame has a column group, the function will group data and display a legend.

If the input data frame has a color and a group column, the assignment must match each other. Every group (every unique string in that column) must be assigned a unique color throughout the data frame.

If regions is set to a value greater than 0, the data frame must have a column ⁠country code⁠.

Parameter frame accepts data frames containing coordinates which define the frame of the plot. The data frame must have a column called latitude & a column called longitude. The latitudinal and longitudinal ranges define the frame of the plot.

Parameter plot_size accepts numeric values of greater than -1. The plot's size is scaled by the given value. Thus, a value of 0 extends the size by 0%. A value of .1 extends the size by 10%. A value of -.1 reduces the size by 10% and so on.

Parameter toponym_path accepts "pkgdir" for the package directory or a full, alternative path. With toponymOptions(), users can specify the path for toponym and map data downloaded by this package across sessions. See help(toponymOptions).

Value

A plot.

Examples

## We recommend setting a persistent path for downloaded data by using toponymOptions()
## Users can always set the path manually when a function is used
## For illustration purposes,
## 1. the path is manually set each time
## 2. and wrapped in donttest because data will be downloaded in the following examples:

mapper(
top("itz$", "DE", toponym_path = tempdir()),
toponym_path = tempdir())
# returns a plot with all populated places
# in Germany ending in "itz"


UG_data <- top(c("et$", "wa$"), "UG", toponym_path = tempdir())
UG_data$color <- "blue"
UG_data[UG_data$group == "wa", "color"] <- "grey"
mapper(UG_data,
      legend_title = "two strings",
      title = "Some locations in grey and blue",
      toponym_path = tempdir())
# returns a plot with all populated places
# in Uganda ending in "wa" (grey) and "et" (blue)
# the plot is titled "Some locations in grey and blue"
# the legend title is "two strings"

toponym documentation built on April 13, 2026, 5:06 p.m.