Introduction

The aim of mapsf is to obtain thematic maps with the visual quality of those build with a classical mapping or GIS software.
mapsf uses sf objects to produce base graphics.
mapsf functions can be classified in the following categories:

Symbology
mf_map() is the main function of the package, it displays map layers on a georeferenced plot. Many parameters are available to fine tune the cartographic representations. These parameters are the common ones found in GIS and automatic cartography tools (e.g. classification and color palettes used in choropleth maps, symbols sizes used in proportional symbols maps…).
Map Layout
Along with the cartographic functions, some other functions are dedicated to layout design (e.g. legends, scale bar, north arrow, title, credits…).
Utility Functions
A set of functions is dedicated to the creation of spatial objects (e.g. links creation) or other utility tasks (e.g. color palette management, class intervals extraction, sample dataset import…).

Main Features

Symbology

mf_map() has three main arguments:

x an sf object
var the name(s) of a variable(s) to map
type the map layer type

The following map types are available:

	base: displays sf objects geometries
	prop: displays symbols with areas proportional to a quantitative variable (stocks)
	choro: areas are shaded according to the variation of a quantitative variable
	typo: displays a typology map of a qualitative variable
	symb: displays the different modalities of a qualitative variable as symbols
	grad: displays graduated symbols
	prop_choro: displays symbols with sizes proportional to values of a first variable and colored to reflect the classification of a second quantitative variable.
	prop_typo: displays symbols with sizes proportional to values of a first variable and and colored to reflect the modalities of a second qualitative variable
	symb_choro: displays the different modalities of a first qualitative variable as symbols colored to reflect the classification of a second quantitative variable

Additionaly, mf_raster() can be used to displays raster objects (single/multi band, continuous, classes, intervals).

Map Layout

These functions are dedicated to the map layout design.

① `mf_title()`	Title of the map
② `mf_arrow()`	North arrow
③ `mf_credits()`	Author, sources…
④ `mf_scale()`	Scale bar
⑤ `mf_annotation()`	Annotations
⑥ `mf_label()`	Labels
⑦ `mf_shadow()`	Shadow

Themes

mf_theme() sets a map theme. A theme is a set of graphical parameters that are applied to maps created with mapsf. These parameters are the figure margins, background and foreground colors and mf_title() options. mapsf offers some builtin themes. It’s possible to modify an existing theme or to start a theme from scratch. Themes are persistent across maps produced by mapsf (e.g. they survive a dev.off() call).

🔗 See the online vignette: How to use themes

Export

mf_export() exports maps in PNG or SVG formats. The exported map width/height ratio will match the one of a spatial object.
If width is specified, then height is deduced from the width/height ratio of x and some theme parameters (figure margins and title size).
If height is specified, then width is deduced from the width/height ratio of xand some theme parameters (figure margins and title size).

🔗 See the online vignette: How to export maps

Datasets

Several datasets are embedded in the package:

A GeoPackage of Martinique municipalities can be imported with mf_get_mtq() (or via sf::st_read()).
- Sources: Base comparateur de territoires (data, upload date: 2018-09-25) & ADMIN EXPRESS-COG (geometry, 2018 edition).
- Citation: Insee and IGN, 2018
- Fields:
  - 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
A csv file of professional mobility flows between Martinique municipalities.
- Sources: Flux de mobilité - déplacements domicile-lieu de travail (upload date: 2018-08-01)
- Citation: Insee, 2018
- Fields:
  - 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

Examples of thematic maps

Base map

mf_theme() allows to apply a theme to the map.

mf_shadow() plots the shadow of a polygon layer.

mf_map(x, type = "base") displays sf objects geometries.

mf_layout() add a complete layout to the map (title, credits, north arrow, scale bar). Each layout elements can also be set separately (with mf_title(), mf_credits(), mf_arrow() and mf_scale()).

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# set a theme
mf_theme("iceberg")
# plot a shadow
mf_shadow(mtq)
# plot municipalities
mf_map(mtq, type = "base", add = TRUE)
# layout
mf_layout(
  title = "Martinique",
  credits = paste0(
    "Sources: IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  )
)

Proportional Symbols

mf_map(x, var, type = "prop") displays symbols with areas proportional to a quantitative variable (stocks). The inches argument is used to customize the symbols sizes.

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# set a theme
mf_theme("darkula")
# plot a shadow
mf_shadow(mtq)
# plot municipalities
mf_map(mtq, add = TRUE)
# plot population
mf_map(
  x = mtq,
  var = "POP",
  type = "prop",
  inches = 0.25,
  col = "brown4",
  leg_pos = "topright",
  leg_adj = c(0, -3),
  leg_title = "Total population"
)
# layout
mf_layout(
  title = "Population Distribution in Martinique",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  )
)

Choropleth Map

In choropleth maps, areas are shaded according to the variation of a quantitative variable. They are used to represent ratios or indices.
mf_map(x, var, type = "choro") displays choropleth maps . Arguments nbreaks, and breaks allow to customize the variable classification. mf_get_breaks() allows to classify data outside of the function itself. Colors palettes, defined with pal, can be created with mf_get_pal() or you can use palette names from hcl.pals().

