Package {mapsf}

Title:	Thematic Cartography
Version:	1.2.0
Description:	Create and integrate thematic maps in your workflow. This package helps to design various cartographic representations such as proportional symbols, choropleth or typology maps. It also offers several functions to display layout elements that improve the graphic presentation of maps (e.g. scale bar, north arrow, title, labels). 'mapsf' maps 'sf' objects on 'base' graphics.
License:	GPL (≥ 3)
URL:	https://riatelab.github.io/mapsf/
BugReports:	https://github.com/riatelab/mapsf/issues/
Depends:	R (≥ 3.6.0)
Imports:	classInt, graphics, maplegend (≥ 0.6.3), s2, sf, stats, utils, grDevices
Suggests:	terra, Ckmeans.1d.dp, png, jpeg, knitr, rmarkdown, svglite, tinytest, covr
Encoding:	UTF-8
RoxygenNote:	7.3.3
VignetteBuilder:	knitr
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-05-05 12:54:30 UTC; tim
Author:	Timothée Giraud [cre, aut], Hugues Pecout [ctb] (Logo), Ronan Ysebaert [ctb] (Cheat sheet), Elina Marveaux [ctb] (Themes), Ian Fellows [cph] (No overlap algorithm for labels, from wordcloud package), Jim Lemon [cph] (Arc drawing algorithm for annotations, from plotrix package), Danielle Navarro [cph] (Bézier curve algorithm for text annotations)
Maintainer:	Timothée Giraud <timothee.giraud@cnrs.fr>
Repository:	CRAN
Date/Publication:	2026-05-05 13:30:02 UTC

Package description

Description

Create and integrate thematic maps in your workflow. This package helps to design various cartographic representations such as proportional symbols, choropleth or typology maps. It also offers several functions to display layout elements that improve the graphic presentation of maps (e.g. scale bar, north arrow, title, labels). mapsf maps sf objects on base graphics.

A "Get Started" vignette contains commented scripts on how to create various maps: vignette(topic = "mapsf", package = "mapsf")

Symbology

These functions display cartographic layers.

• mf_map() Plot a map

• mf_label() Plot labels

• mf_raster() Plot a raster

• mf_graticule() Plot graticules

Map layout

These functions are dedicated to the map layout design.

• mf_theme() Set a theme

• mf_shadow() Plot a shadow

• mf_background() Plot a background image

• mf_annotation() Plot an annotation

• mf_arrow() Plot a north arrow

• mf_credits() Plot credits

• mf_layout() Plot a map layout

• mf_title() Plot a title

• mf_scale() Plot a scale bar

• mf_inset_on() / mf_inset_off() Plot an inset

• mf_worldmap() Plot a point on a world map

• mf_legend() Plot a legend

Utility functions

• mf_svg() Export a map in SVG file format

• mf_png() Export a map in SVG file format

• mf_distr() Plot a distribution

• mf_get_links() Get a link layer from a data.frame of links

• mf_get_pal() Get color palettes

• mf_get_breaks() Get class intervals

• mf_get_mtq() Get the 'mtq' dataset

• mf_get_ratio() Get map width and height values

• mf_get_pencil() Get a pencil layer from polygons

• mf_get_borders() Get a border layer from polygons

Author(s)

Maintainer: Timothée Giraud timothee.giraud@cnrs.fr (ORCID)

Other contributors:

• Hugues Pecout (ORCID) (Logo) [contributor]

• Ronan Ysebaert (ORCID) (Cheat sheet) [contributor]

• Elina Marveaux (ORCID) (Themes) [contributor]

• Ian Fellows (No overlap algorithm for labels, from wordcloud package) [copyright holder]

• Jim Lemon (Arc drawing algorithm for annotations, from plotrix package) [copyright holder]

• Danielle Navarro (ORCID) (Bézier curve algorithm for text annotations) [copyright holder]

See Also

Useful links:

• https://riatelab.github.io/mapsf/

• Report bugs at https://github.com/riatelab/mapsf/issues/

Deprecated functions in mapsf

Description

These functions and features still work but will be removed in the next major version of the package.

mf_map sub-functions

Instead of using the following deprecated functions, one can use mf_map with the corresponding type:

• mf_base() => mf_map_base

• mf_choro() => mf_map_choro

• mf_prop() => mf_map_prop

• mf_typo() => mf_map_typo

• mf_symb() => mf_map_symb

• mf_grad() => mf_map_grad

• mf_prop_typo() => mf_map_prop_typo

• mf_prop_choro() => mf_map_prop_choro

• mf_symb_choro() => mf_map_symb_choro

mf_init

mf_init is deprecated. It is possible to use mf_map instead (mf_map(x, type = "base", col = NA, border = NA).

It is also possible to use the extent argument of mf_map.

mf_export

mf_export is deprecated, use mf_png or mf_svg instead.

mf_annotation

mf_annotation is deprecated, use mf_text instead.

Double legends

The use of separated legends for map types prop_choro, prop_typo and symb_choro is deprecated. Use leg_pos = NA and mf_legend if separated legends are needed.

Theming system

In mf_theme, the following themes are deprecated: "default", "brutal", "ink", "dark", "agolalight", "candy", "darkula", "iceberg", "green", "nevermind", "jsk" and "barcelona".
The following arguments are also deprecated: "bg", "fg", "tab", "pos", "inner", "line", "cex" and "font".

Although the map theming system has been radically changed in version 1.0.0 of the package, you can still use the old themes by referencing them by name. If you need to use the pre v1.0.0 default theme, set x to "default".
If an old theme is set, only deprecated arguments are used and others are ignored.
If current and deprecated arguments are mixed, only deprecated arguments are used and others are ignored.
All references and usages of the old theming system will be removed in the next major version.

Deprecated - Plot an annotation

Description

This function is deprecated. Please use mf_text instead. instead.

Plot an annotation on a map.

Usage

mf_annotation(
  x,
  txt,
  pos = "topright",
  cex = 0.8,
  col_arrow,
  col_txt,
  halo = FALSE,
  bg,
  s = 1,
  ...
)

Arguments

Value

No return value, an annotation is displayed.

Note

Annotations cannot be displayed on unprojected (long/lat) maps.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_text(
  x = mtq[2, ],
  txt = "pos = 'bottomleft'\nline = 2\nclockwise = FALSE",
  pos = "bottomleft",
  offset = 6,
  clockwise = FALSE,
  line = 2,
  box = FALSE
)
mf_text(
  x = mtq[28, ],
  txt = "pos = 'topright'\nline = 3\nclockwise = FALSE",
  pos = "topright",
  offset = 10,
  clockwise = FALSE,
  line = 3,
  halo = TRUE,
  align = "left"
)

Plot a north arrow

Description

Plot a north arrow.

Usage

mf_arrow(pos = "topleft", col, cex = 1, adj = c(0, 0), align)

Arguments

Value

No return value, a north arrow is displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_arrow(pos = "topright")

Plot a background image

Description

Plot a background image on an existing plot

Usage

mf_background(filename, ...)

Arguments

Value

No return value, a background image is displayed.

Examples

if (require("jpeg")) {
  mtq <- mf_get_mtq()
  mf_map(mtq, col = NA, border = NA)
  mf_background(system.file("img/background.jpg", package = "mapsf"))
  mf_map(mtq, lwd = 3, col = NA, border = "white", add = TRUE)
  mf_credits(
    txt = "Background photo by Noita Digital on Unsplash",
    col = "white"
  )
}

Deprecated - Plot an sf object

Description

This function is deprecated. Please use mf_map() with type = "base" instead.

Plot an sf object. This is mostly a wrapper around plot(st_geometry(x), ...).

Usage

mf_base(
  x,
  col,
  border,
  alpha = NULL,
  cex = 1,
  pch = 20,
  lwd = 0.7,
  lty = 1,
  add = FALSE,
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  ...
)

Arguments

Value

x is (invisibly) returned.

Examples

library(sf)
mtq <- mf_get_mtq()
mf_map(mtq, type = "base")
mf_map(mtq, type = "base", col = "blue")

Deprecated - Plot a choropleth map

Description

This function is deprecated. Please use mf_map() with type = "choro" instead.

Plot a choropleth map

Usage

mf_choro(
  x,
  var,
  pal,
  alpha = NULL,
  rev = FALSE,
  breaks = "quantile",
  nbreaks,
  border,
  pch = 21,
  cex = 2,
  lwd = 0.7,
  col_na = "white",
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x),
  leg_title = var,
  leg_title_cex = 0.8,
  leg_val_cex = 0.6,
  leg_val_rnd = 2,
  leg_val_dec = ".",
  leg_val_big = "",
  leg_no_data = "No data",
  leg_frame = FALSE,
  leg_horiz = FALSE,
  leg_adj = c(0, 0),
  leg_size = 1,
  leg_box_border,
  leg_box_cex = c(1, 1),
  leg_fg,
  leg_bg,
  leg_frame_border,
  add = FALSE
)

