+position. It can be one of ‘topleft’, ‘top’,‘topright’, ‘right’,
+‘bottomright’, ‘bottom’,‘bottomleft’, ‘left’, ‘interactive’ or a vector
+of two coordinates in map units (c(x, y))
+
+
+
+
+col
+
+
+arrow color
+
+
+
+
+cex
+
+
+arrow size
+
+
+
+
+adj
+
+
+adjust the postion of the north arrow in x and y directions
+
+
+
+
+align
+
+
+object of class sf or sfc used to adjust the
+arrow to the real north
+
+
+
+
+## Value
+
+No return value, a north arrow is displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq)
+mf_arrow(pos = "topright")
+```
+
+
diff --git a/docs/man/mf_background.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_background.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..0f66826
Binary files /dev/null and b/docs/man/mf_background.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_background.md b/docs/man/mf_background.md
new file mode 100644
index 0000000..a7ce280
--- /dev/null
+++ b/docs/man/mf_background.md
@@ -0,0 +1,54 @@
+
+
+# Plot a background image
+
+## Description
+
+Plot a background image on an existing plot
+
+## Usage
+
+
mf_background(filename, ...)
+
+
+## Arguments
+
+
+
+
+filename
+
+
+filename of the background image, PNG or JPG/JPEG format.
+
+
+
+
+…
+
+
+further parameters for rasterImage
+
+
+
+
+## Value
+
+No return value, a background image is displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+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"
+)
+```
+
+
diff --git a/docs/man/mf_credits.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_credits.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..ce767ee
Binary files /dev/null and b/docs/man/mf_credits.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_credits.md b/docs/man/mf_credits.md
new file mode 100644
index 0000000..873f4b9
--- /dev/null
+++ b/docs/man/mf_credits.md
@@ -0,0 +1,88 @@
+
+
+# Plot credits
+
+## Description
+
+Plot credits (sources, author, year…).
+
+## Usage
+
+
+position, one of ‘bottomleft’, ‘bottomright’ or ‘rightbottom’
+
+
+
+
+col
+
+
+color
+
+
+
+
+cex
+
+
+cex of the credits
+
+
+
+
+font
+
+
+font of the credits
+
+
+
+
+bg
+
+
+background color
+
+
+
+
+## Value
+
+No return value, credits are displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq)
+mf_credits(txt = "Author\nSources - Year")
+```
+
+
diff --git a/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..e978ef8
Binary files /dev/null and b/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..022f0eb
Binary files /dev/null and b/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..e1a8194
Binary files /dev/null and b/docs/man/mf_distr.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_distr.md b/docs/man/mf_distr.md
new file mode 100644
index 0000000..139007d
--- /dev/null
+++ b/docs/man/mf_distr.md
@@ -0,0 +1,75 @@
+
+
+# Plot a distribution
+
+## Description
+
+This function displays a histogram, a box plot, a strip chart and a
+density curve on the same plot.
+
+## Usage
+
+
mf_distr(x, nbins, bw)
+
+
+## Arguments
+
+
+
+
+x
+
+
+a numeric variable
+
+
+
+
+nbins
+
+
+number of bins in the histogram
+
+
+
+
+bw
+
+
+bandwidth of the density curve
+
+
+
+
+## Value
+
+The number of bins of the histogram and the bandwidth of the density
+curve are (invisibly) returned in a list.
+
+## Examples
+
+``` r
+library("mapsf")
+
+(mf_distr(rnorm(1000)))
+```
+
+
+
+ $bw
+ [1] 0.2493926
+
+ $nbins
+ [1] 12
+
+``` r
+mf_distr(rbeta(1000, .6, 7))
+```
+
+
+
+``` r
+mf_distr(rbeta(1000, 5, .6))
+```
+
+
diff --git a/docs/man/mf_export.md b/docs/man/mf_export.md
new file mode 100644
index 0000000..f6f1769
--- /dev/null
+++ b/docs/man/mf_export.md
@@ -0,0 +1,116 @@
+
+
+# Export a map
+
+## Description
+
+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
+
+
+path to the exported file. If the file extention is ".png" a png graphic
+device is opened, if the file extension is ".svg" a svg graphic device
+is opened.
+
+
+
+
+width
+
+
+width of the figure (pixels for png, inches for svg)
+
+
+
+
+height
+
+
+height of the figure (pixels for png, inches for svg)
+
+
+
+
+res
+
+
+resolution (for png)
+
+
+
+
+…
+
+
+further parameters for png or svg export
+
+
+
+
+expandBB
+
+
+fractional values to expand the bounding box with, in each direction
+(bottom, left, top, right)
+
+
+
+
+## Value
+
+No return value, a map file is initiated (in PNG or SVG format).
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+(filename <- tempfile(fileext = ".png"))
+```
+
+ [1] "/tmp/Rtmp7qqK5S/file2528711451f0e.png"
+
+``` r
+mf_export(mtq, filename = filename)
+mf_map(mtq, add = TRUE)
+dev.off()
+```
+
+ png
+ 2
diff --git a/docs/man/mf_get_borders.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_get_borders.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..91d5eff
Binary files /dev/null and b/docs/man/mf_get_borders.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_get_borders.md b/docs/man/mf_get_borders.md
new file mode 100644
index 0000000..77bb6e5
--- /dev/null
+++ b/docs/man/mf_get_borders.md
@@ -0,0 +1,50 @@
+
+
+# Get a border layer from polygons
+
+## Description
+
+This function extracts borders between contiguous polygons.
+
+## Usage
+
+
mf_get_borders(x)
+
+
+## Arguments
+
+
+
+
+x
+
+
+an sf object of POLYGONS, using a projected CRS
+
+
+
+
+## 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
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mtq_b <- mf_get_borders(mtq)
+mf_map(mtq)
+mf_map(mtq_b, col = 1:5, lwd = 4, add = TRUE)
+```
+
+
diff --git a/docs/man/mf_get_breaks.md b/docs/man/mf_get_breaks.md
new file mode 100644
index 0000000..bc8f13a
--- /dev/null
+++ b/docs/man/mf_get_breaks.md
@@ -0,0 +1,143 @@
+
+
+# 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
+
+
+
+
+x
+
+
+a vector of numeric values. NA and Inf values are not used in the
+classification.
+
+
+
+
+nbreaks
+
+
+a number of classes
+
+
+
+
+breaks
+
+
+a classification method; one of "fixed", "sd", "equal", "pretty",
+"quantile", "kmeans", "hclust", "bclust", "fisher", "jenks", "dpih",
+"q6", "Q6", geom", "arith", "em", "msd" or "ckmeans" (see Details)
+
+
+
+
+k
+
+
+number of standard deviation for "msd" method (see Details)
+
+
+
+
+central
+
+
+creation of a central class for "msd" method (see Details)
+
+
+
+
+…
+
+
+further arguments of classIntervals
+
+
+
+
+## Details
+
+"fixed", "sd", "equal", "pretty", "quantile", "kmeans", "hclust",
+"bclust", "fisher", "jenks" and "dpih" are classIntervals
+methods. You may need to pass additional arguments for some of
+them.
+
+The "jenks", "fisher" and "ckmeans" methods are based on the same
+concept of natural breaks and and produce similar
+groupings.
+
+
+
+
+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.
+
+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.
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.
+
+## Value
+
+A numeric vector of breaks
+
+## See Also
+
+classIntervals
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_get_breaks(x = mtq$MED, nbreaks = 6, breaks = "quantile")
+```
+
+ [1] 11929.0 13667.0 14786.0 15685.5 16860.0 18622.0 21761.0
diff --git a/docs/man/mf_get_links.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_get_links.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..994143d
Binary files /dev/null and b/docs/man/mf_get_links.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_get_links.md b/docs/man/mf_get_links.md
new file mode 100644
index 0000000..663ab0a
--- /dev/null
+++ b/docs/man/mf_get_links.md
@@ -0,0 +1,74 @@
+
+
+# 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
+
+
+
+
+x
+
+
+an sf object, a simple feature collection.
+
+
+
+
+df
+
+
+a data.frame that contains identifiers of starting and ending points.
+
+
+
+
+x_id
+
+
+name of the identifier variable in x, default to the first column
+(optional)
+
+
+
+
+df_id
+
+
+names of the identifier variables in df, character vector of length 2,
+default to the two first columns. (optional)
+
+
+
+
+## Value
+
+An sf object is returned, it is composed of df and the sfc (LINESTRING)
+of links.
+
+## Examples
+
+``` r
+library("mapsf")
+
+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)
+```
+
+
diff --git a/docs/man/mf_get_mtq.md b/docs/man/mf_get_mtq.md
new file mode 100644
index 0000000..e960f65
--- /dev/null
+++ b/docs/man/mf_get_mtq.md
@@ -0,0 +1,29 @@
+
+
+# Get the ‘mtq’ dataset
+
+## Description
+
+Import the mtq dataset (Martinique municipalities).
+
+## Usage
+
+
mf_get_mtq()
+
+
+## Details
+
+This a wrapper around st_read(system.file(“gpkg/mtq.gpkg”, package
+= “mapsf”),quiet = TRUE).
+
+## Value
+
+an sf object of Martinique municipalities
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+```
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..83b2f93
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..2c798a5
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..48e5406
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png
new file mode 100644
index 0000000..b7b5fd2
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png differ
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png
new file mode 100644
index 0000000..3e3904a
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png differ
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-6.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-6.png
new file mode 100644
index 0000000..d54c634
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-6.png differ
diff --git a/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-7.png b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-7.png
new file mode 100644
index 0000000..347053f
Binary files /dev/null and b/docs/man/mf_get_pal.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-7.png differ
diff --git a/docs/man/mf_get_pal.md b/docs/man/mf_get_pal.md
new file mode 100644
index 0000000..f7fd022
--- /dev/null
+++ b/docs/man/mf_get_pal.md
@@ -0,0 +1,131 @@
+
+
+# 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
+
+
+the number of colors (\>= 1) to be in the palette
+
+
+
+
+palette
+
+
+a valid palette name. See hcl.pals to get available palette names. The
+name is matched to the list of available palettes, ignoring upper
+vs. lower case, spaces, dashes, etc. in the matching.
+
+
+
+
+alpha
+
+
+an alpha-transparency level in the range \[0,1\] (0 means transparent
+and 1 means opaque)
+
+
+
+
+rev
+
+
+logical indicating whether the ordering of the colors should be reversed
+
+
+
+
+neutral
+
+
+a color, if two gradients are used, the ‘neutral’ color can be added
+between them
+
+
+
+
+## Value
+
+A vector of colors.
+
+## Examples
+
+``` r
+library("mapsf")
+
+cols <- mf_get_pal(n = 10, pal = "Reds 2")
+plot(1:10, rep(1, 10), bg = cols, pch = 22, cex = 4)
+```
+
+
+
+``` r
+cols <- mf_get_pal(n = c(3, 7), pal = c("Reds 2", "Greens"))
+plot(1:10, rep(1, 10), bg = cols, pch = 22, cex = 4)
+```
+
+
+
+``` r
+cols <- mf_get_pal(n = c(5, 5), pal = c("Reds 2", "Greens"))
+plot(1:10, rep(1, 10), bg = cols, pch = 22, cex = 4)
+```
+
+
+
+``` r
+cols <- mf_get_pal(n = c(7, 3), pal = c("Reds 2", "Greens"))
+plot(1:10, rep(1, 10), bg = cols, pch = 22, cex = 4)
+```
+
+
+
+``` r
+cols <- mf_get_pal(
+ n = c(5, 5), pal = c("Reds 2", "Greens"),
+ neutral = "grey"
+)
+plot(1:11, rep(1, 11), bg = cols, pch = 22, cex = 4)
+```
+
+
+
+``` r
+opar <- par(bg = "black")
+cols <- mf_get_pal(
+ n = c(7, 3), pal = c("Reds 2", "Greens"),
+ alpha = c(.3, .7)
+)
+plot(1:10, rep(1, 10), bg = cols, pch = 22, cex = 4)
+```
+
+
+
+``` r
+par(opar)
+cols <- mf_get_pal(
+ n = c(5, 5), pal = c("Reds 2", "Greens"),
+ rev = c(TRUE, TRUE)
+)
+plot(1:10, rep(1, 10), bg = cols, pch = 22, cex = 4)
+```
+
+
diff --git a/docs/man/mf_get_pencil.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_get_pencil.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..1b70495
Binary files /dev/null and b/docs/man/mf_get_pencil.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_get_pencil.md b/docs/man/mf_get_pencil.md
new file mode 100644
index 0000000..3c183b6
--- /dev/null
+++ b/docs/man/mf_get_pencil.md
@@ -0,0 +1,78 @@
+
+
+# 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
+
+
+an sf object, a simple feature collection (POLYGON or MULTIPOLYGON).
+
+
+
+
+size
+
+
+density of the penciling. Median number of points used to build the
+MULTILINESTRING.
+
+
+
+
+buffer
+
+
+buffer around each polygon. This buffer (in map units) is used to take
+sample points. A negative value adds a margin between the penciling and
+the original polygons borders
+
+
+
+
+lefthanded
+
+
+if TRUE the penciling is done left-handed style.
+
+
+
+
+clip
+
+
+if TRUE, the penciling is cut by the original polygon.
+
+
+
+
+## Value
+
+A MULTILINESTRING sf object is returned.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mtq_pencil <- mf_get_pencil(x = mtq, clip = FALSE)
+mf_map(mtq)
+mf_map(mtq_pencil, add = TRUE)
+```
+
+
diff --git a/docs/man/mf_get_ratio.md b/docs/man/mf_get_ratio.md
new file mode 100644
index 0000000..c4c95f5
--- /dev/null
+++ b/docs/man/mf_get_ratio.md
@@ -0,0 +1,95 @@
+
+
+# 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
+
+
+fractional values to expand the bounding box with, in each direction
+(bottom, left, top, right)
+
+
+
+
+label
+
+
+whether to add labels (TRUE) or not (FALSE)
+
+
+
+
+pos
+
+
+labels positions ("bottom", "left", "top" and / or "right")
+
+
+
+
+cex
+
+
+labels size
+
+
+
+
+add
+
+
+whether to add the layer to an existing plot (TRUE) or not (FALSE)
+
+
+
+
+## Value
+
+An (invisible) layer of graticules is returned (LINESTRING).
+
+## Use of graticules
+
+From 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
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq, expandBB = c(0, .1, .1, 0))
+mf_graticule(mtq)
+```
+
+
+
+``` r
+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)
+```
+
+
diff --git a/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..c24b8f2
Binary files /dev/null and b/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..5dbec99
Binary files /dev/null and b/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..3da76ae
Binary files /dev/null and b/docs/man/mf_inset_on.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_inset_on.md b/docs/man/mf_inset_on.md
new file mode 100644
index 0000000..8d9c466
--- /dev/null
+++ b/docs/man/mf_inset_on.md
@@ -0,0 +1,99 @@
+
+
+# Plot an inset
+
+## Description
+
+This function is used to add an inset map to the current map.
+
+## Usage
+
+
+an sf object, or "worldmap" to use with mf_worldmap.
+
+
+
+
+pos
+
+
+position, one of "bottomleft", "left", "topleft", "top", "bottom",
+"bottomright", "right", "topright"
+
+
+
+
+cex
+
+
+share of the map width occupied by the inset
+
+
+
+
+fig
+
+
+coordinates of the inset region (in NDC, see in ?par())
+
+
+
+
+## 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
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq)
+mf_inset_on(x = mtq[1, ], cex = .2)
+mf_map(mtq[1, ])
+mf_inset_off()
+```
+
+
+
+``` r
+mf_map(mtq)
+mf_inset_on(x = "worldmap", pos = "bottomleft")
+mf_worldmap(x = mtq)
+mf_inset_off()
+```
+
+
+
+``` r
+mf_map(mtq)
+mf_inset_on(fig = c(0, 0.25, 0, 0.25))
+mf_map(x = mtq)
+mf_inset_off()
+```
+
+
diff --git a/docs/man/mf_label.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_label.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..6c22c2f
Binary files /dev/null and b/docs/man/mf_label.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_label.md b/docs/man/mf_label.md
new file mode 100644
index 0000000..9eca757
--- /dev/null
+++ b/docs/man/mf_label.md
@@ -0,0 +1,142 @@
+
+
+# Plot labels
+
+## Description
+
+Put labels on a map.
+
+## Usage
+
+
+labels color, it can be a single color or a vector of colors
+
+
+
+
+cex
+
+
+labels cex, it can be a single size or a vector of sizes
+
+
+
+
+overlap
+
+
+if FALSE, labels are moved so they do not overlap.
+
+
+
+
+lines
+
+
+if TRUE, then lines are plotted between x,y and the word, for those
+words not covering their x,y coordinate
+
+
+
+
+halo
+
+
+if TRUE, a ‘halo’ is displayed around the text and additional arguments
+bg and r can be modified to set the color and width of the halo.
+
+
+
+
+bg
+
+
+halo color, it can be a single color or a vector of colors
+
+
+
+
+r
+
+
+width of the halo, it can be a single value or a vector of values
+
+
+
+
+q
+
+
+quality of the non overlapping labels placement. Possible values are 0
+(quick results), 1 (reasonable quality and speed), 2 (better quality), 3
+(insane quality, can take a lot of time).
+
+
+
+
+…
+
+
+further text arguments.
+
+
+
+
+## Value
+
+No return value, labels are displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+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
+)
+```
+
+
diff --git a/docs/man/mf_layout.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_layout.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..ba1f4d0
Binary files /dev/null and b/docs/man/mf_layout.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_layout.md b/docs/man/mf_layout.md
new file mode 100644
index 0000000..48eebaa
--- /dev/null
+++ b/docs/man/mf_layout.md
@@ -0,0 +1,82 @@
+
+
+# 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
+
+
+
+## Value
+
+No return value, a map layout is displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq)
+mf_layout()
+```
+
+
diff --git a/docs/man/mf_legend.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_legend.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..2621b87
Binary files /dev/null and b/docs/man/mf_legend.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_legend.md b/docs/man/mf_legend.md
new file mode 100644
index 0000000..bf313be
--- /dev/null
+++ b/docs/man/mf_legend.md
@@ -0,0 +1,447 @@
+
+
+# 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
+
+
+vector of value(s) (for "prop" and "prop_line", at least c(min, max) for
+"cont"), vector of categories (for "symb" and "typo"), break labels (for
+"choro" and "grad_line").
+
+
+
+
+pos
+
+
+position of the legend. It can be one of ‘topleft’, ‘top’, ‘topright’,
+‘right’, ‘bottomright’, ‘bottom’,‘bottomleft’, ‘left’, ‘interactive’ or
+a vector of two coordinates in map units (c(x, y)).
+
+
+
+
+pal
+
+
+a color palette name or a vector of colors
+
+
+
+
+alpha
+
+
+if pal is a hcl.colors palette name, the alpha-transparency
+level in the range \[0,1\]
+
+
+
+
+col
+
+
+color of the symbols (for "prop") or color of the lines (for "prop_line"
+and "grad_line")
+
+
+
+
+inches
+
+
+size of the largest symbol (radius for circles, half width for squares)
+in inches
+
+
+
+
+symbol
+
+
+type of symbols, ‘circle’ or ‘square’
+
+
+
+
+self_adjust
+
+
+if TRUE values are self-adjusted to keep min, max and intermediate
+rounded values
+
+
+
+
+lwd
+
+
+width(s) of the symbols borders (for "prop" and "symb"), width of the
+largest line (for "prop_line"), vector of line width (for "grad_line")
+
+
+
+
+border
+
+
+symbol border color(s)
+
+
+
+
+pch
+
+
+type(s) of the symbols (0:25)
+
+
+
+
+cex
+
+
+size(s) of the symbols
+
+
+
+
+title
+
+
+title of the legend
+
+
+
+
+title_cex
+
+
+size of the legend title
+
+
+
+
+val_cex
+
+
+size of the values in the legend
+
+
+
+
+val_rnd
+
+
+number of decimal places of the values in the legend
+
+
+
+
+col_na
+
+
+color for missing values
+
+
+
+
+cex_na
+
+
+size of the symbols for missing values
+
+
+
+
+pch_na
+
+
+type of the symbols for missing values
+
+
+
+
+no_data
+
+
+if TRUE a "missing value" box is plotted
+
+
+
+
+no_data_txt
+
+
+label for missing values
+
+
+
+
+box_border
+
+
+border color of legend boxes
+
+
+
+
+box_cex
+
+
+width and height size expansion of boxes, (or offset between circles for
+"prop" legends with horiz = TRUE)
+
+
+
+
+horiz
+
+
+if TRUE plot an horizontal legend
+
+
+
+
+frame_border
+
+
+border color of the frame
+
+
+
+
+frame
+
+
+if TRUE the legend is plotted within a frame
+
+
+
+
+bg
+
+
+background color of the legend
+
+
+
+
+fg
+
+
+foreground color of the legend
+
+
+
+
+size
+
+
+size of the legend; 2 means two times bigger
+
+
+
+
+return_bbox
+
+
+return only bounding box of the legend. No legend is plotted.
+
+
+
+
+adj
+
+
+adjust the postion of the legend in x and y directions
+
+
+
+
+## Details
+
+Some arguments are available for all types of legend: val,
+pos, title, title_cex,
+val_cex, frame, bg,
+fg, size, adj,
+return_bbox).
+
+Relevant arguments for each specific legend types:
+
+
+
+## Value
+
+No value is returned, a legend is displayed (except if
+return_bbox is used).
+
+## Examples
+
+``` r
+library("mapsf")
+
+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))
+```
+
+
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..312870b
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-10.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-10.png
new file mode 100644
index 0000000..f251b4c
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-10.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-11.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-11.png
new file mode 100644
index 0000000..35355e0
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-11.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-12.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-12.png
new file mode 100644
index 0000000..199f164
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-12.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-13.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-13.png
new file mode 100644
index 0000000..c82049d
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-13.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-14.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-14.png
new file mode 100644
index 0000000..2163f8e
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-14.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-15.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-15.png
new file mode 100644
index 0000000..0ebffc4
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-15.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-16.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-16.png
new file mode 100644
index 0000000..3a0dc08
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-16.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-17.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-17.png
new file mode 100644
index 0000000..cd6b44c
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-17.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..62a812e
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..0a83957
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png
new file mode 100644
index 0000000..041f4c3
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png
new file mode 100644
index 0000000..22afec3
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-6.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-6.png
new file mode 100644
index 0000000..3d34d95
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-6.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-7.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-7.png
new file mode 100644
index 0000000..6f5e3bb
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-7.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-8.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-8.png
new file mode 100644
index 0000000..16c0344
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-8.png differ
diff --git a/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-9.png b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-9.png
new file mode 100644
index 0000000..6770058
Binary files /dev/null and b/docs/man/mf_map.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-9.png differ
diff --git a/docs/man/mf_map.md b/docs/man/mf_map.md
new file mode 100644
index 0000000..db2b6d2
--- /dev/null
+++ b/docs/man/mf_map.md
@@ -0,0 +1,801 @@
+
+
+# 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 layer type.
+
+
+
+
+Many parameters are available to fine tune symbologies and legends.
+
+Relevant arguments and default values are different for each map type
+and are described in the "Details" section.
+
+## Usage
+
+
+
+prop_choro: proportional symbols maps with symbols
+colors based on a quantitative data classification
+
+
+
+
+prop_typo: proportional symbols maps with symbols
+colors based on qualitative data
+
+
+
+
+symb_choro: symbols maps with symbols colors based on a
+quantitative data classification
+
+
+
+
+
+
+
+breaks
+
+
+either a numeric vector with the actual breaks, or a classification
+method name (see mf_get_breaks and Details)
+
+
+
+
+nbreaks
+
+
+number of classes
+
+
+
+
+pal
+
+
+a set of colors or a palette name (from hcl.colors)
+
+
+
+
+alpha
+
+
+opacity, in the range \[0,1\]
+
+
+
+
+rev
+
+
+if pal is a hcl.colors palette name, whether the ordering
+of the colors should be reversed (TRUE) or not (FALSE)
+
+
+
+
+inches
+
+
+size of the biggest symbol (radius for circles, half width for squares)
+in inches.
+
+
+
+
+val_max
+
+
+maximum value used for proportional symbols
+
+
+
+
+symbol
+
+
+type of symbols, ‘circle’ or ‘square’
+
+
+
+
+col
+
+
+color
+
+
+
+
+lwd_max
+
+
+line width of the largest line
+
+
+
+
+val_order
+
+
+values order, a character vector that matches var modalities
+
+
+
+
+pch
+
+
+point type
+
+
+
+
+cex
+
+
+point size
+
+
+
+
+border
+
+
+border color
+
+
+
+
+lwd
+
+
+border width
+
+
+
+
+col_na
+
+
+color for missing values
+
+
+
+
+cex_na
+
+
+point size for NA values
+
+
+
+
+pch_na
+
+
+point type for NA values
+
+
+
+
+expandBB
+
+
+fractional values to expand the bounding box with, in each direction
+(bottom, left, top, right)
+
+
+
+
+add
+
+
+whether to add the layer to an existing plot (TRUE) or not (FALSE)
+
+
+
+
+leg_pos
+
+
+position of the legend, one of ‘topleft’, ‘top’,‘topright’, ‘right’,
+‘bottomright’, ‘bottom’, ‘bottomleft’, ‘left’ or a vector of two
+coordinates in map units (c(x, y)). If leg_pos = NA then the legend is
+not plotted. If leg_pos = ‘interactive’ click onthe map to choose the
+legend position.
+
+
+
+
+leg_title
+
+
+legend title
+
+
+
+
+leg_title_cex
+
+
+size of the legend title
+
+
+
+
+leg_val_cex
+
+
+size of the values in the legend
+
+
+
+
+leg_val_rnd
+
+
+number of decimal places of the values in the legend
+
+
+
+
+leg_no_data
+
+
+label for missing values
+
+
+
+
+leg_frame
+
+
+whether to add a frame to the legend (TRUE) or not (FALSE)
+
+
+
+
+leg_frame_border
+
+
+border color of the legend frame
+
+
+
+
+leg_horiz
+
+
+display the legend horizontally (for proportional symbols and choropleth
+types)
+
+
+
+
+leg_adj
+
+
+adjust the postion of the legend in x and y directions
+
+
+
+
+leg_bg
+
+
+color of the legend backgournd
+
+
+
+
+leg_fg
+
+
+color of the legend foreground
+
+
+
+
+leg_size
+
+
+size of the legend; 2 means two times bigger
+
+
+
+
+leg_border
+
+
+symbol border color(s)
+
+
+
+
+leg_box_border
+
+
+border color of legend boxes
+
+
+
+
+leg_box_cex
+
+
+width and height size expansion of boxes
+
+
+
+
+…
+
+
+further parameters from plot for sfc objects
+
+
+
+
+## Details
+
+
+Relevant arguments and default values for each map types:
+
+
+choro: areas are shaded according to the variation of a
+quantitative variable. Choropleth maps are used to represent ratios or
+indices. nbreaks, and breaks allow to set the
+variable classification. Colors palettes, defined with pal,
+can be created with mf_get_pal() or can use palette names
+from hcl.pals().
+
+
+
+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 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.
+
+
+type of raster map, one of "continuous", "classes", or "interval".
+Default type for a numeric and categorial raster are "continuous" and
+"classes" respectively.
+
+
+
+
+nbreaks
+
+
+number of classes
+
+
+
+
+breaks
+
+
+either a numeric vector with the actual breaks (for type = "continuous"
+and type = "interval"), or a classification method name (for type =
+"interval" only; see mf_get_breaks for classification methods)
+
+
+
+
+val_order
+
+
+values order, a character vector that matches var modalities
+
+
+
+
+pal
+
+
+a set of colors or a palette name (from hcl.colors)
+
+
+
+
+expandBB
+
+
+fractional values to expand the bounding box with, in each direction
+(bottom, left, top, right)
+
+
+
+
+alpha
+
+
+opacity, in the range \[0,1\]
+
+
+
+
+rev
+
+
+if pal is a hcl.colors palette name, whether the ordering
+of the colors should be reversed (TRUE) or not (FALSE)
+
+
+
+
+leg_pos
+
+
+position of the legend, one of ‘topleft’, ‘top’,‘topright’, ‘right’,
+‘bottomright’, ‘bottom’, ‘bottomleft’, ‘left’ or a vector of two
+coordinates in map units (c(x, y)). If leg_pos = NA then the legend is
+not plotted. If leg_pos = ‘interactive’ click onthe map to choose the
+legend position.
+
+
+
+
+leg_title
+
+
+legend title
+
+
+
+
+leg_title_cex
+
+
+size of the legend title
+
+
+
+
+leg_val_cex
+
+
+size of the values in the legend
+
+
+
+
+leg_val_rnd
+
+
+number of decimal places of the values in the legend
+
+
+
+
+leg_frame
+
+
+whether to add a frame to the legend (TRUE) or not (FALSE)
+
+
+
+
+leg_frame_border
+
+
+border color of the legend frame
+
+
+
+
+leg_horiz
+
+
+display the legend horizontally
+
+
+
+
+leg_adj
+
+
+adjust the postion of the legend in x and y directions
+
+
+
+
+leg_box_border
+
+
+border color of legend boxes
+
+
+
+
+leg_box_cex
+
+
+width and height size expansion of boxes
+
+
+
+
+leg_fg
+
+
+color of the legend foreground
+
+
+
+
+leg_bg
+
+
+color of the legend backgournd
+
+
+
+
+leg_size
+
+
+size of the legend; 2 means two times bigger
+
+
+
+
+add
+
+
+whether to add the layer to an existing plot (TRUE) or not (FALSE)
+
+
+
+
+…
+
+
+bgalpha, smooth, maxcell or other arguments passed to be passed to
+plotRGB or plot
+
+
+
+
+## Value
+
+x is (invisibly) returned.
+
+## Examples
+
+``` r
+library("mapsf")
+
+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")
+ )
+}
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..111f61a
Binary files /dev/null and b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..9a78055
Binary files /dev/null and b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..9a78055
Binary files /dev/null and b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png
new file mode 100644
index 0000000..a86f12b
Binary files /dev/null and b/docs/man/mf_scale.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png differ
diff --git a/docs/man/mf_scale.md b/docs/man/mf_scale.md
new file mode 100644
index 0000000..0dd5827
--- /dev/null
+++ b/docs/man/mf_scale.md
@@ -0,0 +1,158 @@
+
+
+# Plot a scale bar
+
+## Description
+
+Plot a scale bar.
+
+## Usage
+
+
+size of the scale bar in scale units (scale_units, default
+to km). If size is not set, an automatic size is used (1/10 of the map
+width).
+
+
+
+
+pos
+
+
+position. It can be one of ‘bottomright’, ‘bottomleft’, ‘interactive’ or
+a vector of two coordinates in map units (c(x, y)).
+
+
+
+
+lwd
+
+
+line width of the scale bar
+
+
+
+
+cex
+
+
+size of the scale bar text
+
+
+
+
+col
+
+
+color of the scale bar (line and text)
+
+
+
+
+crs_units
+
+
+units used in the CRS of the currently plotted layer. Possible values
+are "m" and "ft" (see Details).
+
+
+
+
+scale_units
+
+
+units used for the scale bar. Can be "mi" for miles, "ft" for feet, "m"
+for meters, or "km" for kilometers (default).
+
+
+
+
+x
+
+
+object of class crs, sf or sfc. If set, the CRS of x will be used
+instead of crs_units to define CRS units.
+
+
+
+
+## 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.
+
+This scale bar does not work on unprojected (long/lat) maps.
+
+## Value
+
+No return value, a scale bar is displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq)
+mf_scale()
+```
+
+
+
+``` r
+library(sf)
+nc <- st_read(system.file("shape/nc.shp", package = "sf"))[1, ]
+```
+
+ Reading layer `nc' from data source `/home/tim/Documents/R/4.4/sf/shape/nc.shp' using driver `ESRI Shapefile'
+ Simple feature collection with 100 features and 14 fields
+ Geometry type: MULTIPOLYGON
+ Dimension: XY
+ Bounding box: xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965
+ Geodetic CRS: NAD27
+
+``` r
+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")
+```
+
+
+
+``` r
+mf_map(nc_foot)
+mf_scale(size = 5, x = nc_foot, scale_units = "mi")
+```
+
+
+
+``` r
+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")
+```
+
+
diff --git a/docs/man/mf_shadow.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_shadow.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..c2262db
Binary files /dev/null and b/docs/man/mf_shadow.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_shadow.md b/docs/man/mf_shadow.md
new file mode 100644
index 0000000..1ac8726
--- /dev/null
+++ b/docs/man/mf_shadow.md
@@ -0,0 +1,65 @@
+
+
+# Plot a shadow
+
+## Description
+
+Plot the shadow of a polygon layer.
+
+## Usage
+
+
+whether to add the layer to an existing plot (TRUE) or not (FALSE)
+
+
+
+
+## Value
+
+x is (invisibly) returned.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_shadow(mtq)
+mf_map(mtq, add = TRUE)
+```
+
+
diff --git a/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..a7f5a13
Binary files /dev/null and b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..9581a68
Binary files /dev/null and b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..350a032
Binary files /dev/null and b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png
new file mode 100644
index 0000000..bc23349
Binary files /dev/null and b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-4.png differ
diff --git a/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png
new file mode 100644
index 0000000..9550fa3
Binary files /dev/null and b/docs/man/mf_theme.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-5.png differ
diff --git a/docs/man/mf_theme.md b/docs/man/mf_theme.md
new file mode 100644
index 0000000..22be0e9
--- /dev/null
+++ b/docs/man/mf_theme.md
@@ -0,0 +1,216 @@
+
+
+# Set a theme
+
+## Description
+
+This function set a map theme. The parameters set by this function are
+the figure margins, background and foreground colors and some mf_title
+options. Use mf_theme(NULL) or
+mf_theme(‘default’) to reset to default theme settings.
+
+## Usage
+
+
+name of a map theme. One of "default", "brutal", "ink", "dark",
+"agolalight", "candy", "darkula", "iceberg", "green", "nevermind",
+"jsk", "barcelona".
+
+
+
+
+bg
+
+
+background color
+
+
+
+
+fg
+
+
+foreground color
+
+
+
+
+mar
+
+
+margins
+
+
+
+
+tab
+
+
+if TRUE the title is displayed as a ‘tab’
+
+
+
+
+pos
+
+
+title position, one of ‘left’, ‘center’, ‘right’
+
+
+
+
+inner
+
+
+if TRUE the title is displayed inside the plot area.
+
+
+
+
+line
+
+
+number of lines used for the title
+
+
+
+
+cex
+
+
+cex of the title
+
+
+
+
+font
+
+
+font of the title
+
+
+
+
+## Details
+
+It is also possible to set a custom theme using a list of arguments (see
+Examples). mf_theme() returns the current theme settings.
+
+## Value
+
+The (invisible) list of theme parameters is returned.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+
+# Choosing a theme by name:
+mf_theme("default")
+mf_map(mtq)
+mf_title()
+```
+
+
+
+``` r
+# Specifying some values directly:
+mf_theme(bg = "darkslategrey", fg = "lightgrey")
+mf_map(mtq)
+mf_title()
+```
+
+
+
+``` r
+# Using a mix of the above:
+mf_theme("brutal", fg = "lightgreen", pos = "center", font = 2, tab = FALSE)
+mf_map(mtq)
+mf_title()
+```
+
+
+
+``` r
+# Specifying a list with theme values:
+theme <- mf_theme("default")
+theme$mar <- c(1, 1, 3, 1)
+theme$line <- 2
+theme$cex <- 1.5
+mf_theme(theme)
+mf_map(mtq)
+mf_title()
+```
+
+
+
+``` r
+# or
+theme <- list(
+ bg = "green",
+ fg = "red",
+ mar = c(2, 2, 2, 2),
+ tab = TRUE,
+ pos = "center",
+ inner = TRUE,
+ line = 2,
+ cex = 1.5,
+ font = 3
+)
+mf_theme(theme)
+mf_map(mtq)
+mf_title()
+```
+
+
+
+``` r
+# Obtaining a list of parameters for the current theme:
+mf_theme()
+```
+
+ $bg
+ [1] "green"
+
+ $fg
+ [1] "red"
+
+ $mar
+ [1] 2 2 2 2
+
+ $tab
+ [1] TRUE
+
+ $pos
+ [1] "center"
+
+ $inner
+ [1] TRUE
+
+ $line
+ [1] 2
+
+ $cex
+ [1] 1.5
+
+ $font
+ [1] 3
+
+``` r
+# Removing the current theme:
+mf_theme(NULL)
+# or
+mf_theme("default")
+```
diff --git a/docs/man/mf_title.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_title.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..a7f5a13
Binary files /dev/null and b/docs/man/mf_title.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_title.md b/docs/man/mf_title.md
new file mode 100644
index 0000000..f61301d
--- /dev/null
+++ b/docs/man/mf_title.md
@@ -0,0 +1,105 @@
+
+
+# Plot a title
+
+## Description
+
+Plot a title
+
+## Usage
+
+
+if TRUE the title is displayed inside the plot area.
+
+
+
+
+## Value
+
+No return value, a title is displayed.
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_map(mtq)
+mf_title()
+```
+
+
diff --git a/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png b/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png
new file mode 100644
index 0000000..53437fc
Binary files /dev/null and b/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-1.png differ
diff --git a/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png b/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png
new file mode 100644
index 0000000..407e1a4
Binary files /dev/null and b/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-2.png differ
diff --git a/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png b/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png
new file mode 100644
index 0000000..4d68533
Binary files /dev/null and b/docs/man/mf_worldmap.markdown_strict_files/figure-markdown_strict/unnamed-chunk-1-3.png differ
diff --git a/docs/man/mf_worldmap.md b/docs/man/mf_worldmap.md
new file mode 100644
index 0000000..f280dd5
--- /dev/null
+++ b/docs/man/mf_worldmap.md
@@ -0,0 +1,127 @@
+
+
+# Plot a point on a world map
+
+## Description
+
+Plot a point on a world map.
+
+## Usage
+
+
+further parameters related to the plotted point aspect (cex, pch, col…)
+
+
+
+
+## Value
+
+No return value, a world map is displayed.
+
+## Note
+
+The main part of the code is stolen from @fzenoni
+(https://gist.github.com/fzenoni/ef23faf6d1ada5e4a91c9ef23b0ba2c1).
+
+## Examples
+
+``` r
+library("mapsf")
+
+mtq <- mf_get_mtq()
+mf_worldmap(mtq)
+```
+
+
+
+``` r
+mf_worldmap(lon = 24, lat = 39)
+```
+
+
+
+``` r
+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
+)
+```
+
+
diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml
new file mode 100644
index 0000000..930db35
--- /dev/null
+++ b/docs/pkgdown.yml
@@ -0,0 +1,4 @@
+urls:
+ reference: https:/riatelab.github.io/mapsf/man
+ article: https:/riatelab.github.io/mapsf/vignettes
+
diff --git a/docs/preamble_man_qmd.yml b/docs/preamble_man_qmd.yml
new file mode 100644
index 0000000..cd2e598
--- /dev/null
+++ b/docs/preamble_man_qmd.yml
@@ -0,0 +1,6 @@
+---
+format:
+ md:
+ prefer-html: true
+---
+
diff --git a/docs/preamble_vignettes_qmd.yml b/docs/preamble_vignettes_qmd.yml
new file mode 100644
index 0000000..1436a9e
--- /dev/null
+++ b/docs/preamble_vignettes_qmd.yml
@@ -0,0 +1,6 @@
+---
+format:
+ md:
+ prefer_html: true
+default-image-extension: ""
+---
diff --git a/docs/preamble_vignettes_rmd.yml b/docs/preamble_vignettes_rmd.yml
new file mode 100644
index 0000000..b47a68a
--- /dev/null
+++ b/docs/preamble_vignettes_rmd.yml
@@ -0,0 +1,4 @@
+---
+always_allow_html: yes
+---
+
diff --git a/docs/vignettes/.gitignore b/docs/vignettes/.gitignore
new file mode 100644
index 0000000..097b241
--- /dev/null
+++ b/docs/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/docs/vignettes/cheat_sheet.Rmd b/docs/vignettes/cheat_sheet.Rmd
new file mode 100644
index 0000000..18999ef
--- /dev/null
+++ b/docs/vignettes/cheat_sheet.Rmd
@@ -0,0 +1,16 @@
+---
+title: "Cheat Sheet"
+author: "Ronan Ysebaert & Timothée Giraud"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{Cheat Sheet}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+
+
+
+
+[Download PDF version](https://raw.githubusercontent.com/riatelab/mapsf/master/vignettes/web_only/img/mapsf_cheatsheet.pdf)
diff --git a/docs/vignettes/cheat_sheet.md b/docs/vignettes/cheat_sheet.md
new file mode 100644
index 0000000..1261fce
--- /dev/null
+++ b/docs/vignettes/cheat_sheet.md
@@ -0,0 +1,8 @@
+# Cheat Sheet
+Ronan Ysebaert & Timothée Giraud
+2025-01-22
+
+
+
+[Download PDF
+version](https://raw.githubusercontent.com/riatelab/mapsf/master/vignettes/web_only/img/mapsf_cheatsheet.pdf)
diff --git a/docs/vignettes/fig/maplayout.png b/docs/vignettes/fig/maplayout.png
new file mode 100644
index 0000000..ca99a67
Binary files /dev/null and b/docs/vignettes/fig/maplayout.png differ
diff --git a/docs/vignettes/fig/mapsf_cheatsheet.pdf b/docs/vignettes/fig/mapsf_cheatsheet.pdf
new file mode 100644
index 0000000..579ce18
Binary files /dev/null and b/docs/vignettes/fig/mapsf_cheatsheet.pdf differ
diff --git a/docs/vignettes/fig/mapsf_cheatsheet.png b/docs/vignettes/fig/mapsf_cheatsheet.png
new file mode 100644
index 0000000..d33fbb4
Binary files /dev/null and b/docs/vignettes/fig/mapsf_cheatsheet.png differ
diff --git a/docs/vignettes/fig/mapsf_cheatsheet.svg b/docs/vignettes/fig/mapsf_cheatsheet.svg
new file mode 100644
index 0000000..b9ff099
--- /dev/null
+++ b/docs/vignettes/fig/mapsf_cheatsheet.svg
@@ -0,0 +1,12039 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_base.png b/docs/vignettes/fig/mf_base.png
new file mode 100644
index 0000000..66a852b
Binary files /dev/null and b/docs/vignettes/fig/mf_base.png differ
diff --git a/docs/vignettes/fig/mf_base.svg b/docs/vignettes/fig/mf_base.svg
new file mode 100644
index 0000000..aa6d85f
--- /dev/null
+++ b/docs/vignettes/fig/mf_base.svg
@@ -0,0 +1,77 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_choro.svg b/docs/vignettes/fig/mf_choro.svg
new file mode 100644
index 0000000..7b5361c
--- /dev/null
+++ b/docs/vignettes/fig/mf_choro.svg
@@ -0,0 +1,48 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_grad.svg b/docs/vignettes/fig/mf_grad.svg
new file mode 100644
index 0000000..2a8cdc5
--- /dev/null
+++ b/docs/vignettes/fig/mf_grad.svg
@@ -0,0 +1,98 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_prop.svg b/docs/vignettes/fig/mf_prop.svg
new file mode 100644
index 0000000..ba5e395
--- /dev/null
+++ b/docs/vignettes/fig/mf_prop.svg
@@ -0,0 +1,108 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_prop_choro.svg b/docs/vignettes/fig/mf_prop_choro.svg
new file mode 100644
index 0000000..73b6d4a
--- /dev/null
+++ b/docs/vignettes/fig/mf_prop_choro.svg
@@ -0,0 +1,123 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_prop_typo.svg b/docs/vignettes/fig/mf_prop_typo.svg
new file mode 100644
index 0000000..adb9c8f
--- /dev/null
+++ b/docs/vignettes/fig/mf_prop_typo.svg
@@ -0,0 +1,148 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_raster.svg b/docs/vignettes/fig/mf_raster.svg
new file mode 100644
index 0000000..306b01e
--- /dev/null
+++ b/docs/vignettes/fig/mf_raster.svg
@@ -0,0 +1,49 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_symb.svg b/docs/vignettes/fig/mf_symb.svg
new file mode 100644
index 0000000..cfbe73e
--- /dev/null
+++ b/docs/vignettes/fig/mf_symb.svg
@@ -0,0 +1,94 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_symb_choro.svg b/docs/vignettes/fig/mf_symb_choro.svg
new file mode 100644
index 0000000..b582738
--- /dev/null
+++ b/docs/vignettes/fig/mf_symb_choro.svg
@@ -0,0 +1,94 @@
+
+
+
+
diff --git a/docs/vignettes/fig/mf_typo.svg b/docs/vignettes/fig/mf_typo.svg
new file mode 100644
index 0000000..a0a8c05
--- /dev/null
+++ b/docs/vignettes/fig/mf_typo.svg
@@ -0,0 +1,48 @@
+
+
+
+
diff --git a/docs/vignettes/fig/wo_export_fixed_height_centered.png b/docs/vignettes/fig/wo_export_fixed_height_centered.png
new file mode 100644
index 0000000..8b9fafe
Binary files /dev/null and b/docs/vignettes/fig/wo_export_fixed_height_centered.png differ
diff --git a/docs/vignettes/fig/wo_export_fixed_width.png b/docs/vignettes/fig/wo_export_fixed_width.png
new file mode 100644
index 0000000..ba930e0
Binary files /dev/null and b/docs/vignettes/fig/wo_export_fixed_width.png differ
diff --git a/docs/vignettes/fig/wo_export_fixed_width.svg b/docs/vignettes/fig/wo_export_fixed_width.svg
new file mode 100644
index 0000000..a015885
--- /dev/null
+++ b/docs/vignettes/fig/wo_export_fixed_width.svg
@@ -0,0 +1,133 @@
+
+
diff --git a/docs/vignettes/fig/wo_export_fixed_width_expand.png b/docs/vignettes/fig/wo_export_fixed_width_expand.png
new file mode 100644
index 0000000..73014a0
Binary files /dev/null and b/docs/vignettes/fig/wo_export_fixed_width_expand.png differ
diff --git a/docs/vignettes/fig/wo_export_unnamed-chunk-9-1.png b/docs/vignettes/fig/wo_export_unnamed-chunk-9-1.png
new file mode 100644
index 0000000..8a93d26
Binary files /dev/null and b/docs/vignettes/fig/wo_export_unnamed-chunk-9-1.png differ
diff --git a/docs/vignettes/fig/wo_facet_unnamed-chunk-2-1.png b/docs/vignettes/fig/wo_facet_unnamed-chunk-2-1.png
new file mode 100644
index 0000000..d995a65
Binary files /dev/null and b/docs/vignettes/fig/wo_facet_unnamed-chunk-2-1.png differ
diff --git a/docs/vignettes/fig/wo_facet_unnamed-chunk-3-1.png b/docs/vignettes/fig/wo_facet_unnamed-chunk-3-1.png
new file mode 100644
index 0000000..4bddeb4
Binary files /dev/null and b/docs/vignettes/fig/wo_facet_unnamed-chunk-3-1.png differ
diff --git a/docs/vignettes/fig/wo_font_a-1.png b/docs/vignettes/fig/wo_font_a-1.png
new file mode 100644
index 0000000..0244a82
Binary files /dev/null and b/docs/vignettes/fig/wo_font_a-1.png differ
diff --git a/docs/vignettes/fig/wo_inset_unnamed-chunk-2-1.png b/docs/vignettes/fig/wo_inset_unnamed-chunk-2-1.png
new file mode 100644
index 0000000..b1307c9
Binary files /dev/null and b/docs/vignettes/fig/wo_inset_unnamed-chunk-2-1.png differ
diff --git a/docs/vignettes/fig/wo_inset_unnamed-chunk-3-1.png b/docs/vignettes/fig/wo_inset_unnamed-chunk-3-1.png
new file mode 100644
index 0000000..8771e50
Binary files /dev/null and b/docs/vignettes/fig/wo_inset_unnamed-chunk-3-1.png differ
diff --git a/docs/vignettes/fig/wo_inset_unnamed-chunk-4-1.png b/docs/vignettes/fig/wo_inset_unnamed-chunk-4-1.png
new file mode 100644
index 0000000..7be4de3
Binary files /dev/null and b/docs/vignettes/fig/wo_inset_unnamed-chunk-4-1.png differ
diff --git a/docs/vignettes/fig/wo_inset_unnamed-chunk-5-1.png b/docs/vignettes/fig/wo_inset_unnamed-chunk-5-1.png
new file mode 100644
index 0000000..b2bcfe0
Binary files /dev/null and b/docs/vignettes/fig/wo_inset_unnamed-chunk-5-1.png differ
diff --git a/docs/vignettes/fig/wo_inset_unnamed-chunk-6-1.png b/docs/vignettes/fig/wo_inset_unnamed-chunk-6-1.png
new file mode 100644
index 0000000..b111db5
Binary files /dev/null and b/docs/vignettes/fig/wo_inset_unnamed-chunk-6-1.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-1.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-1.png
new file mode 100644
index 0000000..a1bf200
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-1.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-10.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-10.png
new file mode 100644
index 0000000..c496366
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-10.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-11.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-11.png
new file mode 100644
index 0000000..3d8ba95
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-11.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-2.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-2.png
new file mode 100644
index 0000000..7671e7c
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-2.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-3.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-3.png
new file mode 100644
index 0000000..e75f7b3
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-3.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-4.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-4.png
new file mode 100644
index 0000000..730310a
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-4.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-5.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-5.png
new file mode 100644
index 0000000..c674c68
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-5.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-6.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-6.png
new file mode 100644
index 0000000..845fa87
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-6.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-7.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-7.png
new file mode 100644
index 0000000..348e8a7
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-7.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-8.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-8.png
new file mode 100644
index 0000000..b14d536
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-8.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-2-9.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-9.png
new file mode 100644
index 0000000..7575ce3
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-2-9.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-5-1.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-5-1.png
new file mode 100644
index 0000000..39c32ce
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-5-1.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-6-1.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-6-1.png
new file mode 100644
index 0000000..00f7c9e
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-6-1.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-7-1.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-7-1.png
new file mode 100644
index 0000000..ad526fd
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-7-1.png differ
diff --git a/docs/vignettes/fig/wo_theme_unnamed-chunk-7-2.png b/docs/vignettes/fig/wo_theme_unnamed-chunk-7-2.png
new file mode 100644
index 0000000..7ad8115
Binary files /dev/null and b/docs/vignettes/fig/wo_theme_unnamed-chunk-7-2.png differ
diff --git a/docs/vignettes/how_to_create_faceted_maps.Rmd b/docs/vignettes/how_to_create_faceted_maps.Rmd
new file mode 100644
index 0000000..0fac60d
--- /dev/null
+++ b/docs/vignettes/how_to_create_faceted_maps.Rmd
@@ -0,0 +1,61 @@
+---
+title: "How to Create Faceted Maps"
+author: "Timothée Giraud"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{How to Create Faceted Maps}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.width = 7,
+ fig.height = 4,
+ fig.path = "fig/wo_facet_",
+ eval = TRUE
+
+)
+```
+
+To plot several maps on the same figure, the user can use the `mfrow` argument of the `par()` function before plotting the maps.
+For example, use `par(mfrow = c(1, 2))` (i.e. 1 row, 2 columns) to plot two maps side by side).
+
+```{r, fig.height=4, fig.width=7, results = FALSE}
+library(mapsf)
+mtq <- mf_get_mtq()
+# define the figure layout (1 row, 2 columns)
+par(mfrow = c(1, 2))
+# first map
+mf_map(mtq)
+mf_map(mtq, "POP", "prop")
+mf_title("Population")
+# second map
+mf_map(mtq, "MED", "choro")
+mf_title("Median Income")
+```
+
+
+When relevant the user can use a `for` loop.
+```{r, fig.height = 8, fig.width = 7, results = FALSE}
+# define the figure layout (6 rows and 6 columns)
+par(mfrow = c(6, 6))
+for (i in seq_len(nrow(mtq))) {
+ # center the map on a targeted municipality and its
+ # neighborhood (with mf_map(..., col = NA, border = NA) and its expandBB arg)
+ mf_map(mtq[i, ], col = NA, border = NA, expandBB = c(.3, .3, .3, .3))
+ # plot the municpalities
+ mf_map(mtq, border = "white", lwd = .5, add = TRUE)
+ # plot the shadow of the targeted municpality
+ mf_shadow(mtq[i, ], cex = .75, col = "grey60", add = TRUE)
+ # plot the targeted municipality
+ mf_map(mtq[i, ], col = "tomato1", border = "grey60", add = TRUE)
+ # add a title
+ mf_title(mtq[[i, "LIBGEO"]])
+}
+```
+
diff --git a/docs/vignettes/how_to_create_faceted_maps.md b/docs/vignettes/how_to_create_faceted_maps.md
new file mode 100644
index 0000000..1711d10
--- /dev/null
+++ b/docs/vignettes/how_to_create_faceted_maps.md
@@ -0,0 +1,46 @@
+# How to Create Faceted Maps
+Timothée Giraud
+2025-01-22
+
+To plot several maps on the same figure, the user can use the `mfrow`
+argument of the `par()` function before plotting the maps. For example,
+use `par(mfrow = c(1, 2))` (i.e. 1 row, 2 columns) to plot two maps side
+by side).
+
+``` r
+library(mapsf)
+mtq <- mf_get_mtq()
+# define the figure layout (1 row, 2 columns)
+par(mfrow = c(1, 2))
+# first map
+mf_map(mtq)
+mf_map(mtq, "POP", "prop")
+mf_title("Population")
+# second map
+mf_map(mtq, "MED", "choro")
+mf_title("Median Income")
+```
+
+
+
+When relevant the user can use a `for` loop.
+
+``` r
+# define the figure layout (6 rows and 6 columns)
+par(mfrow = c(6, 6))
+for (i in seq_len(nrow(mtq))) {
+ # center the map on a targeted municipality and its
+ # neighborhood (with mf_map(..., col = NA, border = NA) and its expandBB arg)
+ mf_map(mtq[i, ], col = NA, border = NA, expandBB = c(.3, .3, .3, .3))
+ # plot the municpalities
+ mf_map(mtq, border = "white", lwd = .5, add = TRUE)
+ # plot the shadow of the targeted municpality
+ mf_shadow(mtq[i, ], cex = .75, col = "grey60", add = TRUE)
+ # plot the targeted municipality
+ mf_map(mtq[i, ], col = "tomato1", border = "grey60", add = TRUE)
+ # add a title
+ mf_title(mtq[[i, "LIBGEO"]])
+}
+```
+
+
diff --git a/docs/vignettes/how_to_create_inset_maps.Rmd b/docs/vignettes/how_to_create_inset_maps.Rmd
new file mode 100644
index 0000000..be1f50e
--- /dev/null
+++ b/docs/vignettes/how_to_create_inset_maps.Rmd
@@ -0,0 +1,186 @@
+---
+title: "How to Create Inset Maps"
+author: "Timothée Giraud"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{How to Create Inset Maps}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.path = "fig/wo_inset_"
+)
+```
+
+
+
+
+**`mf_inset*()`** functions create map insets.
+`mf_inset_on()` starts the inset and `mf_inset_off()` closes it.
+
+
+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.
+
+
+
+## Size and Position
+
+There is 2 solutions for defining the size and position of an inset.
+
+The first solution is based on `x`, `pos` and `cex` arguments:
+
+- `x` is an sf object, the width/height ratio of the inset will match the width/height ratio of `x` bounding box;
+- `pos` must be one of "bottomleft", "left", "topleft", "top", "bottom", "bottomright", "right" or"topright";
+- `cex` defines the share of the map width covered by the inset (0.5 means 50%).
+
+In the following example we create an inset for a specific municipality in the topright corner of the map.
+
+```{r, fig.height=5.71, fig.width=6, results = FALSE}
+library(mapsf)
+# set a theme
+mf_theme("default", mar = c(0, 0, 0, 0))
+# data import
+mtq <- mf_get_mtq()
+# Selection of a target municipality to display in the inset
+mtq_target <- mtq[c(26), ]
+# Display the base map
+mf_map(mtq, expandBB = c(0, 0, 0, .25))
+# display the target on the main map
+mf_map(mtq_target, add = TRUE, col = "tomato")
+# open the inset
+mf_inset_on(x = mtq_target, pos = "topright", cex = .3)
+# display the target municipality
+mf_map(mtq_target, add = FALSE, col = "tomato")
+# close the inset
+mf_inset_off()
+```
+
+Once an inset is opened, map elements can be added to it.
+Here we add a title, a shadow, a scale bar, other Martinique municipalities and a frame.
+
+```{r, fig.height=5.71, fig.width=6, results = FALSE}
+# set a theme
+mf_theme("dark")
+# Selection of a target municipality to display in the inset
+mtq_target <- mtq[c(26), ]
+# Display the base map
+mf_map(mtq, expandBB = c(0, 0, 0, .25))
+# display the target on the main map
+mf_map(mtq_target, add = TRUE, col = "tomato")
+# open the inset
+mf_inset_on(x = mtq_target, pos = "topright", cex = .3)
+# center on on the target munucipality
+mf_map(mtq_target, col = NA, border = NA)
+# display all municipalities
+mf_map(mtq, add = TRUE)
+# display the target municipality shadow
+mf_shadow(mtq_target, add = TRUE)
+# display the target municipality
+mf_map(mtq_target, add = TRUE, col = "tomato")
+# display a title
+mf_title("Saint-Anne",
+ pos = "left", tab = TRUE,
+ cex = .9, line = 1, inner = TRUE
+)
+# display a scale bar
+mf_scale(size = 2)
+# dispaly a frame around the inset
+box()
+# close the inset
+mf_inset_off()
+# display the map layout of the main map
+mf_title("Martinique Municipalities")
+# display a scale bar
+mf_scale(size = 5)
+# display credits
+mf_credits(txt = "T. Giraud, 2021")
+```
+
+The second solution to set the size and position of an inset is to use the `fig` argument.
+`fig` coordinates (xmin, xmax, ymin, ymax) are expressed as fractions of the mapping space (i.e. excluding margins).
+`mf_inset_on(fig = c(0, 0.25, 0, 0.25))` will create an inset on the bottomleft corner of the map and will cover a quarter of the map in width and height.
+
+In the following example we create an inset for a specific municipality in the bottom left corner of the map.
+
+```{r, fig.height=6, fig.width=5, results = FALSE}
+# set a theme
+mf_theme("default", mar = c(0, 0, 0, 0))
+# Display the base map
+mf_map(mtq)
+# open the inset
+mf_inset_on(fig = c(0, 0.25, 0, 0.25))
+# display a municipality
+mf_map(mtq[9, ])
+# add a frame
+box()
+# close the inset
+mf_inset_off()
+```
+
+
+## World Map Inset
+
+It is easy to create an inset with a world map (see `mf_worldmap()`) using `x = "worldmap"`.
+
+```{r, fig.height=6, fig.width=5, results = FALSE}
+mf_map(mtq)
+mf_inset_on(x = "worldmap")
+mf_worldmap(mtq)
+mf_inset_off()
+```
+
+
+
+## Non-cartographic Insets
+Insets can be used for regular plots. In the next map we create an inset with an histogram of the median income distribution using the map classification.
+
+```{r, fig.height=7.58, fig.width=6.25, results = FALSE}
+# create classes
+bks <- mf_get_breaks(x = mtq$MED, nbreaks = 5, breaks = "quantile")
+bks <- round(bks, digits = -2)
+# define a color palette
+pal <- hcl.colors(n = 5, palette = "Dark Mint", rev = TRUE)
+# set a theme
+mf_theme("candy")
+fg <- getOption("mapsf.fg")
+# Create the map
+mf_map(
+ x = mtq, var = "MED", type = "choro",
+ pal = pal, breaks = bks, leg_pos = NA
+)
+# start the inset
+mf_inset_on(fig = c(0.75, .95, 0.84, .99))
+# draw the histogram
+par(mar = c(0, 0, 1.7, 0))
+hist(mtq$MED,
+ breaks = bks, col = pal, border = fg, axes = FALSE, labels = "",
+ xlab = "", ylab = "", main = ""
+)
+axis(
+ side = 1, at = bks, las = 2, tick = FALSE, line = -.9,
+ cex.axis = .7, col.axis = fg
+)
+title("Median Income\nin euros",
+ cex.main = .8, col.main = fg,
+ font.main = 1, adj = 0
+)
+# close the inset
+mf_inset_off()
+# Add map layout
+mf_title("Wealth in Martinique, 2015", pos = "left")
+mf_scale(5)
+mf_credits(paste0(
+ "Sources: Insee and IGN, 2018\n",
+ "mapsf ", packageVersion("mapsf")
+))
+```
+
diff --git a/docs/vignettes/how_to_create_inset_maps.md b/docs/vignettes/how_to_create_inset_maps.md
new file mode 100644
index 0000000..7e4509e
--- /dev/null
+++ b/docs/vignettes/how_to_create_inset_maps.md
@@ -0,0 +1,185 @@
+# How to Create Inset Maps
+Timothée Giraud
+2025-01-22
+
+**`mf_inset*()`** functions create map insets. `mf_inset_on()` starts
+the inset and `mf_inset_off()` closes it.
+
+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.
+
+## Size and Position
+
+There is 2 solutions for defining the size and position of an inset.
+
+The first solution is based on `x`, `pos` and `cex` arguments:
+
+- `x` is an sf object, the width/height ratio of the inset will match
+ the width/height ratio of `x` bounding box;
+- `pos` must be one of “bottomleft”, “left”, “topleft”, “top”,
+ “bottom”, “bottomright”, “right” or”topright”;
+- `cex` defines the share of the map width covered by the inset (0.5
+ means 50%).
+
+In the following example we create an inset for a specific municipality
+in the topright corner of the map.
+
+``` r
+library(mapsf)
+# set a theme
+mf_theme("default", mar = c(0, 0, 0, 0))
+# data import
+mtq <- mf_get_mtq()
+# Selection of a target municipality to display in the inset
+mtq_target <- mtq[c(26), ]
+# Display the base map
+mf_map(mtq, expandBB = c(0, 0, 0, .25))
+# display the target on the main map
+mf_map(mtq_target, add = TRUE, col = "tomato")
+# open the inset
+mf_inset_on(x = mtq_target, pos = "topright", cex = .3)
+# display the target municipality
+mf_map(mtq_target, add = FALSE, col = "tomato")
+# close the inset
+mf_inset_off()
+```
+
+
+
+Once an inset is opened, map elements can be added to it.
+Here we add a title, a shadow, a scale bar, other Martinique
+municipalities and a frame.
+
+``` r
+# set a theme
+mf_theme("dark")
+# Selection of a target municipality to display in the inset
+mtq_target <- mtq[c(26), ]
+# Display the base map
+mf_map(mtq, expandBB = c(0, 0, 0, .25))
+# display the target on the main map
+mf_map(mtq_target, add = TRUE, col = "tomato")
+# open the inset
+mf_inset_on(x = mtq_target, pos = "topright", cex = .3)
+# center on on the target munucipality
+mf_map(mtq_target, col = NA, border = NA)
+# display all municipalities
+mf_map(mtq, add = TRUE)
+# display the target municipality shadow
+mf_shadow(mtq_target, add = TRUE)
+# display the target municipality
+mf_map(mtq_target, add = TRUE, col = "tomato")
+# display a title
+mf_title("Saint-Anne",
+ pos = "left", tab = TRUE,
+ cex = .9, line = 1, inner = TRUE
+)
+# display a scale bar
+mf_scale(size = 2)
+# dispaly a frame around the inset
+box()
+# close the inset
+mf_inset_off()
+# display the map layout of the main map
+mf_title("Martinique Municipalities")
+# display a scale bar
+mf_scale(size = 5)
+# display credits
+mf_credits(txt = "T. Giraud, 2021")
+```
+
+
+
+The second solution to set the size and position of an inset is to use
+the `fig` argument.
+`fig` coordinates (xmin, xmax, ymin, ymax) are expressed as fractions of
+the mapping space (i.e. excluding margins).
+`mf_inset_on(fig = c(0, 0.25, 0, 0.25))` will create an inset on the
+bottomleft corner of the map and will cover a quarter of the map in
+width and height.
+
+In the following example we create an inset for a specific municipality
+in the bottom left corner of the map.
+
+``` r
+# set a theme
+mf_theme("default", mar = c(0, 0, 0, 0))
+# Display the base map
+mf_map(mtq)
+# open the inset
+mf_inset_on(fig = c(0, 0.25, 0, 0.25))
+# display a municipality
+mf_map(mtq[9, ])
+# add a frame
+box()
+# close the inset
+mf_inset_off()
+```
+
+
+
+## World Map Inset
+
+It is easy to create an inset with a world map (see `mf_worldmap()`)
+using `x = "worldmap"`.
+
+``` r
+mf_map(mtq)
+mf_inset_on(x = "worldmap")
+mf_worldmap(mtq)
+mf_inset_off()
+```
+
+
+
+## Non-cartographic Insets
+
+Insets can be used for regular plots. In the next map we create an inset
+with an histogram of the median income distribution using the map
+classification.
+
+``` r
+# create classes
+bks <- mf_get_breaks(x = mtq$MED, nbreaks = 5, breaks = "quantile")
+bks <- round(bks, digits = -2)
+# define a color palette
+pal <- hcl.colors(n = 5, palette = "Dark Mint", rev = TRUE)
+# set a theme
+mf_theme("candy")
+fg <- getOption("mapsf.fg")
+# Create the map
+mf_map(
+ x = mtq, var = "MED", type = "choro",
+ pal = pal, breaks = bks, leg_pos = NA
+)
+# start the inset
+mf_inset_on(fig = c(0.75, .95, 0.84, .99))
+# draw the histogram
+par(mar = c(0, 0, 1.7, 0))
+hist(mtq$MED,
+ breaks = bks, col = pal, border = fg, axes = FALSE, labels = "",
+ xlab = "", ylab = "", main = ""
+)
+axis(
+ side = 1, at = bks, las = 2, tick = FALSE, line = -.9,
+ cex.axis = .7, col.axis = fg
+)
+title("Median Income\nin euros",
+ cex.main = .8, col.main = fg,
+ font.main = 1, adj = 0
+)
+# close the inset
+mf_inset_off()
+# Add map layout
+mf_title("Wealth in Martinique, 2015", pos = "left")
+mf_scale(5)
+mf_credits(paste0(
+ "Sources: Insee and IGN, 2018\n",
+ "mapsf ", packageVersion("mapsf")
+))
+```
+
+
diff --git a/docs/vignettes/how_to_export_maps.Rmd b/docs/vignettes/how_to_export_maps.Rmd
new file mode 100644
index 0000000..d1f3ce0
--- /dev/null
+++ b/docs/vignettes/how_to_export_maps.Rmd
@@ -0,0 +1,112 @@
+---
+title: "How to Export Maps"
+author: "Timothée Giraud"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{How to Export Maps}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.width = 4,
+ fig.height = 4,
+ eval = FALSE
+)
+```
+
+
+**`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 `x`and some theme parameters (figure margins and title size).
+Additionally, `mf_export()` (and `mf_map()`) can be used to extend the map space on one or several side of the figure, or to center a map on a specific area.
+
+
+## Simple Export
+
+In this example we only set the `width` of the exported figure.
+
+```{r, results="hide"}
+library(mapsf)
+mtq <- mf_get_mtq()
+mf_export(
+ x = mtq,
+ filename = "fixed_width.png",
+ width = 500
+)
+mf_map(mtq, add = TRUE)
+mf_title(txt = "PNG export: width=500px, height=605px (deduced)")
+dev.off()
+```
+
+
+
+**Note that we have to set `add = TRUE` to the first layer plotted.** Internally, `mf_export()` start a device (PNG or SVG) with a specific dimension (figure size) and extent (`x` extent).
+
+
+## Export with Extra Space on the Figure
+
+Here we have added some space on the right side of the plot (50% of `x` width).
+
+```{r, results="hide"}
+mf_theme("dark")
+mf_export(
+ x = mtq,
+ filename = "fixed_width_expand.png",
+ width = 500,
+ expandBB = c(0, 0, 0, .5),
+)
+mf_map(mtq, add = TRUE)
+mf_title(txt = "PNG export: width=500px, height=432px (deduced)")
+dev.off()
+mf_theme(NULL)
+```
+
+
+**Note that `mf_export()` uses the current theme. If a theme is set between an `mf_export()` call and a `dev.off()` call it will not be correctly applied.**
+
+
+## Center the Map on a Specific Area
+In this export, the map is focused on a specific spatial object. `height` is fixed and `width` is deduced.
+
+```{r, results="hide"}
+target <- mtq[5, ]
+mf_export(x = target, filename = "fixed_height_centered.png", height = 600)
+mf_map(mtq, add = TRUE)
+mf_shadow(target, add = TRUE)
+mf_map(target, add = TRUE)
+mf_title(txt = "PNG export: height=600px, width=433px (deduced)")
+mf_scale(1, pos = "bottomleft")
+dev.off()
+```
+
+
+## Other Parameters
+`mf_export()` can produce SVG figures (with `export = "svg"`) and use other parameters of `png()` or `svg()` functions (e.g. `res`, `bg` or `family`).
+
+```{r, results="hide"}
+mf_theme("nevermind")
+mf_export(
+ x = mtq,
+ filename = "fixed_width.svg",
+ width = 5,
+ bg = "black"
+)
+mf_map(mtq, add = TRUE)
+mf_title(txt = "SVG export: bg = 'black'")
+dev.off()
+mf_theme(NULL)
+```
+
+
+
+
+
+
diff --git a/docs/vignettes/how_to_export_maps.md b/docs/vignettes/how_to_export_maps.md
new file mode 100644
index 0000000..5782b86
--- /dev/null
+++ b/docs/vignettes/how_to_export_maps.md
@@ -0,0 +1,103 @@
+# How to Export Maps
+Timothée Giraud
+2025-01-22
+
+**`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 `x`and some theme parameters (figure margins and title size).
+Additionally, `mf_export()` (and `mf_map()`) can be used to extend the
+map space on one or several side of the figure, or to center a map on a
+specific area.
+
+## Simple Export
+
+In this example we only set the `width` of the exported figure.
+
+``` r
+library(mapsf)
+mtq <- mf_get_mtq()
+mf_export(
+ x = mtq,
+ filename = "fixed_width.png",
+ width = 500
+)
+mf_map(mtq, add = TRUE)
+mf_title(txt = "PNG export: width=500px, height=605px (deduced)")
+dev.off()
+```
+
+
+
+**Note that we have to set `add = TRUE` to the first layer plotted.**
+Internally, `mf_export()` start a device (PNG or SVG) with a specific
+dimension (figure size) and extent (`x` extent).
+
+## Export with Extra Space on the Figure
+
+Here we have added some space on the right side of the plot (50% of `x`
+width).
+
+``` r
+mf_theme("dark")
+mf_export(
+ x = mtq,
+ filename = "fixed_width_expand.png",
+ width = 500,
+ expandBB = c(0, 0, 0, .5),
+)
+mf_map(mtq, add = TRUE)
+mf_title(txt = "PNG export: width=500px, height=432px (deduced)")
+dev.off()
+mf_theme(NULL)
+```
+
+
+
+**Note that `mf_export()` uses the current theme. If a theme is set
+between an `mf_export()` call and a `dev.off()` call it will not be
+correctly applied.**
+
+## Center the Map on a Specific Area
+
+In this export, the map is focused on a specific spatial object.
+`height` is fixed and `width` is deduced.
+
+``` r
+target <- mtq[5, ]
+mf_export(x = target, filename = "fixed_height_centered.png", height = 600)
+mf_map(mtq, add = TRUE)
+mf_shadow(target, add = TRUE)
+mf_map(target, add = TRUE)
+mf_title(txt = "PNG export: height=600px, width=433px (deduced)")
+mf_scale(1, pos = "bottomleft")
+dev.off()
+```
+
+
+
+## Other Parameters
+
+`mf_export()` can produce SVG figures (with `export = "svg"`) and use
+other parameters of `png()` or `svg()` functions (e.g. `res`, `bg` or
+`family`).
+
+``` r
+mf_theme("nevermind")
+mf_export(
+ x = mtq,
+ filename = "fixed_width.svg",
+ width = 5,
+ bg = "black"
+)
+mf_map(mtq, add = TRUE)
+mf_title(txt = "SVG export: bg = 'black'")
+dev.off()
+mf_theme(NULL)
+```
+
+
diff --git a/docs/vignettes/how_to_use_a_custom_font_family.Rmd b/docs/vignettes/how_to_use_a_custom_font_family.Rmd
new file mode 100644
index 0000000..d19d06d
--- /dev/null
+++ b/docs/vignettes/how_to_use_a_custom_font_family.Rmd
@@ -0,0 +1,55 @@
+---
+title: "How to Use a Custom Font Family"
+author: "Timothée Giraud"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{How to Use a Custom Font Family}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+
+To use a custom font family, the user can use the `family` argument of the `par()` function before plotting the map.
+For example, use `par(family = "Fira Code")` to use the **Fira Code** font.
+Note that the font has to be installed on your system and recognized by R.
+
+
+```{r a, fig.width = 6, fig.height = 7, cache=FALSE, dpi=110, eval = FALSE, fig.path="fig/wo_font_"}
+library(mapsf)
+library(sf)
+# Import the sample data set
+mtq <- mf_get_mtq()
+# population density (inhab./km2) using sf::st_area()
+mtq$POPDENS <- 1e6 * mtq$POP / st_area(mtq)
+# Define the font family
+# !! Select a font already installed on your system !!
+par(family = "Fira Code")
+# set a theme
+mf_theme("green")
+# plot population density
+mf_map(
+ x = mtq,
+ var = "POPDENS",
+ type = "choro",
+ breaks = "q6",
+ nbreaks = 4,
+ pal = "Greens",
+ border = "grey60",
+ lwd = 0.5,
+ leg_val_rnd = 0,
+ leg_pos = "topright",
+ leg_title = "Population Density\n(people per km2)"
+)
+# layout
+mf_layout(
+ title = "Population Distribution in Martinique",
+ credits = paste0(
+ "Sources: Insee and IGN, 2018\n",
+ "mapsf ",
+ packageVersion("mapsf")
+ )
+)
+```
+
+
diff --git a/docs/vignettes/how_to_use_a_custom_font_family.md b/docs/vignettes/how_to_use_a_custom_font_family.md
new file mode 100644
index 0000000..b24542b
--- /dev/null
+++ b/docs/vignettes/how_to_use_a_custom_font_family.md
@@ -0,0 +1,48 @@
+# How to Use a Custom Font Family
+Timothée Giraud
+2025-01-22
+
+To use a custom font family, the user can use the `family` argument of
+the `par()` function before plotting the map. For example, use
+`par(family = "Fira Code")` to use the **Fira Code** font.
+Note that the font has to be installed on your system and recognized by
+R.
+
+``` r
+library(mapsf)
+library(sf)
+# Import the sample data set
+mtq <- mf_get_mtq()
+# population density (inhab./km2) using sf::st_area()
+mtq$POPDENS <- 1e6 * mtq$POP / st_area(mtq)
+# Define the font family
+# !! Select a font already installed on your system !!
+par(family = "Fira Code")
+# set a theme
+mf_theme("green")
+# plot population density
+mf_map(
+ x = mtq,
+ var = "POPDENS",
+ type = "choro",
+ breaks = "q6",
+ nbreaks = 4,
+ pal = "Greens",
+ border = "grey60",
+ lwd = 0.5,
+ leg_val_rnd = 0,
+ leg_pos = "topright",
+ leg_title = "Population Density\n(people per km2)"
+)
+# layout
+mf_layout(
+ title = "Population Distribution in Martinique",
+ credits = paste0(
+ "Sources: Insee and IGN, 2018\n",
+ "mapsf ",
+ packageVersion("mapsf")
+ )
+)
+```
+
+
diff --git a/docs/vignettes/how_to_use_themes.Rmd b/docs/vignettes/how_to_use_themes.Rmd
new file mode 100644
index 0000000..ed5a5e2
--- /dev/null
+++ b/docs/vignettes/how_to_use_themes.Rmd
@@ -0,0 +1,102 @@
+---
+title: "How to Use Themes"
+author: "Timothée Giraud"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+ %\VignetteIndexEntry{How to Use Themes}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.width = 4,
+ fig.height = 4,
+ fig.path = "fig/wo_theme_"
+)
+```
+
+
+**`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).
+
+## Builtin themes
+
+Here are the builtin themes. We have added a grey background color to make the margins more visible.
+```{r, echo = FALSE}
+par(bg = "grey")
+suppressPackageStartupMessages(library(mapsf))
+themes <- c(
+ "default", "ink", "dark", "agolalight", "candy",
+ "darkula", "iceberg", "green", "nevermind", "jsk", "barcelona"
+)
+mtq <- mf_get_mtq()
+for (i in themes) {
+ mf_theme(i)
+ mf_map(mtq)
+ mf_title(paste0('"', i, '"'))
+ box(which = "figure", col = "white")
+}
+```
+
+The following table displays the parameters of these themes.
+
+```{r, echo = FALSE}
+a <- NULL
+for (i in themes) {
+ ax <- mf_theme(i)
+ a <- rbind(a, paste0(ax))
+}
+a <- as.data.frame(a, row.names = themes)
+names(a) <- c("bg", "fg", "mar", "tab", "pos", "inner", "line", "cex", "font")
+# pipe tables by default
+knitr::kable(a)
+```
+
+## How to modify an existing theme
+
+It is possible to modify an existing theme. In this example we use the "default" theme and modify some title parameters.
+```{r, echo = FALSE}
+par(bg = "grey")
+```
+```{r}
+library(mapsf)
+mtq <- mf_get_mtq()
+mf_theme("default", tab = FALSE, font = 4)
+mf_map(mtq)
+mf_title('Mofified "default" theme')
+```
+
+## How to create a new theme
+
+It is possible to create a new theme.
+
+```{r}
+mf_theme(
+ bg = "lightblue", fg = "tomato1", mar = c(0, 2, 0, 2),
+ tab = TRUE, inner = TRUE, line = 1.3, pos = "center",
+ cex = 1.1, font = 3
+)
+mf_map(mtq)
+mf_title("New theme")
+```
+
+
+It is also possible to assign a theme to a variable.
+
+
+```{r}
+blue_theme <- mf_theme("dark", bg = "lightblue")
+green_theme <- mf_theme("default", bg = "lightgreen")
+mf_theme(blue_theme)
+mf_map(mtq)
+mf_title("Blue Theme")
+mf_theme(green_theme)
+mf_map(mtq)
+mf_title("Green Theme")
+```
+
+
diff --git a/docs/vignettes/how_to_use_themes.md b/docs/vignettes/how_to_use_themes.md
new file mode 100644
index 0000000..8e93d14
--- /dev/null
+++ b/docs/vignettes/how_to_use_themes.md
@@ -0,0 +1,254 @@
+# How to Use Themes
+Timothée Giraud
+2025-01-22
+
+**`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).
+
+## Builtin themes
+
+Here are the builtin themes. We have added a grey background color to
+make the margins more visible.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The following table displays the parameters of these themes.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
bg
+
fg
+
mar
+
tab
+
pos
+
inner
+
line
+
cex
+
font
+
+
+
+
+
default
+
#f7f7f7
+
#333333
+
c(0.5, 0.5, 1.7, 0.5)
+
TRUE
+
left
+
FALSE
+
1.2
+
1
+
1
+
+
+
ink
+
#FFDEAD
+
#0000FF
+
c(0, 0, 1.2, 0)
+
FALSE
+
left
+
FALSE
+
1.2
+
0.9
+
2
+
+
+
dark
+
#2E3947
+
#7E848C
+
c(0.5, 0.5, 2, 0.5)
+
FALSE
+
left
+
FALSE
+
1.5
+
1
+
1
+
+
+
agolalight
+
#EDF4F5
+
#82888A
+
c(0, 0, 2, 0)
+
FALSE
+
left
+
FALSE
+
2
+
1.5
+
3
+
+
+
candy
+
#FDFCFE
+
#6B1767
+
c(0, 0, 2, 0)
+
FALSE
+
center
+
FALSE
+
2
+
1.5
+
2
+
+
+
darkula
+
#232525
+
#A9B7C6
+
c(0.5, 0.5, 0.5, 0.5)
+
TRUE
+
right
+
TRUE
+
1.5
+
1
+
4
+
+
+
iceberg
+
#0B0E0E
+
#BDD6DB
+
c(0.5, 0.5, 0.5, 0.5)
+
TRUE
+
right
+
TRUE
+
1.5
+
1
+
4
+
+
+
green
+
#1B1D16
+
#D7FF68
+
c(0.5, 0.5, 2, 0.5)
+
FALSE
+
center
+
FALSE
+
1.5
+
1
+
2
+
+
+
nevermind
+
#4DB8DA
+
#121725
+
c(2, 2, 3.5, 2)
+
FALSE
+
center
+
FALSE
+
1.5
+
1.4
+
1
+
+
+
jsk
+
#ffdc11
+
#0c973c
+
c(0, 0, 1.5, 0)
+
FALSE
+
left
+
FALSE
+
1.5
+
1
+
2
+
+
+
barcelona
+
#160808
+
#d73e23
+
c(0, 0, 1.2, 0)
+
TRUE
+
left
+
FALSE
+
1.2
+
1
+
2
+
+
+
+
+## How to modify an existing theme
+
+It is possible to modify an existing theme. In this example we use the
+“default” theme and modify some title parameters.
+
+``` r
+library(mapsf)
+mtq <- mf_get_mtq()
+mf_theme("default", tab = FALSE, font = 4)
+mf_map(mtq)
+mf_title('Mofified "default" theme')
+```
+
+
+
+## How to create a new theme
+
+It is possible to create a new theme.
+
+``` r
+mf_theme(
+ bg = "lightblue", fg = "tomato1", mar = c(0, 2, 0, 2),
+ tab = TRUE, inner = TRUE, line = 1.3, pos = "center",
+ cex = 1.1, font = 3
+)
+mf_map(mtq)
+mf_title("New theme")
+```
+
+
+
+It is also possible to assign a theme to a variable.
+
+``` r
+blue_theme <- mf_theme("dark", bg = "lightblue")
+green_theme <- mf_theme("default", bg = "lightgreen")
+mf_theme(blue_theme)
+mf_map(mtq)
+mf_title("Blue Theme")
+```
+
+
+
+``` r
+mf_theme(green_theme)
+mf_map(mtq)
+mf_title("Green Theme")
+```
+
+
diff --git a/docs/vignettes/mapsf.Rmd b/docs/vignettes/mapsf.Rmd
new file mode 100644
index 0000000..19f2247
--- /dev/null
+++ b/docs/vignettes/mapsf.Rmd
@@ -0,0 +1,463 @@
+---
+title: 'mapsf'
+author: "Timothée Giraud"
+date: '`r Sys.Date()`'
+output:
+ rmarkdown::html_vignette:
+ fig_width: 8
+ toc: true
+ toc_depth: 1
+ number_sections: true
+vignette: >
+ %\VignetteIndexEntry{mapsf}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+ collapse = TRUE,
+ comment = "#>",
+ fig.width = 5,
+ fig.height = 6
+)
+```
+
+# 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`](https://CRAN.R-project.org/package=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](https://riatelab.github.io/mapsf/articles/web_only/how_to_use_themes.html)
+
+## 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](https://riatelab.github.io/mapsf/articles/web_only/how_to_export_maps.html)
+
+## Datasets
+
+Several datasets are embedded in the package:
+
+- A [GeoPackage](https://www.geopackage.org/) of Martinique municipalities can be imported with `mf_get_mtq()` (or via `sf::st_read()`).
+ - Sources: [Base comparateur de territoires](https://www.insee.fr/fr/statistiques/2521169) (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](https://www.insee.fr/fr/statistiques/3566477) (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()`).
+
+```{r mf_basemap, message=FALSE, warning=FALSE}
+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.
+
+```{r mf_prop, message=FALSE, warning=FALSE}
+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.
+
+```{r mf_map_c}
+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.
+
+```{r mf_map_t}
+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.
+
+```{r mf_map_pc, fig.width=5}
+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.
+
+```{r mf_map_pt, fig.width=5}
+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()`.
+
+```{r mf_label}
+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.
+
+
+```{r mf_grad}
+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
+)
+```
+
+```{r, echo = FALSE}
+mf_theme("default")
+```
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_basemap-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_basemap-1.png
new file mode 100644
index 0000000..73866ac
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_basemap-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_grad-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_grad-1.png
new file mode 100644
index 0000000..7e5f5ff
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_grad-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_label-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_label-1.png
new file mode 100644
index 0000000..7ffab7c
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_label-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_c-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_c-1.png
new file mode 100644
index 0000000..581adbc
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_c-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_pc-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_pc-1.png
new file mode 100644
index 0000000..9d54ff9
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_pc-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_pt-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_pt-1.png
new file mode 100644
index 0000000..46336b5
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_pt-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_t-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_t-1.png
new file mode 100644
index 0000000..34f41f1
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_map_t-1.png differ
diff --git a/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_prop-1.png b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_prop-1.png
new file mode 100644
index 0000000..e33d7e1
Binary files /dev/null and b/docs/vignettes/mapsf.markdown_strict_files/figure-markdown_strict/mf_prop-1.png differ
diff --git a/docs/vignettes/mapsf.md b/docs/vignettes/mapsf.md
new file mode 100644
index 0000000..f536cee
--- /dev/null
+++ b/docs/vignettes/mapsf.md
@@ -0,0 +1,525 @@
+# mapsf
+Timothée Giraud
+2025-01-22
+
+# 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`](https://CRAN.R-project.org/package=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](https://riatelab.github.io/mapsf/articles/web_only/how_to_use_themes.html)
+
+## 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](https://riatelab.github.io/mapsf/articles/web_only/how_to_export_maps.html)
+
+## Datasets
+
+Several datasets are embedded in the package:
+
+- A [GeoPackage](https://www.geopackage.org/) of Martinique
+ municipalities can be imported with `mf_get_mtq()` (or via
+ `sf::st_read()`).
+ - Sources: [Base comparateur de
+ territoires](https://www.insee.fr/fr/statistiques/2521169)
+ (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](https://www.insee.fr/fr/statistiques/3566477) (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()`).
+
+``` r
+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.
+
+``` r
+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.
+
+``` r
+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.
+
+``` r
+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.
+
+``` r
+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.
+
+``` r
+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()`.
+
+``` r
+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.
+
+``` r
+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
+)
+```
+
+
+
+# mapsf
+
+
+
+[](https://cran.r-project.org/package=mapsf)
+[](https://github.com/riatelab/mapsf/actions/workflows/R-CMD-check.yaml)
+[](https://cran.r-project.org/package=mapsf)
+[](https://app.codecov.io/gh/riatelab/mapsf?branch=master)
+[](https://CRAN.R-project.org/package=mapsf)
+[](https://www.bestpractices.dev/projects/8704)
+[](https://www.repostatus.org/#active)
+
+
+Create and integrate thematic maps in your R 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.
+
+## Installation
+
+You can install the released version of `mapsf` from
+[CRAN](https://cran.r-project.org/package=mapsf) with:
+
+``` r
+install.packages("mapsf")
+```
+
+Alternatively, you can install the development version of `mapsf` from
+GitHub (**dev** branch) with:
+
+``` r
+remotes::install_github("riatelab/mapsf", ref = "dev")
+```
+
+## Usage
+
+This is a basic example which shows how to create a map with `mapsf`.
+The main `mapsf` function is `mf_map()`.
+
+``` r
+library(mapsf)
+# Import the sample dataset
+mtq <- mf_get_mtq()
+# Plot the base map
+mf_map(x = mtq)
+# Plot proportional symbols
+mf_map(x = mtq, var = "POP", type = "prop", leg_pos = "topright")
+# Plot a map layout
+mf_layout(
+ title = "Population in Martinique",
+ credits = "T. Giraud; Sources: INSEE & IGN, 2018"
+)
+```
+
+
+
+A more detailed example:
+
+``` r
+# Export a map with a theme and extra margins
+mf_theme("green")
+mf_export(
+ x = mtq, filename = "mtq.png",
+ width = 600, res = 120,
+ expandBB = c(0, 0, 0, .3)
+)
+# Plot a shadow
+mf_shadow(mtq, col = "grey10", add = TRUE)
+# Plot a choropleth map
+mf_map(
+ x = mtq, var = "MED", type = "choro",
+ pal = "Dark Mint",
+ breaks = "quantile",
+ nbreaks = 6,
+ leg_title = "Median Income\n(euros)",
+ leg_val_rnd = -2,
+ add = TRUE
+)
+# Start an inset map
+mf_inset_on(x = "worldmap", pos = "right")
+# Plot mtq position on a worldmap
+mf_worldmap(mtq, col = "#0E3F5C")
+# Close the inset
+mf_inset_off()
+# Plot a title
+mf_title("Wealth in Martinique, 2015")
+# Plot credits
+mf_credits("T. Giraud\nSources: INSEE & IGN, 2018")
+# Plot a scale bar
+mf_scale(size = 5)
+# Plot a north arrow
+mf_arrow("topleft")
+dev.off()
+```
+
+
+
+## Resources
+
+
