WorldMapR"
In WorldMapR: Worldwide or Coordinates-Based Heat Maps

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.

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

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)

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).

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.

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

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:

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.

worldplot(data = testdata1,
          ColName = "IntVal",
          CountryName = "countrycode",
          rangeVal = c(0,100),
          latitude = c(-40,40), longitude = c(-17,53),
          annote = TRUE,
          palette_option = "A")

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.

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.

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.

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".

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

figure1 <- worldplot(data = testdata1,
                     ColName = "IntVal",
                     CountryName = "name",
                     CountryNameType = "name",
                     rangeVal = c(0,100))

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

figure1

dev.off()

Editable maps in powerpoint

The function empty_editable_map creates a map which can be saved in PowerPoint and edited from there. By default, this function creates a blank map.

# create the map
empty_editable_map(lon = c(-15, 40), lat = c(20, 65), crs = 4326)

# save it
export::graph2ppt(file ="editable_map15.pptx", width = 7, height = 4)