Arguments

Details

Breaks defined by a numeric vector or a classification method are left-closed: breaks defined by c(2, 5, 10, 15, 20) will be mapped as [2 - 5[, [5 - 10[, [10 - 15[, [15 - 20]. The "jenks" method is an exception and has to be right-closed. Jenks breaks computed as c(2, 5, 10, 15, 20) will be mapped as [2 - 5], ]5 - 10], ]10 - 15], ]15 - 20].

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq, var = "MED", type = "choro")

mtq[6, "MED"] <- NA
mf_map(
  x = mtq, var = "MED", type = "choro",
  col_na = "grey", pal = "Cividis",
  breaks = "quantile", nbreaks = 4, border = "white",
  lwd = .5, leg_pos = "topleft",
  leg_title = "Median Income", leg_title_cex = 1.1,
  leg_val_cex = 1, leg_val_rnd = -2, leg_no_data = "No data",
  leg_frame = TRUE
)

Plot credits

Description

Plot credits (sources, author, year...).

Usage

mf_credits(
  txt = "Source(s) & Author(s)",
  pos = "bottomleft",
  col,
  cex = 0.6,
  font = 3,
  bg = NA
)

Arguments

Value

No return value, credits are displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_credits(txt = "Author\nSources - Year")

Plot a distribution

Description

This function displays the statistical distribution of a variable with a histogram, a box plot, a strip chart and a density curve on the same plot.

This graphic can be useful to choose an appropriate classification method for choropleth maps.

User-defined class boundaries can also be displayed on the plot.

Usage

mf_distr(
  x,
  nbins,
  bw,
  breaks,
  pal,
  alpha = 1,
  rev = FALSE,
  main = "Distribution",
  yaxt = TRUE,
  ylab = "Density"
)

Arguments

Value

The number of bins of the histogram and the bandwidth of the density curve are (invisibly) returned in a list.

See Also

mf_map_choro

Examples

(mf_distr(rnorm(1000)))
mf_distr(rbeta(1000, .6, 7))
mf_distr(rbeta(1000, 5, .6))
a <- rbeta(1000, .6, 7)
bks <- mf_get_breaks(a, nbreaks = 5, breaks = "quantile")
mf_distr(a, breaks = bks)
mf_distr(a,
  breaks = bks, pal = "Teal", yaxt = FALSE,
  main = 'Classification method : "quantile"'
)

Deprecated - Export a map

Description

This function is deprecated. Please use mf_png or mf_svg instead.

Export a map with the extent of a spatial object.
The map is exported in PNG or SVG format.
If only one of width or height is set, mf_export uses the width/height ratio of x bounding box to find a matching ratio for the export.
Always use add = TRUE in mf_map calls following an mf_export call.
Use dev.off to finish the export (see Examples).

Usage

mf_export(
  x,
  filename = "map.png",
  width,
  height,
  res = 96,
  ...,
  expandBB = rep(0, 4)
)

Arguments

Value

No return value, a map file is initiated (in PNG or SVG format).

Examples

mtq <- mf_get_mtq()
(filename <- tempfile(fileext = ".png"))
mf_png(mtq, filename = filename)
mf_map(mtq)
mf_title()
dev.off()

Plot a frame

Description

Plot a frame around an existing map.

Usage

mf_frame(extent = "map", col, lwd = 1.5, lty = 1, ...)

Arguments

Value

No return value, a frame is displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_title()
mf_frame(extent = "map")
mf_map(mtq)
mf_title()
mf_frame(extent = "figure")

Get a border layer from polygons

Description

This function extracts borders between contiguous polygons.

Usage

mf_get_borders(x)

Arguments

Value

An sf object (MULTILINESTRING) of borders is returned.

Note

If the polygon layer contains topology errors (such as contiguous polygons not sharing exactly the same boundary) the function may not return all boundaries correctly. It is possible to use st_snap() or other functions to try and correct these errors.

Examples

mtq <- mf_get_mtq()
mtq_b <- mf_get_borders(mtq)
mf_map(mtq)
mf_map(mtq_b, col = 1:5, lwd = 4, add = TRUE)

Get class intervals

Description

A function to classify continuous variables.

This function is a wrapper for classIntervals with some additional methods.

Usage

mf_get_breaks(x, nbreaks, breaks, k = 1, central = FALSE, ...)

Arguments

Details

classInt methods

"fixed", "sd", "equal", "pretty", "quantile", "kmeans", "hclust", "bclust", "fisher", "jenks", "dpih", "headtails", "maximum", and "box" are classIntervals methods. You may need to pass additional arguments for some of them.

Natural breaks method

The "jenks", "fisher" and "ckmeans" methods are based on the same concept of natural breaks and and produce similar groupings. The use of "ckmeans" is recommended.

• The "jenks" method produces class boundaries falling on data points and is slow.

• The "fisher" method produces class boundaries located more conveniently between data points, and is faster than the "jenks" method.

• The "ckmeans" method produces exactly the same class boundaries as the "fisher" method, but is much faster. It uses the optimal univariate k-means method from the Ckmeans.1d.dp package. If the "ckmeans" method is selected but the Ckmeans.1d.dp package is not installed then the "fisher" method is used.

The relative speeds of these three methods may vary depending on the number of data points and the number of classes.

Other methods

The "msd" method is based on the mean and the standard deviation of a numeric vector. The nbreaks parameter is not relevant, use k and central instead. k indicates the extent of each class in share of standard deviation. If central=TRUE then the mean value is the center of a class else the mean is a break value.

The "q6" method uses the following quantile probabilities: 0, 0.05, 0.275, 0.5, 0.725, 0.95, 1.

The "Q6" method uses the following quantile probabilities: 0, 0.05, 0.25, 0.5, 0.75, 0.95, 1.

The "geom" method is based on a geometric progression along the variable values, all values must be strictly greater than zero.

The "arith" method is based on an arithmetic progression along the variable values.

The "em" method is based on nested averages computation.

Class boundaries

