Retrieving boundaries with get_boundary()
getboundary.Rmdget_boundary() can be used to retrieve a variety of
marine and terrestrial boundary types. Details on the options are in the
help file ?get_boundary(), but figuring out exactly how to
get a particular type of boundary can still be confusing. Here we
provide some examples.
Marine boundaries
get_boundary() uses the
mregions2::mrp_get() function from the mregions2
package - the R package for the Marine Regions database. This database
is quite extensive and has several options for querying areas.
get_boundary() is not intended to provide all the
functionality of mregions2, just a slightly simpler
interface for getting commonly used boundaries such as exclusive
economic zones (EEZs), global ocean boundaries, and high seas areas.
When using get_boundary() with
type = "eez", type = "12nm" or
type = "24nm", the country_type can be either
country_type = "country" or
country_type = "sovereign". Using "country"
returns only the EEZ, 12nm or 24nm boundary of the mainland country,
while using "sovereign" returns boundaries for all the
states and territories that a country has sovereignty over as well. The
examples below show how this works.
Note that if type = "ocean" or
type = "high_seas", country_type is
ignored.
Here is a simple query to get Australia’s EEZ:
aus_eez <- get_boundary(name = "Australia", type = "eez")
plot(aus_eez["geometry"], axes = TRUE)
But lets look at what happens if we change the
country_type from the default "country" to
"sovereign":
aus_eez_sov <- get_boundary(name = "Australia", type = "eez", country_type = "sovereign")
plot(aus_eez_sov["geometry"], axes = TRUE)
We now get not just the main country of Australia, but all the
islands it has sovereignty over. For more detail, see the Marine Regions
attribute table; using country_type = "country" queries
using the ‘territory1’ attribute, and using
country_type = "sovereign" uses the ‘territory1’
attribute.
Here is another example using France. Only the EEZ bordering mainland
France is retrieved if country_type = "country", but
setting country_type = "sovereign" we also get all the
islands France has sovereignty over.
#check if rnaturalearthdata package is installed and give option to install if not
rnaturalearth::check_rnaturalearthdata()
fr_eez <- get_boundary(name = "France", type = "eez", country_type = "country")
fr_eez_sov <- get_boundary(name = "France", type = "eez", country_type = "sovereign")
plot(sf::st_geometry(fr_eez_sov), lwd = 1, axes = TRUE)
plot(fr_eez["geometry"], col = "royalblue", add = T)
plot(rnaturalearth::ne_coastline(scale = 110)["geometry"], lty = 3, add = TRUE)
EEZ of mainland France (blue) and all overseas territories (solid outlines). World coastlines are shown as dashed line for reference.
An example, where you might want to use sovereign is
when you are trying to get all the islands that make up Kiribati. Using
country_type = "country" does not return anything because
each island group is listed as a country. Note that if the
name provided is not found, the function will error and
print a list of all possible country_type options:
get_boundary(name = "Kiribati", type = "eez", country_type = "country")
#> [1] "Abu musa, Greater and Lesser Tunb" "Alaska" "Albania"
#> [4] "Algeria" "Alhucemas Islands" "American Samoa"
#> [7] "Amsterdam and Saint Paul Islands" "Andaman and Nicobar" "Angola"
#> [10] "Anguilla" "Antigua and Barbuda" "Argentina"
#> [13] "Aruba" "Ascension" "Australia"
#> [16] "Azerbaijan" "Azores" "Bahamas"
#> [19] "Bahrain" "Bajo Nuevo Bank" "Bangladesh"
#> [22] "Barbados" "Bassas da India" "Belgium"
#> [25] "Belize" "Benin" "Bermuda"
#> [28] "Bonaire" "Bosnia and Herzegovina" "Brazil"
#> [31] "British Virgin Islands" "Brunei" "Bulgaria"
#> [34] "Cambodia" "Cameroon" "Canada"
#> [37] "Canary Islands" "Cape Verde" "Cayman Islands"
#> [40] "Ceuta" "Chafarinas Islands" "Chagos Archipelago"
#> [43] "Chile" "China" "Christmas Island"
#> [46] "Clipperton Island" "Cocos Islands" "Collectivity of Saint Martin"
#> [49] "Colombia" "Comores" "Cook Islands"
#> [52] "Costa Rica" "Croatia" "Crozet Islands"
#> [55] "Cuba" "Curaçao" "Cyprus"
#> [58] "Democratic Republic of the Congo" "Denmark" "Djibouti"
#> [61] "Dominica" "Dominican Republic" "Doumeira Islands"
#> [64] "East Timor" "Easter Island" "Ecuador"
#> [67] "Egypt" "El Salvador" "Equatorial Guinea"
#> [70] "Eritrea" "Estonia" "Europa Island"
#> [73] "Faeroe" "Falkland / Malvinas Islands" "Federal Republic of Somalia"
#> [76] "Fiji" "Finland" "France"
#> [79] "French Guiana" "French Polynesia" "Gabon"
#> [82] "Galapagos" "Gambia" "Georgia"
#> [85] "Germany" "Ghana" "Gibraltar"
#> [88] "Gilbert Islands" "Glorioso Islands" "Greece"
#> [91] "Greenland" "Grenada" "Guadeloupe"
#> [94] "Guam" "Guatemala" "Guernsey"
#> [97] "Guinea" "Guinea-Bissau" "Guyana"
#> [100] "Haiti" "Halaib Triangle" "Hawaii"
#> [103] "Heard and McDonald Islands" "Honduras" "Howland and Baker Islands"
#> [106] "Iceland" "Ile Tromelin" "India"
#> [109] "Indonesia" "Iran" "Iraq"
#> [112] "Ireland" "Islas San Félix and San Ambrosio" "Isle of Man"
#> [115] "Israel" "Italy" "Ivory Coast"
#> [118] "Jamaica" "Jan Mayen" "Japan"
#> [121] "Jarvis Island" "Jersey" "Johnston Atoll"
#> [124] "Jordan" "Juan de Nova Island" "Kazakhstan"
#> [127] "Kenya" "Kerguélen" "Kuril Islands"
#> [130] "Kuwait" "Latvia" "Lebanon"
#> [133] "Liancourt Rocks" "Liberia" "Libya"
#> [136] "Line Group" "Lithuania" "Macquarie Island"
#> [139] "Madagascar" "Madeira" "Malaysia"
#> [142] "Maldives" "Malta" "Marshall Islands"
#> [145] "Martinique" "Matthew and Hunter Islands" "Mauritania"
#> [148] "Mayotte" "Melilla" "Mexico"
#> [151] "Micronesia" "Monaco" "Montenegro"
#> [154] "Montserrat" "Morocco" "Mozambique"
#> [157] "Myanmar" "Namibia" "Nauru"
#> [160] "Navassa Island" "Netherlands" "New Caledonia"
#> [163] "New Zealand" "Nicaragua" "Nigeria"
#> [166] "Niue" "Norfolk Island" "North Korea"
#> [169] "Northern Mariana Islands" "Norway" "Oecusse"
#> [172] "Oman" "Pakistan" "Palau"
#> [175] "Palestine" "Palmyra Atoll" "Panama"
#> [178] "Papua New Guinea" "Peñón de Vélez de la Gomera" "Perejil Island"
#> [181] "Peru" "Philippines" "Phoenix Group"
#> [184] "Pitcairn" "Poland" "Portugal"
#> [187] "Prince Edward Islands" "Puerto Rico" "Qatar"
#> [190] "Quitasueño Bank" "Republic of Mauritius" "Republic of the Congo"
#> [193] "Réunion" "Romania" "Russia"
#> [196] "Saba" "Saint Helena" "Saint Kitts and Nevis"
#> [199] "Saint Lucia" "Saint Vincent and the Grenadines" "Saint-Barthélemy"
#> [202] "Saint-Pierre and Miquelon" "Samoa" "Sao Tome and Principe"
#> [205] "São Tomé and Principe" "Saudi Arabia" "Senegal"
#> [208] "Senkaku Islands" "Serrana Bank" "Serranilla Bank"
#> [211] "Seychelles" "Sierra Leone" "Singapore"
#> [214] "Sint-Eustatius" "Sint-Maarten" "Slovenia"
#> [217] "Solomon Islands" "South Africa" "South Georgia and the South Sandwich Islands"
#> [220] "South Korea" "Spain" "Sri Lanka"
#> [223] "Sudan" "Suriname" "Svalbard"
#> [226] "Sweden" "Syria" "Taiwan"
#> [229] "Tanzania" "Thailand" "Togo"
#> [232] "Tokelau" "Tonga" "Trindade"
#> [235] "Trinidad and Tobago" "Tristan da Cunha" "Tunisia"
#> [238] "Turkey" "Turkmenistan" "Turks and Caicos Islands"
#> [241] "Tuvalu" "Ukraine" "United Arab Emirates"
#> [244] "United Kingdom" "United States" "United States Virgin Islands"
#> [247] "Uruguay" "Vanuatu" "Venezuela"
#> [250] "Vietnam" "Wake Island / Enenkio" "Wallis and Futuna"
#> [253] "Western Sahara" "Yemen"
#> Error:
#> ! "Kiribati" is not a valid name. Please re-run get_boundary() with one of the names above.Try again, setting country_type = "sovereign":
kir_eez <- get_boundary(name = "Kiribati", type = "eez", country_type = "sovereign")
plot(sf::st_geometry(kir_eez), col = "royalblue")
plot(rnaturalearth::ne_coastline(scale = 110)["geometry"], lty = 3, add = TRUE)
Kiribati’s EEZ. World coastlines are shown as dashed line for reference.
The mregions2 package can be used to query many
different marine boundaries, not all of which are included as options
for get_boundary():
| title | layer |
|---|---|
| Exclusive Economic Zones (200 NM) (v11, world, 2019) | eez |
| Maritime Boundaries (v11, world, 2019) | eez_boundaries |
| Territorial Seas (12 NM) (v3, world, 2019) | eez_12nm |
| Contiguous Zones (24 NM) (v3, world, 2019) | eez_24nm |
| Internal Waters (v3, world, 2019) | eez_internal_waters |
| Archipelagic Waters (v3, world, 2019) | eez_archipelagic_waters |
| High Seas (v1, world, 2020) | high_seas |
| Extended Continental Shelves (v01, world, 2022) | ecs |
| Extended Continental Shelves - boundaries (v01, world, 2022) | ecs_boundaries |
| IHO Sea Areas (v3) | iho |
| Global Oceans and Seas (v1) | goas |
| The intersect of the Exclusive Economic Zones and IHO areas (v4) | eez_iho |
| Marine and land zones: the union of world country boundaries and EEZ’s | eez_land |
| Global Biogeochemical Provinces (Longhurst) | longhurst |
| Global contourite distribution | cds |
| Emission Control Areas (ECAs) designated under regulation 13 of MARPOL Annex VI (NOx emission control) | eca_reg13_nox |
| Emission Control Areas (ECAs) designated under regulation 14 of MARPOL Annex VI (SOx and particulate matter emission control) | eca_reg14_sox_pm |
| UNESCO World Heritage Marine Sites (v02, 2023) | worldheritagemarineprogramme |
| The 66 Large Marine Ecosystems of the World | lme |
| Marine Ecoregions of the World - Ecoregions | ecoregions |
| SeaVoX - Sea Areas Polygons (v18, 2021) | seavox_v18 |
Land boundaries
get_boundary() uses the
rnaturalearth::ne_countries() function from the rnaturalearth
package to retrieve land boundaries. get_boundary() is only
intended to provide a slightly simpler interface for getting some
commonly used land boundaries.
As with maritime boundaries, the country_type can be
specified as either country_type = "country" or
country_type = "sovereign" depending on whether only the
main country is required or the country and all territories/ states it
has sovereignty over. The following examples show how these options work
in practice.
The rnaturalearth package vignette
contains more details about what constitutes a country and more options
for querying.
If we query France setting country_type = "country" we
get:
france <- get_boundary(name = "France", type = "country", country_type = "country")
plot(sf::st_geometry(france), col = "blue")
plot(rnaturalearth::ne_coastline(scale = 110)["geometry"], lty = 3, add = TRUE)
This is slightly unexpected perhaps, but the islands of Guadeloupe and Martinique in the Caribbean, Mayotte and Réunion in the Western Indian Ocean, and French Guiana in South America, all have the same status as mainland France.
If we use country_type = "sovereign", we also get
France’s overseas territories in the Pacific, Atlantic and
Antarctic:
france_sov <- get_boundary(name = "France", type = "country", country_type = "sovereign")
plot(sf::st_geometry(france_sov), col = "blue")
plot(rnaturalearth::ne_coastline(scale = 110)["geometry"], lty = 3, add = TRUE)