WorldMapR
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.
Data
For this demonstration, we will use three different databases with a randomly-generated numeric variable associated to each country.
testdata1has 90 rows with only a numeric variable (with some missing values)testdata1bhas 46 rows, with one numeric and one categorical variable (with some missing values)testdata1chas 237 rows, with one numeric and one categorical variable (without any missing values)
head(WorldMapR::testdata1)
#> name countrycode IntVal
#> 1 Aruba AW 22.82
#> 2 Afghanistan AF 5.56
#> 3 American Samoa AS 81.69
#> 4 Antarctica AQ NA
#> 5 Azerbaijan AZ 93.63
#> 6 Benin BJ 11.45
dim(testdata1)
#> [1] 90 3
head(testdata1b)
#> Cnames Cshort VNum VCat
#> 1 Argentina AR NA <NA>
#> 2 Antigua and Barb. AG 22.46 2_Medium
#> 3 Australia AU 13.05 1_Low
#> 4 Austria AT 26.72 2_Medium
#> 5 Bosnia and Herz. BA 0.44 1_Low
#> 6 St-Barthélemy BL 18.91 2_Medium
dim(testdata1b)
#> [1] 46 4
head(testdata1c)
#> name iso_a2 value ValCat
#> 1 Zimbabwe ZW 66.93 3_High
#> 2 Zambia ZM 65.06 3_High
#> 3 Yemen YE 69.57 3_High
#> 4 Vietnam VN 29.26 2_Medium
#> 5 Venezuela VE 64.59 3_High
#> 6 Vatican VA 93.03 3_High
dim(testdata1c)
#> [1] 237 4All these datasets have two variables defining the country for demonstrative purposes (more later);
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.
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.
worldplot(data = testdata1,
ColName = "IntVal",
CountryName = "name",
CountryNameType = "name",
rangeVal = c(0,100))We can focus on a subregion of our interest, by specifying a range
for latitude and longitude arguments
worldplot(data = testdata1,
ColName = "IntVal",
CountryName = "countrycode",
rangeVal = c(0,100),
latitude = c(-40,40), longitude = c(-17,50))
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:
worldplot(data = testdata1,
ColName = "IntVal",
CountryName = "countrycode",
rangeVal = c(0,100),
latitude = c(-40,40), longitude = c(-17,50),
annote = TRUE)
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):
worldplot(data = testdata1,
ColName = "IntVal",
CountryName = "countrycode",
rangeVal = c(0,100),
latitude = c(-40,40), longitude = c(-17,50),
annote = TRUE,
palette_option = "A")
World map for categorical data
The function worldmapCat() deals with categorical
data.
The syntax is similar to the previous, with some minor changes.
worldplotCat(data = testdata1b,
ColName = "VCat",
CountryName = "Cshort",
CountryNameType = "isoa2",
annote = FALSE)
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.
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)
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).
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)