Breaks defined by a numeric vector or a classification method are left-closed: breaks defined by c(2, 5, 10, 15, 20) will be mapped as [2 - 5[, [5 - 10[, [10 - 15[, [15 - 20].

Value

A numeric vector of breaks

See Also

classIntervals

Examples

mtq <- mf_get_mtq()
mf_get_breaks(x = mtq$MED, nbreaks = 6, breaks = "quantile")

Get the optimal position of a legend

Description

Find the optimal for one or two legends. The optimal position is a position that minimizes overlap between a spatial object and a legend.

Usage

mf_get_leg_pos(x, n = 1)

Arguments

Value

A vector of position is returned

Examples

mtq <- mf_get_mtq()
mf_get_leg_pos(mtq)

Get a link layer from a data.frame of links

Description

Create a link layer from a data.frame of links and an sf object.

Usage

mf_get_links(x, df, x_id, df_id)

Arguments

Value

An sf object is returned, it is composed of df and the sfc (LINESTRING) of links.

Examples

mtq <- mf_get_mtq()
mob <- read.csv(system.file("csv/mob.csv", package = "mapsf"))
# Select links from Fort-de-France (97209))
mob_97209 <- mob[mob$i == 97209, ]
# Create a link layer
mob_links <- mf_get_links(x = mtq, df = mob_97209)
# Plot the links
mf_map(mtq)
mf_map(mob_links, col = "red4", lwd = 2, add = TRUE)

Get the 'mtq' dataset

Description

Import the mtq dataset (Martinique municipalities).

Usage

mf_get_mtq(x = "polygons")

Arguments

Details

This a wrapper around st_read(system.file("gpkg/mtq.gpkg", package = "mapsf"), layer = x, quiet = TRUE).

For polygons (municipalities shapes) and points (municipalities centroids)

• INSEE_COM: Municipality identifier

• STATUS: Municipality administrative status

• LIBGEO: Municipality name

• POP: Total population, 2015

• MED: Median disposable income adjusted per equivalent household member, in euros, 2015

• CHOM: Unemployed population, 2015

• ACT: Active population, 2015

For lines (professional mobility flows from Fort-de-France to other municipalities)

• i: Municipality of residence identifier

• j: Municipality of workplace identifier

• fij: Flows of workers (employed population, 15 y.o. or more, 2015, only flows \> 100)

• sj: Administrative status of the workplace municipality

Value

an sf object

Source

For polygons (municipalities shapes) and points (municipalities centroids)

Base comparateur de territoires (data, upload date: 2018-09-25) & ADMIN EXPRESS-COG (geometry, 2018 edition).

Citation: Insee and IGN, 2018

For lines (professional mobility flows from Fort-de-France to other municipalities)

Flux de mobilité - déplacements domicile-lieu de travail (upload date: 2018-08-01)

Citation: Insee, 2018

Examples

mtq <- mf_get_mtq()

Get color palettes

Description

mf_get_pal builds sequential, diverging and qualitative color palettes. Diverging color palettes can be dissymmetric (different number of colors in each of the two gradients).

Usage

mf_get_pal(
  n,
  palette,
  alpha = NULL,
  rev = c(FALSE, FALSE),
  neutral,
  breaks,
  mid
)

Arguments

Value

A vector of colors.

Examples

cls <- mf_get_pal(n = c(3, 7), palette = c("Reds 2", "Greens"))
plot(1:10, rep(1, 10), bg = cls, pch = 22, cex = 4)
mtq <- mf_get_mtq()
bks <- mf_get_breaks(mtq$MED, breaks = "equal", nbreaks = 8)
pal <- mf_get_pal(
  breaks = bks, mid = 15000,
  palette = c("Dark Mint", "Burg"), neutral = "grey90"
)
mf_map(mtq, "MED", "choro", breaks = bks, pal = pal)
pal <- mf_get_pal(breaks = bks, mid = bks[4], palette = c("Dark Mint", "Burg"))
mf_map(mtq, "MED", "choro", breaks = bks, pal = pal)

Get a pencil layer from polygons

Description

Create a pencil layer. This function transforms a POLYGON or MULTIPOLYGON sf object into a MULTILINESTRING one.

Usage

mf_get_pencil(x, size = 100, buffer = 0, lefthanded = TRUE, clip = FALSE)

Arguments

Value

A MULTILINESTRING sf object is returned.

Examples

mtq <- mf_get_mtq()
mtq_pencil <- mf_get_pencil(x = mtq, clip = FALSE)
mf_map(mtq)
mf_map(mtq_pencil, add = TRUE)

Get map width and height values

Description

This function is to be used to get width and height values for maps created in reports (*.Rmd, *.qmd).
It uses the width / height ratio of a spatial object bounding box to find a matching ratio for the map.
If width is specified, then height is deduced from the width / height ratio of x, figure margins and title size.
If height is specified, then width is deduced from the width / height ratio of x, figure margins and title size.

Usage

mf_get_ratio(x, width, height, expandBB = rep(0, 4), theme = mf_theme())

Arguments

Value

Width and height are returned in inches.

Examples

mtq <- mf_get_mtq()
mf_get_ratio(x = mtq, width = 5)

Deprecated - Plot graduated symbols

Description

This function is deprecated. Please use mf_map() with type = "grad" instead.

Plot graduated symbols based on quantitative data.

Usage

mf_grad(
  x,
  var,
  breaks = "quantile",
  nbreaks = 3,
  col,
  alpha = NULL,
  border,
  pch = 21,
  cex,
  lwd,
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x),
  leg_title = var,
  leg_title_cex = 0.8,
  leg_val_cex = 0.6,
  leg_val_rnd = 0,
  leg_val_dec = ".",
  leg_val_big = "",
  leg_frame = FALSE,
  leg_adj = c(0, 0),
  leg_size = 1,
  leg_box_cex = c(1, 1),
  leg_fg,
  leg_bg,
  leg_frame_border,
  add = TRUE
)

Arguments

Details

Breaks defined by a numeric vector or a classification method are left-closed: breaks defined by c(2, 5, 10, 15, 20) will be mapped as [2 - 5[, [5 - 10[, [10 - 15[, [15 - 20]. The "jenks" method is an exception and has to be right-closed. Jenks breaks computed as c(2, 5, 10, 15, 20) will be mapped as [2 - 5], ]5 - 10], ]10 - 15], ]15 - 20].

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, "POP", "grad", pch = 22)

Plot graticules

Description

Display graticules and labels on a map.

Usage

mf_graticule(
  x,
  col,
  lwd = 1,
  lty = 1,
  expandBB = rep(0, 4),
  label = TRUE,
  pos = c("top", "left"),
  cex = 0.7,
  extent = x,
  bg,
  add = TRUE
)

Arguments

Value

An (invisible) layer of graticules is returned (LINESTRING).

Use of graticules

From sf::st_graticule(): "In cartographic visualization, the use of graticules is not advised, unless the graphical output will be used for measurement or navigation, or the direction of North is important for the interpretation of the content, or the content is intended to display distortions and artifacts created by projection. Unnecessary use of graticules only adds visual clutter but little relevant information. Use of coastlines, administrative boundaries or place names permits most viewers of the output to orient themselves better than a graticule."

Examples

mtq <- mf_get_mtq()
mf_map(mtq, expandBB = c(0, .1, .1, 0))
mf_graticule(mtq)

mf_graticule(
  x = mtq,
  col = "coral4",
  lwd = 2,
  lty = 2,
  expandBB = c(.1, 0, 0, .1),
  label = TRUE,
  pos = c("right", "bottom"),
  cex = .8,
  add = FALSE
)
mf_map(mtq, add = TRUE)

Deprecated - Initialize a map with a specific extent

Description

This function is deprecated. Please use mf_map(x, col = NA, border = NA) instead.

Plot an invisible layer with the extent of a spatial object.
Always use add = TRUE in mf_map() calls following an mf_init() call. This function is similar to mf_map(x, col = NA, border = NA).

Usage

mf_init(x, expandBB = rep(0, 4), extent = x, bgc)

Arguments

Value

No return value, a map is initiated.

Examples

mtq <- mf_get_mtq()
target <- mtq[30, ]
mf_map(target, type = "base", col = NA, border = NA)
mf_map(mtq, add = TRUE)
# or
mf_map(mtq, extent = target)

Plot an inset

Description

This function is used to add an inset map to the current map.

Usage

mf_inset_on(x, pos = "topright", cex = 0.2, fig)

mf_inset_off()

Arguments

Details

If x is used (with pos and cex), the width/height ratio of the inset will match the width/height ratio of x bounding box.
If fig is used, coordinates (xmin, xmax, ymin, ymax) are expressed as fractions of the mapping space (i.e. excluding margins).
If map layers have to be plotted after the inset (i.e after mf_inset_off()), please use add = TRUE.
It is not possible to plot an inset within an inset.
It is possible to plot anything (base plots) within the inset, not only map layers.

Value

No return value, an inset is initiated or closed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_inset_on(x = mtq[1, ], cex = .2)
mf_map(mtq[1, ])
mf_inset_off()

mf_map(mtq)
mf_inset_on(x = "worldmap", pos = "bottomleft")
mf_worldmap(x = mtq)
mf_inset_off()

mf_map(mtq)
mf_inset_on(fig = c(0, 0.25, 0, 0.25))
mf_map(x = mtq)
mf_inset_off()

Plot labels

Description

Put labels on a map.

Usage

mf_label(
  x,
  var,
  col,
  cex = 0.7,
  overlap = TRUE,
  lines = TRUE,
  halo = FALSE,
  bg,
  r = 0.1,
  q = 1,
  ...
)

Arguments

Value

No return value, labels are displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mtq$cex <- c(rep(.8, 8), 2, rep(.8, 25))
mf_label(
  x = mtq, var = "LIBGEO",
  col = "grey10", halo = TRUE, cex = mtq$cex,
  overlap = FALSE, lines = FALSE
)

Plot a map layout

Description

Plot a map layout (title, credits, scalebar, north arrow, frame).

This function uses mf_title, mf_credits, mf_scale and mf_arrow with default values.

Usage

mf_layout(
  title = "Map Title",
  credits = "Authors & Sources",
  scale = TRUE,
  arrow = TRUE,
  frame = FALSE
)

Arguments

Value

No return value, a map layout is displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_layout()

Plot a legend

Description

Plot different types of legend. The "type" argument defines the legend type. Please note that some arguments are available for all types of legend and some others are only relevant for specific legend types (see Details). mf_legend() is a wrapper for maplegend::leg().

Usage

mf_legend(
  type,
  val,
  pos = "left",
  pal = "Inferno",
  alpha = 1,
  col = "tomato4",
  inches = 0.3,
  val_max = NULL,
  symbol = "circle",
  self_adjust = FALSE,
  lwd = 0.7,
  border = "#333333",
  pch = seq_along(val),
  cex = rep(1, length(val)),
  title = "Legend Title",
  title_cex = 0.8 * size,
  val_cex = 0.6 * size,
  val_rnd = 0,
  val_dec = ".",
  val_big = "",
  col_na = "white",
  cex_na = 1,
  pch_na = 4,
  no_data = FALSE,
  no_data_txt = "No Data",
  box_border = "#333333",
  box_cex = c(1, 1),
  horiz = FALSE,
  frame_border,
  frame = FALSE,
  bg,
  fg,
  size = 1,
  return_bbox = FALSE,
  adj = c(0, 0)
)

Arguments

Details

Some arguments are available for all types of legend: val, pos, title, title_cex, val_cex, frame, bg, fg, size, adj, alpha, return_bbox).

Relevant arguments for each specific legend types:

• mf_legend(type = "prop", val, inches, val_max, symbol, col, lwd, border, val_rnd, val_big, val_dec, self_adjust, horiz)

• mf_legend(type = "choro", val, pal, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt, box_border, box_cex, horiz)

• mf_legend(type = "cont", val, pal, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt, box_border, box_cex, horiz)

• mf_legend(type = "typo", val, pal, col_na, no_data, no_data_txt, box_border, box_cex)

• mf_legend(type = "symb", val, pal, pch, cex, lwd, pch_na, cex_na, col_na, no_data, no_data_txt)

• mf_legend(type = "prop_line", val, col, lwd, val_rnd, val_big, val_dec)

• mf_legend(type = "grad_line", val, col, lwd, val_rnd, val_big, val_dec)

• mf_legend(type = "histo", val, pal, box_border, val_rnd, val_big, val_dec)

• mf_legend(type = "choro_point", val, pal, symbol, border, cex, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt, horiz)

• mf_legend(type = "choro_line", val, pal, lwd, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt)

• mf_legend(type = "choro_symb", val, pal, pch, lwd, val_rnd, val_big, val_dec, col_na, no_data, no_data_txt)

• mf_legend(type = "typo_line", val, pal, lwd, col_na, no_data, no_data_txt, box_cex)

Value

No value is returned, a legend is displayed (except if return_bbox is used).

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_legend(type = "prop", pos = "topright", val = c(1, 5, 10), inches = .3)
mf_legend(
  type = "choro", pos = "bottomright", val = c(10, 20, 30, 40, 50),
  pal = hcl.colors(4, "Reds 2")
)
mf_legend(
  type = "typo", pos = "topleft", val = c("A", "B", "C", "D"),
  pal = hcl.colors(4, "Dynamic")
)
mf_legend(
  type = "symb", pos = "bottomleft", val = c("A", "B", "C"),
  pch = 21:23, cex = c(1, 2, 2),
  pal = hcl.colors(3, "Dynamic")
)
mf_legend(
  type = "grad_line", pos = "top", val = c(1, 2, 3, 4, 10, 15),
  lwd = c(0.2, 2, 4, 5, 10)
)
mf_legend(type = "prop_line", pos = "bottom", lwd = 20, val = c(5, 50, 100))

Plot a logo on a map

Description

The logo can be a PNG or JPG/JPEG file.

Usage

mf_logo(filename, pos = "bottomright", cex = 1, adj = c(0, 0), resize = TRUE)

Arguments

Value

No return value, a logo is displayed.

Examples

m <- mf_get_mtq()
mf_map(m)
mf_scale()
logo <- system.file("img", "Rlogo.png", package = "png")
mf_logo(logo, pos = "bottomleft", adj = c(0, 4))
mf_credits()

Plot a map

Description

mf_map() is the main function of the package, it displays map layers on a georeferenced plot.

mf_map() has three main arguments:

• x, an sf object,

• var, the name(s) of a variable(s) to map,

• type, the map type.

Relevant arguments and default values are different for each map type and are described in dedicated help pages (see base, choro, typo, prop, prop_choro, prop_typo, symb, grad or symb_choro).

Usage

mf_map(x, var, type = "base",
       breaks, nbreaks, pal, alpha, rev, inches, val_max, symbol, col,
       lwd_max, val_order, pch, cex, border, lwd, col_na, cex_na, pch_na,
       expandBB, extent, bg, add,
       leg_pos, leg_title, leg_title_cex, leg_val_cex, leg_val_rnd,
       leg_val_dec, leg_val_big, leg_no_data, leg_frame, leg_frame_border,
       leg_horiz, leg_adj, leg_bg, leg_fg, leg_size,
       leg_box_border, leg_box_cex, ...)

Arguments

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
# basic examples
# type = "base"
mf_map(mtq)
# type = "prop"
mf_map(mtq)
mf_map(mtq, var = "POP", type = "prop")
# type = "choro"
mf_map(mtq, var = "MED", type = "choro")
# type = "typo"
mf_map(mtq, "STATUS", "typo")
# type = "symb"
mf_map(mtq)
mf_map(mtq, "STATUS", "symb")
# type = "grad"
mf_map(mtq)
mf_map(mtq, var = "POP", type = "grad")
# type = "prop_choro"
mf_map(mtq)
mf_map(mtq, var = c("POP", "MED"), type = "prop_choro")
# type = "prop_typo"
mf_map(mtq)
mf_map(mtq, var = c("POP", "STATUS"), type = "prop_typo")
# type = "symb_choro
mf_map(mtq)
mf_map(mtq, var = c("STATUS", "MED"), type = "symb_choro")

Plot a base map

Description

mf_map() can be used to display geographic layers (sf objects), using the default map type base.

Usage

For polygons:

mf_map(x, col, border, lwd = 0.7, lty = 1,
       alpha, expandBB, extent, bg, add = FALSE)

For points:

mf_map(x, col, border, pch = 20, cex = 1, lwd = 0.7,
       alpha, expandBB, extent, bg, add = FALSE)

For lines:

mf_map(x, col, lwd = .7, lty = 1,
       alpha, expandBB, extent, bg, add = FALSE)

Arguments

Value

x is (invisibly) returned.

See Also

mf_map()

Examples

mtq <- mf_get_mtq()
pts <- mf_get_mtq("points")
flows <- mf_get_mtq("lines")
mf_map(mtq, lty = 3)
mf_map(pts, col = "red", border = "white", pch = 21, add = TRUE)
mf_map(flows, col = "coral", lwd = 2, add = TRUE)

Plot a choropleth map

Description

With the choro map type, mf_map() displays a choropleth map.

In choropleth maps, areas are shaded according to the variation of a quantitative variable. They are used to represent ratios or indices.

Usage

For polygons:

mf_map(x, var, type = "choro",
       breaks = "quantile", nbreaks, pal, rev = FALSE,
       border, lwd = 0.7, col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

For points:

mf_map(x, var, type = "choro",
       breaks = "quantile", nbreaks, pal, rev = FALSE,
       border, pch = 21, cex = 2, lwd = 0.7, col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

For lines:

mf_map(x, var, type = "choro",
       breaks = "quantile", nbreaks, pal, rev = FALSE, lwd = .7,
       col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

Arguments

Value

x is (invisibly) returned.

See Also

mf_map(), mf_distr(), mf_get_breaks(), mf_get_pal()

Examples

mtq <- mf_get_mtq()
pts <- mf_get_mtq("points")
flows <- mf_get_mtq("lines")
# polygons
mtq[6, "MED"] <- NA
mf_map(
  x = mtq, var = "MED", type = "choro",
  col_na = "grey90", pal = "Cividis",
  breaks = "equal", nbreaks = 5, border = "white",
  lwd = .5, leg_pos = "topleft",
  leg_title = "Median Income", leg_title_cex = 1,
  leg_val_cex = .9, leg_val_rnd = -2, leg_no_data = "No data",
  leg_box_cex = c(0.5, 3), leg_box_border = NA, leg_frame = FALSE
)
# points
mf_map(mtq)
mf_map(
  x = pts, var = "MED", type = "choro",
  pch = 21, cex = 3, lwd = 1.2,
  pal = "Teal", border = "white",
  leg_horiz = FALSE, leg_val_big = " ",
  leg_val_rnd = -2, leg_pos = "topright",
  leg_frame = TRUE, add = TRUE
)
# lines
mf_map(mtq, extent = flows)
mf_map(
  x = flows, var = "fij", type = "choro",
  breaks = "equal", nbreaks = 3, add = TRUE,
  lwd = 5, pal = "Burg", leg_horiz = TRUE,
  leg_box_cex = c(.7, 1),
  leg_val_rnd = 0, leg_pos = "bottomleft"
)

Plot graduated symbols

Description

With the grad map type, mf_map() displays graduated symbols on a map.

Graduated symbols are based on classified quantitative variables.

For polygons, centroids are used to plot graduated symbols.

Usage

For polygons and points:

mf_map(x, var, type = "grad",
       breaks = "quantile", nbreaks = 3,
       col, border, lwd = 0.7, pch = 21, cex,
       alpha, expandBB, extent, bg, add = TRUE, leg_*)

For lines:

mf_map(x, var, type = "grad",
       breaks = "quantile", nbreaks = 3,
       col, lwd,
       alpha, expandBB, extent, bg, add = TRUE, leg_*)

Arguments

Value

x is (invisibly) returned.

See Also

mf_map()

Examples

mtq <- mf_get_mtq()
flows <- mf_get_mtq("lines")
mf_map(mtq, bg = "cornsilk2")
mf_map(flows, "fij", "grad",
  breaks = "geom", nbreaks = 3,
  lwd = c(1, 3, 7),
  leg_title = "N. commuters",
  leg_pos = "bottomleft", leg_val_rnd = 0
)
mf_map(mtq, "POP", "grad",
  breaks = c(686, 5000, 25000, 82502),
  cex = c(1, 2, 4), pch = 22, col = "steelblue",
  leg_title = "Population", leg_pos = "topright",
  leg_frame = TRUE
)

Plot proportional symbols

Description

With the prop map type, mf_map() displays symbols (squares or circles) with areas proportional to a quantitative variable (stocks).

For polygons, centroids are used to plot proportional symbols.

Usage

For polygons and points:

mf_map(x, var, type = "prop",
       inches = 0.3, val_max, symbol, col, border, lwd,
       expandBB, extent, bg, alpha, add = FALSE, leg_*)

For lines:

mf_map(x, var, type = "prop",
       val_max, lwd_max = 20, col,
       expandBB, extent, bg, alpha, add = FALSE, leg_*)

Arguments

Value

x is (invisibly) returned.

See Also

mf_map()

Examples

mtq <- mf_get_mtq()
flows <- mf_get_mtq("lines")
mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, "POP", "prop",
  inches = .4, leg_title = "Population",
  leg_pos = "topright"
)
mf_map(flows, "fij", "prop",
  lwd_max = 10, col = "steelblue2",
  leg_pos = "right"
)

Plot proportional symbols with choropleth coloration

Description

mf_map() with prop_choro type creates symbols that are proportional to values of a first variable and colored to reflect the classification of a second variable.

This map types uses two variables and some arguments need to be set for both variables (see Details).

For polygons, centroids are used to plot proportional symbols. This map type is not available for lines.

Usage

For polygons and points:

mf_map(x, var, type = "prop_choro",
       inches = 0.3, val_max,  symbol = "circle",
       pal, rev = FALSE, breaks = "quantile", nbreaks,
       border, lwd = 0.7, col_na = "white",
       alpha, expandBB, extent, bg, add = TRUE, leg_*)

Arguments

Details

Legend arguments that need two values are: 'leg_title', 'leg_val_rnd', and 'leg_horiz'. The first values refers to the proportional symbols legend, the second one to the choropleth legend.

Value

x is (invisibly) returned.

See Also

mf_map(), mf_map_prop, mf_map_choro, mf_distr(), mf_get_breaks(), mf_get_pal()

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mtq[6, "MED"] <- NA
mf_map(
  x = mtq, var = c("POP", "MED"), type = "prop_choro",
  inches = .2,
  val_max = 90000, symbol = "circle",
  col_na = "grey90", pal = "Cividis",
  breaks = "msd", nbreaks = 4, lwd = 1,
  leg_pos = "topright",
  leg_title = c("Population", "Median Income"),
  leg_val_rnd = c(0, 1),
  leg_horiz = c(TRUE, FALSE),
  leg_title_cex = .9,
  leg_val_dec = ",",
  leg_val_cex = .8,
  leg_size = 1,
  add = TRUE
)

Plot proportional symbols with typology coloration

Description

mf_map() with prop_typo type creates symbols that are proportional to values of a first variable and colored to reflect the modalities of a second qualitative variable.

This map types uses two variables and some arguments need to be set for both variables (see Details).

For polygons, centroids are used to plot proportional symbols.

Usage

For polygons and points:

mf_map(x, var, type = "prop_typo",
       inches = 0.3, val_max, symbol, border,
       pal, rev = FALSE, val_order,
       border, lwd = 0.7, col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

For lines:

mf_map(x, var, type = "typo",
       lwd_max = 15,
       pal, rev = FALSE, val_order,
       col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

Arguments

Details

'leg_title' needs two values. The first value refers to the symbols legend, the second one to the choropleth legend.

Value

x is (invisibly) returned.

See Also

mf_map(), mf_map_prop, mf_map_typo, mf_get_pal()

Examples

mtq <- mf_get_mtq()
flows <- mf_get_mtq("lines")
mf_map(mtq, extent = flows, expandBB = c(0, .5, 0, 0))
mf_map(flows, c("fij", "sj"), "prop_typo",
  val_order = c("Sub-prefecture", "Simple municipality"),
  pal = c("steelblue", "lightblue"), lwd_max = 30,
  leg_pos = "topleft", leg_title = c("commuters", "destination")
)
mf_map(
  x = mtq, var = c("POP", "STATUS"), type = "prop_typo",
  inches = .2, border = "tomato4", lwd = 1,
  pal = c("darkblue", "steelblue", "lightblue"),
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality"),
  leg_pos = "bottomleft",
  leg_title = c("Population", ""),
  leg_no_data = "No dada",
  add = TRUE
)

Plot symbols

Description

mf_map() can use symbols to display qualitative data, using symb map type.

For polygons, centroids are used to plot graduated symbols. This map type is not available for lines.

Usage

For polygons and points:

mf_map(x, var, type = "symb",
       pch, cex = 2, lwd = 0.7, pal, rev = FALSE, border,
       val_order,
       col_na = "grey", pch_na = 4, cex_na = 1,
       alpha, expandBB, extent, bg, add = TRUE, leg_*)

Arguments

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mtq$STATUS[3] <- NA
mf_map(mtq)
mf_map(mtq, "STATUS", "symb",
  pal = "Berlin", border = "white", lwd = 1,
  cex = c(4, 3, 2), pch = c(21:23), col_na = "red",
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality"),
  leg_title = ""
)

Plot symbols with choropleth coloration

Description

mf_map() with symb_choro type creates symbols that reflect modalities of a first qualitative variable and colored to reflect the classification of a second variable.

This map types uses two variables and some arguments need to be set for both variables (see Details).

For polygons, centroids are used to plot symbols. This map type is not available for lines.

Usage

For polygons and points:

mf_map(x, var, type = "symb_choro",
       pch, cex = 2, lwd = 0.7, border, val_order,
       pal, rev = FALSE, breaks = "quantile", nbreaks,
       pch_na = 4, cex_na = 1, col_na = "white",
       alpha, expandBB, extent, bg, add = TRUE, leg_*)

Arguments

Details

Legend arguments that need two values are: 'leg_title', 'leg_no_data'. The first value refers to the symbols legend, the second one to the choropleth legend.

Value

x is (invisibly) returned.

See Also

mf_map(), mf_map_symb, mf_map_choro, mf_distr(), mf_get_breaks(), mf_get_pal()

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mtq$STATUS[4] <- NA
mf_map(mtq, c("STATUS", "MED"),
  type = "symb_choro", lwd = 1,
  pal = "Reds 3", breaks = "quantile", nbreaks = 4,
  cex = c(2, 1, 1), pch = c(20, 21, 23), pch_na = 22,
  leg_pos = "topright", border = "white",
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality")
)

Plot a typology map

Description

With the typo map type, mf_map() displays a typology map.

In typology maps, areas are shaded according to the modalities of a qualitative variable.

Usage

For polygons:

mf_map(x, var, type = "typo",
       pal, rev = FALSE, val_order,
       border, lwd = 0.7, col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

For points:

mf_map(x, var, type = "typo",
       pal, rev = FALSE, val_order,
       border, pch = 21, cex = 2, lwd = 0.7, col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

For lines:

mf_map(x, var, type = "typo",
       pal, rev = FALSE, val_order, lwd = .7,
       col_na = "white",
       alpha, expandBB, extent, bg, add = FALSE, leg_*)

Arguments

Value

x is (invisibly) returned.

See Also

mf_map(), mf_get_pal()

Examples

mtq <- mf_get_mtq()
pts <- mf_get_mtq("points")
flows <- mf_get_mtq("lines")
# polygons
mtq[6, "STATUS"] <- NA
mf_map(
  x = mtq, var = "STATUS", type = "typo",
  col_na = "grey90", border = "white",
  pal = c("#FFE93F", "#00214E", "#7C7C7C"),
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality"),
  lwd = .5, leg_pos = "bottomleft",
  leg_title = "", leg_title_cex = 1,
  leg_val_cex = .9, leg_no_data = "No data",
  leg_box_cex = c(0.5, 3), leg_box_border = NA
)
# points
mf_map(
  x = pts, var = "STATUS", type = "typo",
  cex = 3, pal = "Dark 3", border = "grey",
  leg_pos = "bottomleft"
)
# lines
mf_map(mtq, extent = flows)
mf_map(
  x = flows, var = "sj", type = "typo",
  add = TRUE,
  lwd = 2, pal = c("red", "blue"),
  leg_pos = "bottomleft"
)

Export a map in PNG format

Description

Export a map with the extent of a spatial object in PNG format.

PNG is a raster graphics file format and PNG export should be used for maps that do not require further modification.

If width is specified, then height is deduced from the width/height ratio of x. Alternatively, if height is specified, then width is deduced from the width/height ratio of x. This helps to produce maps without too much wasted space.

Use dev.off() to finish the export (see Examples).

Usage

mf_png(
  x,
  filename = "map.png",
  width,
  height,
  expandBB = rep(0, 4),
  res = 96,
  ...
)

Arguments

Value

No return value, a PNG device is initiated.

Examples

mtq <- mf_get_mtq()
(filename <- tempfile(fileext = ".png"))
mf_png(mtq, filename = filename)
mf_map(mtq)
mf_title()
dev.off()

Deprecated - Plot proportional symbols

Description

This function is deprecated. Please use mf_map() with type = "prop" instead.

Plot proportional symbols.

Usage

mf_prop(
  x,
  var,
  inches = 0.3,
  val_max,
  lwd_max = 20,
  symbol = "circle",
  col,
  alpha = NULL,
  border,
  lwd = 0.7,
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x),
  leg_title = var,
  leg_title_cex = 0.8,
  leg_val_cex = 0.6,
  leg_val_rnd = 0,
  leg_val_dec = ".",
  leg_val_big = "",
  leg_frame = FALSE,
  leg_frame_border,
  leg_horiz = FALSE,
  leg_adj = c(0, 0),
  leg_fg,
  leg_bg,
  leg_size = 1,
  add = TRUE
)

Arguments

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, "POP", "prop")

mf_map(mtq)
mf_map(
  x = mtq, var = "POP", type = "prop",
  inches = .4, symbol = "circle", val_max = 90000,
  col = "tomato1", border = "blue", lwd = 1,
  leg_pos = "right", leg_title = "Population",
  leg_title_cex = 1, leg_val_cex = .8, leg_val_rnd = 0,
  leg_frame = TRUE, add = TRUE
)

Deprecated - Plot proportional symbols using choropleth coloration

Description

This function is deprecated. Please use mf_map() with type = "prop_choro" instead.

Plot proportional symbols with colors based on a quantitative data classification.

Usage

mf_prop_choro(
  x,
  var,
  inches = 0.3,
  val_max,
  symbol = "circle",
  pal,
  alpha = NULL,
  rev = FALSE,
  breaks = "quantile",
  nbreaks,
  border,
  lwd = 0.7,
  col_na = "white",
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x, 1),
  leg_title = var,
  leg_title_cex = c(0.8, 0.8),
  leg_val_cex = c(0.6, 0.6),
  leg_val_rnd = c(0, 2),
  leg_val_dec = ".",
  leg_val_big = "",
  leg_no_data = "No data",
  leg_frame = c(FALSE, FALSE),
  leg_frame_border,
  leg_horiz = c(FALSE, FALSE),
  leg_adj = c(0, 0),
  leg_fg,
  leg_bg,
  leg_size = 1,
  leg_box_border,
  leg_box_cex = c(1, 1),
  add = TRUE
)

Arguments

Details

Breaks defined by a numeric vector or a classification method are left-closed: breaks defined by c(2, 5, 10, 15, 20) will be mapped as [2 - 5[, [5 - 10[, [10 - 15[, [15 - 20]. The "jenks" method is an exception and has to be right-closed. Jenks breaks computed as c(2, 5, 10, 15, 20) will be mapped as [2 - 5], ]5 - 10], ]10 - 15], ]15 - 20].

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, c("POP", "MED"), "prop_choro")

mf_map(mtq)
mtq[6, "MED"] <- NA
mf_map(
  x = mtq, var = c("POP", "MED"), type = "prop_choro",
  inches = .35, border = "tomato4",
  val_max = 90000, symbol = "circle", col_na = "grey", pal = "Cividis",
  breaks = "equal", nbreaks = 4, lwd = 4,
  leg_pos = "bottomright",
  leg_title = c("Population", "Median Income"),
  leg_title_cex = 1,
  leg_val_cex = .9,
  leg_val_rnd = c(0, 0),
  leg_no_data = "No data",
  leg_frame = TRUE,
  add = TRUE
)

Deprecated - Plot proportional symbols using typology coloration

Description

This function is deprecated. Please use mf_map() with type = "prop_typo" instead.

Plot proportional symbols with colors based on qualitative data.

Usage

mf_prop_typo(
  x,
  var,
  inches = 0.3,
  val_max,
  symbol = "circle",
  pal,
  alpha = NULL,
  rev = FALSE,
  val_order,
  border,
  lwd = 0.7,
  lwd_max = 15,
  col_na = "white",
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x, 1),
  leg_title = var,
  leg_title_cex = c(0.8, 0.8),
  leg_val_cex = c(0.6, 0.6),
  leg_val_rnd = 0,
  leg_val_dec = ".",
  leg_val_big = "",
  leg_no_data = "No data",
  leg_frame = c(FALSE, FALSE),
  leg_frame_border,
  leg_horiz = FALSE,
  leg_adj = c(0, 0),
  leg_fg,
  leg_bg,
  leg_size = 1,
  leg_box_border,
  leg_box_cex = c(1, 1),
  add = TRUE
)

Arguments

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, c("POP", "STATUS"), "prop_typo")

mtq[6, "STATUS"] <- NA
mf_map(mtq)
mf_map(
  x = mtq, var = c("POP", "STATUS"), type = "prop_typo",
  inches = .35, border = "tomato4",
  val_max = 90000, symbol = "circle", col_na = "grey", pal = "Dynamic",
  lwd = 2,
  leg_pos = "bottomright",
  leg_title = c("Population", "Municipality\nstatus"),
  leg_title_cex = 0.9,
  leg_val_cex = .7,
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality"),
  leg_no_data = "No dada",
  leg_frame = TRUE,
  add = TRUE
)

Plot a raster

Description

Plot a raster object (SpatRaster from terra).

Usage

mf_raster(
  x,
  type,
  nbreaks,
  breaks = "equal",
  val_order,
  pal,
  alpha = NULL,
  rev = FALSE,
  expandBB = rep(0, 4),
  bg,
  leg_pos = "right",
  leg_title = names(x),
  leg_title_cex = 0.8,
  leg_val_cex = 0.6,
  leg_val_rnd = 1,
  leg_val_dec = ".",
  leg_val_big = "",
  leg_frame = FALSE,
  leg_frame_border,
  leg_horiz = FALSE,
  leg_adj = c(0, 0),
  leg_box_border,
  leg_box_cex = c(1, 1),
  leg_fg,
  leg_bg,
  leg_size = 1,
  add = FALSE,
  ...
)

Arguments

Value

x is (invisibly) returned.

Examples

if (require("terra")) {
  # multi band
  logo <- rast(system.file("ex/logo.tif", package = "terra"))
  mf_raster(logo)

  # one band
  elev <- rast(system.file("ex/elev.tif", package = "terra"))

  ## continuous
  mf_raster(elev)
  mf_raster(elev,
    pal = "Burg", expandBB = c(.2, 0, 0, 0),
    leg_pos = "bottom", leg_horiz = TRUE
  )

  ## continuous with colors and breaks
  mf_raster(elev,
    type = "continuous",
    breaks = c(141, 400, 547),
    pal = c("darkseagreen1", "black", "red")
  )

  ## interval
  mf_raster(elev,
    type = "interval",
    nbreaks = 5, breaks = "equal", pal = "Teal"
  )

  ## classes
  elev2 <- classify(elev, c(140, 400, 450, 549))
  lev_evel <- data.frame(ID = 0:2, elevation = c("Low", "High", "Super High"))
  levels(elev2) <- lev_evel
  mf_raster(elev2)
  mf_raster(elev2,
    pal = c("salmon4", "olivedrab", "yellow3"),
    val_order = c("Super High", "High", "Low")
  )
}

Plot a scale bar

Description

Plot a scale bar.

Usage

mf_scale(
  size,
  pos = "bottomright",
  lwd = 1.5,
  cex = 0.6,
  col,
  crs_units = "m",
  scale_units = "km",
  adj = c(0, 0),
  x
)

Arguments

Details

Most CRS use the meter as unit. Some US CRS use feet or US survey feet. If unsure of the unit used in the CRS you can use the x argument of the function. Alternatively, you can use sf::st_crs(zz, parameters = TRUE)$units_gdal to see which units are used in the zz layer.

The scale bar cannot be displayed on unprojected (long/lat) maps or on maps without documented CRS.

Value

No return value, a scale bar is displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_scale()

library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"))[1, ]

nc_foot <- st_transform(nc, 2264) # NC state plane, US foot
mf_map(nc_foot)
mf_scale(size = 5, crs_units = "ft", scale_units = "mi")
mf_map(nc_foot)
mf_scale(size = 5, x = nc_foot, scale_units = "mi")

nc_meter <- st_transform(nc, 32119) # NC state plane, m
mf_map(nc_meter)
mf_scale(size = 5, crs_units = "m", scale_units = "mi")
mf_scale(size = 5, crs_units = "m", scale_units = "km", pos = "bottomleft")

Plot a shadow

Description

Plot the shadow of a polygon layer.

Usage

mf_shadow(
  x,
  col,
  cex = 1,
  add = FALSE,
  extent = x,
  bg,
  expandBB = rep(0.04, 4)
)

Arguments

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_shadow(mtq)
mf_map(mtq, add = TRUE)

Export a map in SVG format

Description

Export a map with the extent of a spatial object in SVG format.

SVG export is the perfect solution for editing maps with desktop vector graphics software. SVG is a vector graphics file format.

If width is specified, then height is deduced from the width/height ratio of x. Alternatively, if height is specified, then width is deduced from the width/height ratio of x. This helps to produce maps without too much wasted space.

Use 'dev.off() to finish the export (see Examples).

Usage

mf_svg(
  x,
  filename = "map.svg",
  width,
  height,
  expandBB = rep(0, 4),
  svglite = TRUE,
  ...
)

Arguments

Details

The default driver for building SVG files, grDevices::svg(), has limitations regarding speed, file size, editability, and font support. The svglite package aims to solve these issues but it is not lightweight in terms of dependencies, so it is not imported by mapsf, but rather suggested.

However, we strongly recommend its use if the aim is to edit the maps after export.

Value

No return value, an SVG device is initiated.

Examples

mtq <- mf_get_mtq()
(filename <- tempfile(fileext = ".svg"))
mf_svg(mtq, filename = filename)
mf_map(mtq)
mf_title()
dev.off()

Deprecated - Plot symbols

Description

This function is deprecated. Please use mf_map() with type = "symb" instead.

Plot symbols based on qualitative data.

Usage

mf_symb(
  x,
  var,
  pal,
  alpha = NULL,
  rev = FALSE,
  border,
  pch,
  cex = 2,
  lwd = 0.7,
  col_na = "grey",
  pch_na = 4,
  cex_na = 1,
  val_order,
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x),
  leg_title = var,
  leg_title_cex = 0.8,
  leg_val_cex = 0.6,
  leg_no_data = "No data",
  leg_frame = FALSE,
  leg_frame_border,
  leg_adj = c(0, 0),
  leg_fg,
  leg_bg,
  leg_size = 1,
  add = TRUE
)

Arguments

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, "STATUS", "symb")

mtq[6, "STATUS"] <- NA
mf_map(mtq)
mf_map(
  x = mtq, var = "STATUS", type = "symb",
  pch = c(21:23), pal = c("red1", "tan1", "khaki1"),
  border = "grey20", cex = c(1.5, 1, .9), lwd = .5,
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality"),
  pch_na = 24, leg_frame = TRUE
)

Deprecated - Plot symbols using choropleth coloration

Description

This function is deprecated. Please use mf_map() with type = "symb_choro" instead.

Plot symbols with colors based on a quantitative data classification.

Usage

mf_symb_choro(
  x,
  var,
  pal,
  alpha = NULL,
  rev = FALSE,
  breaks = "quantile",
  nbreaks,
  border,
  pch,
  cex = 2,
  lwd = 0.7,
  pch_na = 4,
  cex_na = 1,
  col_na = "white",
  val_order,
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x, 1),
  leg_title = var,
  leg_title_cex = c(0.8, 0.8),
  leg_val_cex = c(0.6, 0.6),
  leg_val_rnd = 2,
  leg_val_dec = ".",
  leg_val_big = "",
  leg_no_data = c("No data", "No data"),
  leg_frame = c(FALSE, FALSE),
  leg_frame_border,
  leg_horiz = FALSE,
  leg_adj = c(0, 0),
  leg_fg,
  leg_bg,
  leg_size = 1,
  leg_box_border,
  leg_box_cex = c(1, 1),
  add = TRUE
)

