# mapsf <img src="man/figures/logo.png" align="right" width="120"/>

[![CRAN](https://www.r-pkg.org/badges/version-ago/mapsf)](https://cran.r-project.org/package=mapsf)
[![mapsf status
badge](https://riatelab.r-universe.dev/mapsf/badges/version)](https://riatelab.r-universe.dev/mapsf)
![code coverage:
95%](https://img.shields.io/badge/code_coverage-95%25-green)
[![status](https://tinyverse.netlify.app/badge/mapsf)](https://CRAN.R-project.org/package=mapsf)
[![downloads](https://cranlogs.r-pkg.org/badges/mapsf?color=brightgreen)](https://cran.r-project.org/package=mapsf)

**Create thematic maps and integrate them into your R workflow.**

This package helps you design different cartographic representations
such as proportional symbols, choropleths, or typology maps. It also
provides several functions for displaying layout elements that enhance
the graphical 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` (the
**dev** branch) from [r-universe](https://riatelab.r-universe.dev/mapsf)
with:

``` r
install.packages("mapsf", repos = c("https://riatelab.r-universe.dev", "https://cloud.r-project.org"))
```

## Usage

This is a basic example which shows how to create a map with `mapsf`.

``` 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", add = TRUE)
# Plot a map layout
mf_layout(
  title = "Population in Martinique",
  credits = "T. Giraud; Sources: INSEE & IGN, 2018"
)
```

<img src="man/figures/example1-1.png" alt="A simple map created with mapsf"  />

You can find more detailed examples on the [“Get
Started”](https://riatelab.github.io/mapsf/articles/mapsf) section of
the [package website](https://riatelab.github.io/mapsf/) and you can
also download its [cheat
sheet](https://raw.githubusercontent.com/riatelab/mapsf/master/vignettes/fig/mapsf_cheatsheet.pdf).\
[![Cheat
Sheet](man/figures/mapsf_cheatsheet.png)](https://raw.githubusercontent.com/riatelab/mapsf/master/vignettes/fig/mapsf_cheatsheet.pdf)

## mapsf.gui <img src="man/figures/mapsf_gui_logo.png" alt="mapsf.gui logo" align="right" width="60"/>

The [`mapsf.gui` package](https://codeberg.org/riatelab/mapsf.gui)
provides a Shiny interface for creating thematic maps using `mapsf`.
Users of the application can **build thematic maps interactively and
automatically generate the corresponding R code** to reproduce the map
identically.

## Alternatives

- [`tmap`](https://github.com/r-tmap/tmap)
- [`ggplot2`](https://github.com/tidyverse/ggplot2) +
  [`ggspatial`](https://github.com/paleolimbot/ggspatial)

## Community Guidelines

One can contribute to the package through [pull
requests](https://github.com/riatelab/mapsf/pulls) and report issues or
ask questions [here](https://github.com/riatelab/mapsf/issues). See the
[CONTRIBUTING.md](https://github.com/riatelab/mapsf/blob/master/CONTRIBUTING.md)
file for detailed instructions on how to contribute.\
This project uses [conventional
commits](https://www.conventionalcommits.org/en/v1.0.0-beta.3/) and
[semantic versioning](https://semver.org/).