---
title: "WorldMapR"
subtitle: "v. 1.0.1"
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 its main features.

```{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 databases. These datasets 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 takes the name of the dataframe (testdata1), the name of the column with the values to be plotted (IntVal), and the name of the column with 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 name column to be of type ISO 3166-1 alpha-2 (referred as `iso-a2` throughout the package). More information about it can be found at (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). \
It is possible to specify it differently: for example, the following code provides the same result. \
Note that it is advisable to use `iso-a2` 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 a range 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,50))
```

\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,50),
          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,50),
          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,50),
          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 previous, with some minor changes.


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

\newpage

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}

colours <- c("#C3E2EA", "#58C0D0", "#256C91")

worldplotCat(data = testdata1c,
             ColName = "ValCat",
             CountryName = "iso_a2",
             CountryNameType = "isoa2",
             palette_option = colours ,
             Categories = c("Low", "Average", "High"),
             legendTitle = "CAT",
             latitude = c(30,72), longitude = c(-15,40),
             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, if you are interested in selected regions, other reference systems may be preferable.

For example, the 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.

As an example, the two chunks below provide the same map, as they only change for the definition of the limit coordinates and the `transform_limits` argument

```{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(-15, 55),
             transform_limits = TRUE)
```


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

\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()

```