Arguments

Details

Breaks defined by a numeric vector or a classification method are left-closed: breaks defined by c(2, 5, 10, 15, 20) will be mapped as [2 - 5[, [5 - 10[, [10 - 15[, [15 - 20]. The "jenks" method is an exception and has to be right-closed. Jenks breaks computed as c(2, 5, 10, 15, 20) will be mapped as [2 - 5], ]5 - 10], ]10 - 15], ]15 - 20].

Value

x is (invisibly) returned.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_map(mtq, c("STATUS", "MED"), "symb_choro")

mf_map(mtq)
mtq$STATUS[30] <- NA
mtq$MED[5] <- NA
mf_map(mtq, c("STATUS", "MED"),
  type = "symb_choro",
  pal = "Reds 3", breaks = "quantile", nbreaks = 4,
  pch = 21:23, cex = c(3, 2, 1),
  pch_na = 25, cex_na = 1.5, col_na = "blue",
  val_order = c(
    "Prefecture",
    "Sub-prefecture",
    "Simple municipality"
  )
)

Plot a text

Description

Plot a text on the map.

Usage

mf_text(
  x,
  txt = "Text",
  cex = 0.8,
  col_txt,
  pos = "center",
  offset = 0,
  align = "center",
  font = 1,
  family = "sans",
  halo = FALSE,
  col_halo,
  cex_halo = cex,
  box = FALSE,
  col_box,
  col_box_border,
  lwd_box = 2,
  line = 0,
  clockwise = TRUE,
  lwd = 2,
  col_line,
  arrow = TRUE,
  cex_arrow = 1,
  adj = c(0, 0)
)

