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

[![mapsf.gui status
badge](https://riatelab.r-universe.dev/mapsf.gui/badges/version)](https://riatelab.r-universe.dev/mapsf.gui)
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)


**GUI for the mapsf R library to create thematic maps interactively**

`mapsf.gui` is a Shiny application and a RStudio addin that provides an **interactive interface for creating thematic maps** using the [`mapsf`](https://github.com/riatelab/mapsf) package.
It allows users to choose and configure different types of maps such as choropleth, proportional symbols or typology. It also **automatically generates the corresponding R code to reproduce the map identically**.

## Features

- Load and manage multiple spatial datasets.
- Select different types of thematic maps.
- Customize classification methods, color palettes, and most of the visualization parameters handled by `mapsf`.
- Manage various map elements such as legends, title, scale and north arrow.
- Discover the corresponding code in real-time as you construct maps.
- Copy the R code for reproducibility of the maps created.
- Download maps as images (PNG or SVG).

## Limitations and alternatives

`mapsf.gui` is useful for familiarizing yourself with `mapsf` and learning about its main features. However, please note that not all of `mapsf`'s features are available through the GUI. You can consult the [`mapsf` documentation](https://riatelab.github.io/mapsf/) (as well as the various help panels in `mapsf.gui`) to learn more about this.

Moreover, `mapsf.gui` is not intended to replace dedicated thematic cartography software.
If you’re not interested in learning R/mapsf code or in reproducibility, we also develop [Magrit](https://magrit.cnrs.fr): a Web-based thematic cartography app that offers a comprehensive experience for learning or teaching cartography itself.

## Installation

You can install the stable version of `mapsf.gui` from CRAN:

```R
install.packages('mapsf.gui')
```

Alternatively, you can install the development version of `mapsf.gui` from [riatelab's R-universe](https://riatelab.r-universe.dev/) with:

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

You can also install `mapsf.gui` from its Git repository using the following commands:

```R
install.packages("remotes") # if you haven't already
remotes::install_git("https://codeberg.org/riatelab/mapsf.gui.git")
```

## Usage

To launch `mapsf.gui`, simply use the following command in R:

```R
mapsf.gui::run_app()
```

### Changing the viewer

This will open the application in your default Web browser (which is recommended for the best experience).
If you prefer, you can also open it in a dialog or in a pane of your IDE (RStudio, Positron).
This can be controlled with the `viewer` argument and the `browser`, `dialog` or `pane` values:

```R
mapsf.gui::run_app(viewer = "browser")
```

If you're using Positron and the app isn't opening in your default browser, we recommend adding `"positron.viewer.openLocalhostUrls": false` to Positron's `settings.json` file (you can access it by pressing <kbd>CTRL</kbd> + <kbd>P</kbd> and typing `settings` in the search bar that appears).

### RStudio addin

If you are using RStudio, you can also access `mapsf.gui` as an addin from the "Addins" menu.

### Opening the app with preloaded data

If you want to use some datasets already loaded in your R environment,
you can launch the app with the `data` argument:

```R
library(sf)

ne <- st_transform(st_read("/path/to/file.geojson"), crs = 2154)
mun <- st_transform(st_read("/path/to/another-file.shp"), crs = 2154)

mapsf.gui::run_app(data = list(neighborhoods = ne, municipalities = mun))
```

## Screenshots

![](./man/figures/mapsfgui.png)

![](./man/figures/mapsfgui2.png)

## Community Guidelines

One can contribute to the package through [pull requests](https://codeberg.org/riatelab/mapsf.gui/pulls)
and report issues or ask questions [here](https://codeberg.org/riatelab/mapsf.gui/issues).
See the [CONTRIBUTING.md](https://codeberg.org/riatelab/mapsf.gui/src/branch/main/CONTRIBUTING.md)
file for detailed instructions on how to contribute.

Note that this project uses [semantic versioning](https://semver.org/).

## License

GPL-3.0 License. See the [LICENSE](https://codeberg.org/riatelab/mapsf.gui/src/branch/main/LICENSE.md) file for details.

