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.
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)
#> 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 4
All 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 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))
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))
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)
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"))
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")
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)
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.