Arguments

Value

No return value, an text is displayed.

Examples

library(mapsf)
mf_theme("base")
mtq <- mf_get_mtq()
mtq_p <- mf_get_mtq("points")
mf_map(mtq, expandBB = c(0, .1, 0, .3))
mf_map(mtq_p[c(2, 3, 17, 28), ],
  pch = 4, lwd = 1.5, cex = .5, col = "red",
  add = TRUE
)
mf_title("Title of the map", banner = TRUE)
mf_frame()
mf_text(x = "topright", txt = "x = 'topright'")
mf_text(
  x = "bottomleft",
  txt = "x = 'bottomleft'\nadj = c(4,4)\nalign = 'left'",
  adj = c(4, 4),
  align = "left"
)
mf_text(
  x = c(728000, 1625500),
  txt = "x = c(X, Y)",
  pos = "right",
  line = 2,
  offset = 5
)
mf_text(
  mtq[3, ],
  txt = "pos = 'top'\nhalo = TRUE",
  pos = "top",
  align = "center",
  halo = TRUE
)
mf_text(
  mtq[3, ],
  txt = "pos = 'bottomleft'\nhalo = TRUE\nalign = 'right'",
  pos = "bottomleft",
  align = "right",
  halo = TRUE
)
mf_text(
  x = mtq[17, ],
  txt = "pos = 'bottomright'\nline = 1\nbox = TRUE",
  pos = "bottomright",
  offset = 10,
  line = 1,
  box = TRUE
)
mf_text(
  x = mtq[17, ],
  txt = "pos = 'topright'\nline = 1\nalign = 'left'",
  pos = "topright",
  offset = 15,
  align = "left",
  line = 1
)
mf_text(
  x = mtq[2, ],
  txt = "pos = 'topleft'\nline = 2\nbox = TRUE\nclockwise = TRUE",
  pos = "topleft",
  offset = 8,
  clockwise = TRUE,
  line = 2,
  box = TRUE
)
mf_text(
  x = mtq[2, ],
  txt = "pos = 'bottomleft'\nline = 2\nclockwise = FALSE",
  pos = "bottomleft",
  offset = 6,
  clockwise = FALSE,
  line = 2,
  box = FALSE
)
mf_text(
  x = mtq[28, ],
  txt = "pos = 'topright'\nline = 3\nclockwise = FALSE",
  pos = "topright",
  offset = 10,
  clockwise = FALSE,
  line = 3,
  halo = TRUE,
  align = "left"
)
mf_text(
  x = mtq[28, ],
  txt = "pos = 'right'\nline = 3\nbox = TRUE\nclockwise = TRUE",
  pos = "right",
  offset = 10,
  clockwise = TRUE,
  line = 3,
  box = TRUE
)

