---
title: "WorldMapR"
subtitle: "v. 0.1.3"
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 with 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 (more later);
\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, the name of the column with the values to be plotted, the name of the column with the country names, and the range of the values that we want to be shown.

```{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

We can focus on a subregion 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

Moreover, it is 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

`palette_option` allows to change the colour palette, by specifying a letter between "A" and "H". These are different color maps from the `scale_fill_viridis()` palette (in a future release, the user will be allowed to define its own palette):

```{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")
```

\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",
             CountryNameType = "isoa2",
             annote = FALSE)
```

\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, you will also need to redefine the values for `longitude` and `latitude` accordingly - these may not be limited to (-180,180) and (-90, 90) anymore, and might be counterintuitive. If this is the case, I suggest to start without defining them  and then searching for the best values with some trial and error.

Notably, the function automatically updates the coordinates of the labels when a different `crs` is defined, meaning that these values might help to find the coordinates you want to show (AVAILABLE IN A FUTURE UPDATE, this information can be extracted only by unfolding the function right now).

```{r,fig.width=7, fig.height=5, fig.retina=3, eval=F}
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(5450000, 1000000), longitude = c(2500000, 6900000),
             crs = 3035, annote = TRUE,
             na.as.category = F)
```

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

```

