Thematic Cartography

Create and integrate maps in your R workflow. This package allows various cartographic representations such as proportional symbols, choropleth, typology, flows or discontinuities maps. It also offers several features enhancing the graphic presentation of maps like cartographic palettes, layout elements (scale, north arrow, title...), labels, legends or access to some cartographic APIs. See Giraud and Lambert (2017) .

CRAN_Status_Badge Travis-CI Build Status Build status status

Create and integrate maps in your R workflow!

Cartographic Mix

This package allows various cartographic representations such as proportional symbols, chroropleth, typology, flows or discontinuities maps. It also offers several features enhancing the graphic presentation of maps: cartographic palettes, layout elements (scale, north arrow, title...), labels, legends or access to some cartographic APIs.

cartography uses R base graphics to map spatial information.

Up to version 1.4.2 cartography was mainly based on sp and rgeos for its spatial data management and geoprocessing operations. These dependencies have been as much as possible replaced by sf functions since version 2.0.0.

Most functions are kept unchanged except for the addition of an x argument used to take sf objects as inputs.

See the NEWS file for the full list of changes and see sf README in case of installation problems with sf.


The vignette contains commented scripts on how to build various types of maps with cartography

vignette(topic = "cartography")

Blog Posts, Tutorials & Papers

Giraud, T. and Lambert, N. (2017). “Reproducible Cartography.” In Peterson MP (ed.), Advances in Cartography and GIScience. ICACI 2017. Lecture Notes in Geoinformation and Cartography., pp. 173-183. doi: 10.1007/978-3-319-57336-6_13. (EN)

New version of the cartography package (EN)
Demo codes in the R graph Gallery (EN)
Create and integrate maps in your R workflow with the cartography package (EN)
SF & cartography V2.0.0 (FR)
De superbes cartes thématiques... (FR)
Le package cartography a un an (FR)
Cartographie avec R : le package cartography (FR)
R pour les cartographes (FR)
Comment faire un carton avec R? (FR - How to build inset maps)
Tutoriel - Cartographie avec R (FR)
Cartographie et traitement de l’information géographique avec R (FR)
R pour les cartographes : le package cartography (FR)


  • You can access the code used to create the cartographic mix here.

  • The following script creates a map of symbols that are proportional to values of a first variable and colored to reflect the discretization of a second variable.

# Import a shapefile // this one is distributed within the package
mtq <- st_read(system.file("shape/martinique.shp", package="cartography"))
# Share of farmers in the active population
mtq$shareCS1 <- 100 * mtq$C13_CS1/mtq$C13_POP
# Set a custom color palette
cols <- carto.pal(pal1 = "wine.pal", n1 = 6)
# set plot margins
opar <- par(mar = c(0,0,1.2,0))
# Plot the communes
plot(st_geometry(mtq), col = "#5F799C", border = "white", 
     bg = "#A6CAE0", lwd = 0.5, add = FALSE)
# Plot symbols with choropleth coloration
propSymbolsChoroLayer(x = mtq, # sf object 
                      var = "C13_POP", # field used to plot the symbols sizes
                      var2 = "shareCS1", #  field used to plot the colors
                      col = cols, # symbols colors
                      inches = 0.4, # radius of the largest circle
                      method = "quantile", # discretization method (?getBreaks)
                      border = "grey50", # color of circle borders
                      lwd = 1, # width of the circle borders
                      legend.var.pos = "topright", # position of the first legend
                      legend.var2.pos = "left", # position of the second legend
                      legend.var2.title.txt =  
                        "Share of \nthe population\nworking in\nagriculture (%)", 
                      legend.var.title.txt = "Population aged\n15 and over",
             = "c") # legend style
# Add a layout
layoutLayer(title="Farmers in Martinique, 2013", # title of the map
            scale = 5, # size of the scale bar
            north = TRUE, # north arrow
            col = "white",
            coltitle = "black",
            author = "cartography 2.0.0",  
            sources = "INSEE, 2016",
            frame = TRUE)
# restore graphics parameters


  • Development version on GitHub
  • Stable version on CRAN

Alternatives Packages

Community Guidelines

One can contribute to the package through pull requests and report issues or ask questions here.


cartography version 2.0.2 (Release date: 2017-11-13)

Minor Changes:

  • bug fix in labelLayer() when x = SpatialPointsDataFrame.
  • bug fix in propSymbols*Layer() when using a POINT layer with add=FALSE.
  • bug fix in LinkLayer() (df).
  • add R, sf and sp version requirement + sf SystemRequirements
  • allow dataframe AND tibbles as input for df arguùment in relevant functions
  • add postitle to set the position of the title in laoutLayer()
  • add tabtitle to set the size of the title banner in layoutLayer()

cartography version 2.0.1 (Release date: 2017-09-25)

Minor Changes:

  • bug fix for proportionnal symbols with negative values.

cartography version 2.0.0 (Release date: 2017-09-19)

Breaking changes:

  • getBorders, getOuterBorders: an x argument is added in first position, x is added to take sf objects as inputs, if x is used then spdf is not used. spdfid is replaced by id. An sf object (MULTILINESTRING) of borders is returned.

  • discLayer: spdf, spdfid1, spdfid2 and dfid are replaced by x (an sf object as outputed by getBorders).

  • getGridLayer: getGridLayer replaces getGridLayer + getGridData, x argument replaces spdf and can take an sf object or an sp object. var is added to enter the name(s) of numeric field(s) to compute into the grid. cellsize refers to the targeted area of the cells. The function returns an sf object

  • getLinkLayer: spdf, spdf2, df, spdfid, spdf2id, dfids and dfide arguments are replaced by x, xid, df and dfid. x can be either a Spatial*DataFrame or an sf object. The function returns an sf LINESTRING instead of a SpatialLinesDataFrame.

  • propLinkLayer, gradLinkLayer, gradLinkTypoLayer: spdf, df, spdfid, spdfids, spdfide, dfid, dfids and dfide arguments are replaced by x, df, xid and dfid. x must be an sf object (as outputed by getLinkLayer).

  • legend* functions have been enhanced to be more customizable. It is now possible to lay legend on specified x & y.

  • propSymbolsLayer: breakval and col2 arguments are defunct, use propSymbolsTypoLayer if needed.