Set a theme

Description

A theme is a set of graphical parameters that are applied to maps created with mapsf. These parameters are:

• figure margins and frames,

• background, foreground and highlight colors,

• default sequential and qualitative palettes,

• title options (position, size, banner...).

mapsf offers some builtin themes. It's possible to modify an existing theme or to start a theme from scratch. It is also possible to set a custom theme using a list of arguments

Themes are persistent across maps produced by mapsf (e.g. they survive a dev.off() call).

Current theme parameters are set in mapsf options and nammed according to the following convention: "mapsf.mf_theme_arg_name". Use getOption() to return the value of a specific argument of the current theme (see examples).

Use mf_theme(NULL) or mf_theme('base') to reset to default theme settings.

Usage

mf_theme(
  x,
  mar,
  foreground,
  background,
  highlight,
  title_tab,
  title_pos,
  title_inner,
  title_line,
  title_cex,
  title_font,
  title_banner,
  frame,
  frame_lwd,
  frame_lty,
  pal_quali,
  pal_seq,
  ...
)

Arguments

Value

mf_theme (invisibly) returns the list of current theme parameters.

Note

The following themes are deprecated: "default", "brutal", "ink", "dark", "agolalight", "candy", "darkula", "iceberg", "green", "nevermind", "jsk" and "barcelona".
The following arguments are deprecated: "bg", "fg", "tab", "pos", "inner", "line", "cex" and "font".

