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. These datasets contain 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; however, only one is actually needed.
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).
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))Focusing on regions
We can focus on a region 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))
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,50),
annote = TRUE)
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,50),
annote = TRUE,
palette_option = "A")
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"))
World map for categorical data
The function worldmapCat() deals with categorical
data.
The syntax is similar to the previous, with some minor changes.
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, 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
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)
#> Coordinate system already present. Adding new coordinate system, which will
#> replace the existing one.
For additional information regarding the transformation of coordinates in different systems, have a look at https://epsg.io/transform