Major changes:

  • choroLayer, typoLayer, propSymbolsLayer, propSymbolsChoroLayer, propSymbolsTypoLayer, dotDensityLayer, getTiles, getFigDim, labelLayer, smoothLayer: an x argument is added in first position of all these functions. x is added to take sf objects as inputs, if x is used then spdf, df, spdfid, id are not used.

  • labelLayer: possibility to add a colored halo around the labels, option to have non-overlapping labels.

  • layoutLayer: the extent argument can take an sf object.

  • Each function has an example based on sf object.

  • possibility to use text labels in legendChoro

cartography version 1.4.2 (Release date: 2017-03-29)

Minor changes:

  • Addition of 2 discretization methods (thanks to @MBunel): 'em' and 'arith'. The "arith" method is based on a arithmetic progression along the variable values. The "em" method is based on subset defined by the mean of a numeric vector.
  • Update the list of the available tiles servers (getTiles). This list is reduced and could be extended again depanding on the rosm package evolution.

cartography version 1.4.1 (Release date: 2016-12-15)

Major changes:

  • Addition of the hexagonal regular grid in getGridLayer.
  • Addition of barscale function to plot a custom scalebar.
  • Addition of north function to plot a custom north (or south) arrow.

Minor changes:

  • small fix on the msd method (breaks order) in getBreaks function.
  • more precise sources for datasets
  • renaming twincities data frame to twincities.df
  • small fix for ids in getGridLayer

cartography version 1.4.0 (Release date: 2016-08-25)

Major changes:

  • Introduce getOuterBorders that allows to build borders (as getBorders) between non-contiguous polygons.
  • Addition of the theme parameter in layoutLayer to set col and coltitle according to a cartographic palette.
  • discretization function become getBreaks.
  • A new discretisation based on mean and standard deviation is added to getBreaks.
  • Addition of colNA parameter in choro* and typo* function to set a color for NA values.
  • k parameter in prop* function is now defunct, using k will stop the function.

Minor changes:

  • As it was a heavy import, SpatialPosition package is back to suggested packages.
  • As Jenks and Fisher-Jenks algorithms are based on the same principle and give quite similar results but Fisher-Jenks is much faster, "fisher-jenks" method replaces "jenks" in getBreaks methods.
  • In most function, if df is missing then [email protected] is used instead.
  • Introduce function that gives the list of the cartographic palettes.
  • Addition of two qualitatives color palettes ("pastel.pal"" and "multi.pal").

cartography version 1.3 (Release date: 2016-06-07)

Major changes:

  • Introduce the smoothLayer function, this function computes smoothed maps of potentials. It uses quickStewart from SpatialPosition package.
  • Most of previously suggested packages are now imported.

Minor changes:

  • Introduce the legend.*.values.order parameter in typoLayer, propSymbolsTypoLayer and gradLinkTypoLayer. This parameter allows to order modalities in the legend and eases the color assignement.
  • Change min value in prop*Layer legends.
  • Suppress zero values in propSymb*Layer.
  • getGridLayer is faster.
  • getLinkLayer is faster.
  • getBorders is faster.

cartography version 1.2 (Release date: 2016-02-11)

Major changes:

  • The OpenStreetMap package used to display OpenStreetMap tiles has been replaced by the rosm package. rosm installation is lighter and easier (no Java dependency).
  • The k parameter is deprecated in propSymbolsLayer, propSymbolsTypoLayer and propSymbolsChoroLayer. The inches parameter is to be used instead. This modification allows to compare proportionnal symbols maps.

Minor changes:

  • Introduce the getFigDim function that helps to find output figure dimension that fit a Spatial object dimension ratio.
  • The discLayer function now returns a (invisible) SpatialLinesDataFrame of discontinuities.
  • NAs are better managed in choroLayer.
  • The graticule.spdf SpatialLinesDataFrame has been expanded.
  • The size of the title box in layoutLayer is fixed to 1.2 lines height.

cartography version 1.1 (Release date: 2015-11-18)

Major changes:

  • Correction of the proportionnal symbols legends (square, bar, circle, triangle). The previous version was incorrect (size proportionnal to radii and not surfaces).
  • Add a gradLinkTypoLayer function to plot a layer of colored and graduated links.

Minor changes:

  • choroLayer: small correction to allow to plot variable named "x" or "y".
  • vignette: correct the name entry, incorrectly named "SpatialPosition"", to "cartography".
  • Update of the figure in the README file.
  • Darker, and more visible, south and north arrows.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.1.0 by Timothée Giraud, 22 days ago

Report a bug at

Browse source code at

Authors: Timothée Giraud [cre, aut], Nicolas Lambert [aut], Ian Fellows [cph] (no overlap algorithm for labels, from wordcloud package)

Documentation:   PDF Manual  

Task views: Analysis of Spatial Data

GPL-3 license

Imports classInt, stats, graphics, methods, rosm, raster, Rcpp, sp, sf

Suggests SpatialPosition, knitr, rmarkdown, rgdal

Linking to Rcpp

System requirements: GDAL (>= 2.0.0), GEOS (>= 3.4.0), PROJ.4 (>= 4.8.0)

Suggested by MTA, SpatialPosition, osrm, rosm.

See at CRAN