Use mf_theme() to set a theme without plotting anything.

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# population density (inhab./km2) using sf::st_area()
mtq$POPDENS <- 1e6 * mtq$POP / sf::st_area(mtq)
# set a theme
mf_theme("green")
# plot population density
mf_map(
  x = mtq,
  var = "POPDENS",
  type = "choro",
  breaks = "geom",
  nbreaks = 5,
  pal = "Greens",
  border = "white",
  lwd = 0.5,
  leg_pos = "bottomleft",
  leg_adj = c(0, 3), 
  leg_title = "Population Density\n(inh. / km2)"
)
# layout
mf_layout(
  title = "Population Distribution in Martinique",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  )
)

Typology Map

mf_map(x, var, type = "typo") displays a typology map of a qualitative variable. val_order is used to set the modalities order in the legend.

mf_label() displays labels on the map.

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# set theme
mf_theme("dark")
# plot administrative status
mf_map(
  x = mtq,
  var = "STATUS",
  type = "typo",
  pal = c("aquamarine4", "yellow3", "wheat"),
  lwd = .5,
  val_order = c(
    "Prefecture",
    "Sub-prefecture",
    "Simple municipality"
  ),
  leg_pos = "topright",
  leg_adj = c(0, 1),
  leg_title = ""
)
# labels for a few  municipalities
mf_label(
  x = mtq[mtq$STATUS != "Simple municipality", ], var = "LIBGEO",
  cex = 0.9, halo = TRUE, r = 0.15
)
# layout
mf_layout(
  title = "Administrative Status",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  )
)

Proportional Symbols using Choropleth Coloration

mf_map(x, var, type = "prop_choro") creates a map of symbols that are proportional to values of a first variable and colored to reflect the classification of a second variable.

expandBB argument in mf_map() allows to expand the map space. Here, we increase the space available on the right of the map to avoid overlaps between the legends and the map.

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# set theme
mf_theme("candy")
# Plot the municipalities and expand the map space on the right
mf_map(x = mtq, expandBB = c(0, 0, 0, .15))
# Plot symbols with choropleth coloration
mf_map(
  x = mtq,
  var = c("POP", "MED"),
  type = "prop_choro",
  border = "grey50",
  lwd = 1,
  leg_pos = c("topright"),
  leg_title = c("Population", "Median Income\n(in euros)"),
  breaks = "equal",
  nbreaks = 4,
  pal = "Greens",
  leg_val_rnd = c(0, -2),
  leg_frame = TRUE
)
# layout
mf_layout(
  title = "Population & Wealth in Martinique, 2015",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  ),
  frame = TRUE
)

Proportional Symbols using Typology Coloration

mf_map(x, var, type = "prop_typo") creates a map of symbols that are proportional to values of a first variable and colored to reflect the modalities of a second qualitative variable.

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# set theme
mf_theme("ink")
# plot the municipalities and expand the map space on the right
mf_map(x = mtq, expandBB = c(0, 0, 0, .15))
# plot symbols with choropleth coloration
mf_map(
  x = mtq,
  var = c("POP", "STATUS"),
  type = "prop_typo",
  symbol = "square",
  border = "white",
  lwd = .5,
  leg_pos = "topright",
  leg_title = c("Population", "Administrative\nStatus"),
  val_order = c(
    "Prefecture", "Sub-prefecture",
    "Simple municipality"
  )
)
# layout
mf_layout(
  title = "Population Distribution in Martinique",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  )
)

Label Map

mf_label() is dedicated to the display of labels on a map. The overlap = FALSE argument displays non overlapping labels.

In this example we have built a custom theme with mf_theme().

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# set theme
my_theme <- list(
  name = "mytheme",
  bg = "lightblue1",
  fg = "darkseagreen4",
  mar = c(0, 0, 0, 0),
  tab = TRUE,
  pos = "left",
  inner = TRUE,
  line = 1,
  cex = .9,
  font = 3
)
mf_theme(my_theme)
# plot municipalities
mf_map(mtq, col = "#e4e9de", border = "darkseagreen4")
# plot labels
mf_label(
  x = mtq,
  var = "LIBGEO",
  col = "black",
  cex = 0.7,
  font = 4,
  halo = TRUE,
  bg = "white",
  r = 0.1,
  overlap = FALSE,
  lines = FALSE
)
# layout
mf_layout(
  title = "Municipalities of Martinique",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  ),
  arrow = FALSE
)
# north arrow
mf_arrow(pos = "topright")

Links Map

mf_get_links() creates a link layer from an sf object and a link data.frame (long format).

mf_map(x, var, type = "grad") displays graduated links.

library(mapsf)
# import the sample data set
mtq <- mf_get_mtq()
# import the csv file embedded in mapsf
mob <- read.csv(system.file("csv/mob.csv", package = "mapsf"))
# Select links from Fort-de-France (97209))
mob_97209 <- mob[mob$i == 97209, ]
# create an sf object of links
mob_links <- mf_get_links(x = mtq, df = mob_97209)
# set theme
mf_theme("jsk")
# Plot the municipalities
mf_map(mtq)
# plot graduated links
mf_map(
  x = mob_links,
  var = "fij",
  type = "grad",
  breaks = c(100, 500, 1000, 4679.0),
  lwd = c(1, 4, 8),
  leg_pos = "topright",
  leg_title = "Nb. of\nCommuters",
  leg_val_rnd = 0,
  col = "red4",
  leg_frame = TRUE
)
# map layout
mf_layout(
  title = "Commuting to Fort-de-France",
  credits = paste0(
    "Sources: Insee and IGN, 2018\n",
    "mapsf ",
    packageVersion("mapsf")
  ),
  arrow = FALSE
)