Although the map theming system has been radically changed in version 1.0.0 of the package, you can still use the old themes by referencing them by name. If you need to use the pre v1.0.0 default theme, set x to "default".
If an old theme is set, only deprecated arguments are used and others are ignored.
If current and deprecated arguments are mixed, only deprecated arguments are used and others are ignored.
All references and usages of the old theming system will be removed in the next major version.

Examples

mtq <- mf_get_mtq()

# Choosing a theme by name:
mf_theme("base")
mf_map(mtq)
mf_title()

# Specifying some values directly:
mf_theme(title_banner = TRUE)
mf_map(mtq)
mf_title()

# Using a mix of the above:
mf_theme("sol_dark", title_tab = TRUE, title_font = 1)
mf_map(mtq)
mf_title()

# Specifying a list with theme values:
theme <- list(
  mar = c(1, 1, 3, 1),
  title_tab = FALSE,
  title_pos = "left",
  title_inner = FALSE,
  title_line = 2,
  title_cex = 1.5,
  title_font = 2,
  title_banner = FALSE,
  frame = "figure",
  frame_lwd = 1,
  frame_lty = 1,
  foreground = "#fbfbfb",
  background = "grey75",
  highlight = "#0f5027",
  pal_quali = "Dark 3",
  pal_seq = "Greens"
)
mf_theme(theme)
mf_map(mtq, "MED", "choro")
mf_title()

