---
title: "WorldMapR"
subtitle: "v. 1.1.0"
output: rmarkdown::html_vignette
author: Luigi Annicchiarico
date: "`r format(Sys.time(), '%d %B, %Y')`"
vignette: >
  %\VignetteIndexEntry{WorldMapR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

The aim of this package is to create maps of the world or sub regions based on user-defined coordinates, filling them based on the provided data. This vignette will highlight the main features and options.

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, warning = FALSE}
library(WorldMapR)
```

# Data

For this demonstration we will use three different datasets, which contain a randomly-generated numeric variable associated to each country.

- `testdata1` has 90 rows with only a numeric variable (with some missing values)
- `testdata1b` has 46 rows, with one numeric and one categorical variable (with some missing values) 
- `testdata1c` has 237 rows, with one numeric and one categorical variable (without any missing values)

```{r}
head(WorldMapR::testdata1)
dim(testdata1)

head(testdata1b)
dim(testdata1b)

head(testdata1c)
dim(testdata1c)
```

All these datasets have two variables defining the country for demonstrative purposes; however, only one is actually needed.

\newpage

# Displaying a world map for continuous data

As a first step, we may want to plot a map of the world, displaying our data.

We can do this by using the function `worldplot()`.
At its bare minimum, this function requires to enter

- the name of the dataframe (testdata1, in our example)
- the name of the column with the values to be plotted (IntVal)
- the name of the column containing the country names (countrycode).

We also add the range of the values that we want to be shown (these should usually be near to the minimum and the maximum observation that we want to plot).

```{r, fig.width=7, fig.height=5, fig.retina=3}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100))
```

By default, the function expects the country names column to be of type ISO 3166-1 alpha-2 (referred as `iso-a2` throughout the package). Some information about this codification can be found at (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). \
It is possible to specify it differently with the argument `CountryNameType`: for example, the following code provides the same result as the chunk above. \
Note that it is advisable to use `iso-a2` (or `iso-a3`) codes, as country names might be ambiguous in some cases.

```{r, eval=FALSE}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "name",
          CountryNameType = "name",
          rangeVal = c(0,100))
```

\newpage

## Focusing on regions

We can focus on a region of our interest, by specifying bounds (minimum and maximum) for `latitude` and `longitude` arguments

```{r,fig.width=7, fig.height=5, fig.retina=3}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100),
          latitude = c(-40,40), longitude = c(-17,53))
```

\newpage

## Adding country labels

It is also possible to add labels to identify each country present in the database (countries without correspondences in the provided data set or with missing value are not considered). To do this, it is sufficient to add the option `annote = TRUE`:

```{r,fig.width=7, fig.height=5, fig.retina=3}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100),
          latitude = c(-40,40), longitude = c(-17,53),
          annote = TRUE)
```

\newpage

## Colour palettes

`palette_option` allows to change the colour palette:

- By specifying a letter between "A" and "H", we obtain different palettes from the `scale_fill_viridis()` palette
- By specifying two or more colours inside a vector, we obtain a user defined gradient based on the colours we have defined.

```{r,fig.width=7, fig.height=5, fig.retina=3}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100),
          latitude = c(-40,40), longitude = c(-17,53),
          annote = TRUE,
          palette_option = "A")
```

```{r,fig.width=7, fig.height=5, fig.retina=3}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100),
          latitude = c(-40,40), longitude = c(-17,53),
          annote = TRUE,
          palette_option = c("#00A600", "#63C600", "#E6E600", "#E9BD3A", "#ECB176", "#EFC2B3"))
```
\newpage

# World map for categorical data

The function `worldmapCat()` deals with categorical data.

The syntax is similar to the one we have just explained, with some minor changes.


```{r,fig.width=7, fig.height=5, fig.retina=3}
worldplotCat(data = testdata1b,
             ColName = "VCat",
             CountryName = "Cshort")
```

\newpage

Once again, the user is allowed to define the color palette manually: it is simply required to define a colour for each category (plus eventually one for missing data), and provide it in `palette_option`.

```{r,fig.width=7, fig.height=5, fig.retina=3}
worldplotCat(data = testdata1c,
             ColName = "ValCat",
             CountryName = "iso_a2",
             CountryNameType = "isoa2",
             palette_option = c("#C3E2EA", "#58C0D0", "#256C91"),
             Categories = c("Low", "Average", "High"),
             legendTitle = "CAT",
             latitude = c(30,72), longitude = c(-15,42),
             annote = TRUE)
```

\newpage

# Changing the Coordinates Reference System 

The program also allows to use different coordinate systems. 
By default, the EPSG::4326 (WGS84) reference system is used. This is a nice system if you want to plot the whole world; however, other reference systems may be preferable.

As a first example, EPSG::3035 is a nice projection specifically thought for Europe maps.
The option `crs` allows to define the coordinate reference system of choice.
Keep in mind that, if you change the reference system, there will be the need to modify `longitude` and `latitude` accordingly - these may not be limited to (-180,180) and (-90, 90) anymore. The option `transform_limits` helps to deal with this issue: if set to `TRUE` (which is the default), the values of latitude and longitude are automatically updated to the crs that had been defined previously. Usually, it is easier to use the classical longitude and latitude definition for the limits, and let the program automatically update it based on the new crs.

```{r,fig.width=7, fig.height=5, fig.retina=3, eval=TRUE}
worldplotCat(data = testdata1c,
             ColName = "ValCat",
             CountryName = "iso_a2",
             CountryNameType = "isoa2",
             palette_option = c("#C3E2EA", "#58C0D0", "#256C91"),
             Categories = c("Low", "Average", "High"),
             legendTitle = "CAT",
             annote = TRUE,  na.as.category = F,
             crs = 3035,
             latitude = c(30, 66), longitude = c(-13, 55.5),
             transform_limits = TRUE)
```

We note a message telling us that the coordinate reference system has indeed been changed.

As another example, an alternative to EPSG:4326 for plotting the whole world is EPSG:3857, which is known as "Web Mercator projection".

```{r, fig.width=7, fig.height=5, fig.retina=3}
worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100),
          crs = 3857,
          longitude = c(-180, 180), latitude = c(-85, 85))
```


For additional information regarding the transformation of coordinates in different systems, have a look at https://epsg.io/transform.

In general, https://epsg.io provides useful information for each specific EPSG system, such as the WGS84 coordinate bounds and the projected bounds

Note that the `crs` and the `transform_limits` arguments are still under development; when changing the coordinate reference system (especially when using rare crs or out of bounds coordinates) errors might be encountered.

In a future release, ESRI projections will be available, in addition to EPSG.

\newpage

# Saving the plot

The plot can be saved using external functions; for example

```{r, eval=FALSE}
figure1 <- worldplot(data = testdata1,
                     ColName = "IntVal",
                     CountryName = "name",
                     CountryNameType = "name",
                     rangeVal = c(0,100))

tiff(filename =  paste(tempdir(), "/figure.tiff"))

figure1

dev.off()

```

