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

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

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

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.

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, 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(-15, 55),
             transform_limits = TRUE)
#> Coordinate system already present. Adding new coordinate system, which will
#> replace the existing one.

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

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.

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