# Obtaining a list of parameters for the current theme:
current_theme <- mf_theme()

# Obtaining individual parameters for the current theme:
getOption("mapsf.highlight")
getOption("mapsf.pal_seq")


# Use default theme:
mf_theme(NULL)
# or
mf_theme("base")

Plot a title

Description

Plot a title

Usage

mf_title(txt = "Map Title", pos, tab, bg, fg, cex, line, font, inner, banner)

Arguments

Value

No return value, a title is displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq)
mf_title()

Deprecated - Plot a typology map

Description

This function is deprecated. Please use mf_map() with type = "typo" instead.

Plot a typology map.

Usage

mf_typo(
  x,
  var,
  pal,
  alpha = NULL,
  rev = FALSE,
  val_order,
  border,
  pch = 21,
  cex = 2,
  lwd = 0.7,
  col_na = "white",
  extent = x,
  bg,
  expandBB = rep(0.04, 4),
  leg_pos = mf_get_leg_pos(x),
  leg_title = var,
  leg_title_cex = 0.8,
  leg_val_cex = 0.6,
  leg_no_data = "No data",
  leg_frame = FALSE,
  leg_frame_border,
  leg_adj = c(0, 0),
  leg_size = 1,
  leg_box_border,
  leg_box_cex = c(1, 1),
  leg_fg,
  leg_bg,
  add = FALSE
)

Arguments

Value

No return value, a map is displayed.

Examples

mtq <- mf_get_mtq()
mf_map(mtq, "STATUS", "typo")
mtq[6, "STATUS"] <- NA
mf_map(
  x = mtq, var = "STATUS", type = "typo",
  pal = c("red", "blue", "yellow"), lwd = 1.1,
  val_order = c("Prefecture", "Sub-prefecture", "Simple municipality"),
  col_na = "green", border = "brown",
  leg_pos = "bottomleft",
  leg_title = "Status", leg_title_cex = 1.1,
  leg_val_cex = 1, leg_no_data = "No data",
  leg_frame = TRUE, add = FALSE
)

Plot a point on a world map

Description

Plot a point on a world map.

Usage

mf_worldmap(
  x,
  lon,
  lat,
  water_col = "lightblue",
  land_col = "grey60",
  border_col = "grey40",
  border_lwd = 0.8,
  ...
)

Arguments

Value

No return value, a world map is displayed.

Examples

mtq <- mf_get_mtq()
mf_worldmap(mtq)
mf_worldmap(lon = 24, lat = 39)
mf_worldmap(
  lon = 106, lat = 26,
  pch = 4, lwd = 3, cex = 2, col = "tomato4",
  water_col = "#232525", land_col = "#A9B7C6",
  border_col = "white", border_lwd = 1
)