Package 'islandcodes'

Title: Reference Data and Helpers for Small Island States and Territories
Description: A curated reference list of countries and territories with classifications for Small Island Developing States (SIDS), sub-national island jurisdictions (SNIJ), World Bank region and income group, and political association. Sub-sovereign cases such as Aruba, Curacao, Bonaire, Sint Maarten, the French overseas territories, and Aaland Islands are represented with disambiguating codes that standard country-code packages often collapse or omit. Provides predicate helpers and a tidy joiner intended to extend rather than replace 'countrycode'. Source data is maintained at <https://github.com/University-of-Aruba/island-research-reference-data> and licensed CC BY 4.0.
Authors: Rendell de Kort [aut, cre] (ORCID: <https://orcid.org/0009-0006-5402-0500>), University of Aruba [cph, fnd] (Digital Competence Dutch Caribbean (DCDC) Network)
Maintainer: Rendell de Kort <[email protected]>
License: CC BY 4.0
Version: 0.2.0.9000
Built: 2026-09-28 07:25:55 UTC
Source: https://github.com/university-of-aruba/islandcodes

Help Index

Add island classification columns to a data frame

Description

Left-joins selected columns from islands onto an existing data frame, matching on a column of country names or ISO codes. Designed for tidy pipelines but written in base R, so it works with plain data frames, tibbles, and (read-only) data.tables.

Usage

add_island_cols(
  .data,
  code_col,
  cols = c("iso_code", "is_sids", "is_snij", "sids_tier", "political_association",
    "wb_region", "wb_income_group")
)

Arguments

.data

A data frame.
code_col

String. Name of the column in .data that holds country names or ISO codes.
cols

Character vector of columns from islands to attach. Defaults to the most common classification fields.

Value

.data with the requested columns appended. Rows whose code_col value cannot be resolved get NA in the new columns.

Examples

df <- data.frame(
  country = c("Aruba", "Curacao", "Bonaire", "Brazil"),
  gdp = c(3.5, 3.1, 0.5, 1900)
)
add_island_cols(df, "country")

A.R.U.B.A.: Annotated Reference for Under-coded Border Areas

Description

A convenience wrapper around island_lookup with Aruba as the default. Calling aruba() returns Aruba's classification row; passing another country or ISO code returns that one instead.

Usage

aruba(x = "Aruba", quiet = getOption("islandcodes.aruba.quiet", FALSE))

Arguments

x

A character vector of country names or ISO codes. Defaults to "Aruba".
quiet

Logical. If FALSE (the default in interactive sessions, when called with no arguments) a short homage message is printed once. Set to TRUE, or set options(islandcodes.aruba.quiet = TRUE) globally, to silence.

Details

Named in homage to Edward Cheung, the Aruban engineer at NASA Goddard who designed A.R.U.B.A. (the ASCS/NCS Relay Unit Breaker Assembly) installed on the Hubble Space Telescope during the 2002 servicing mission. Cheung engineered the backronym specifically so children in his home country would have something concrete to point to on the telescope. We borrowed the trick. His ARUBA cuts power to Hubble's instruments when there is a fault; ours returns a row of classification data. Both spell Aruba.

Value

A data frame with one row per element of x (the same shape as island_lookup).

Examples

aruba()
aruba("Curacao")
aruba(c("AW", "BQ-BO", "CW"))

Classify countries and territories

Description

Predicate helpers that return a logical vector aligned with the input.

Usage

is_sids(x)

is_snij(x)

is_small_island(x)

Arguments

x

A character vector of ISO codes or country names.

Details

Inputs are resolved in three passes: direct match against the iso_code column of islands, then a case-insensitive match against name, then a fallback through countrycode from "country.name" to "iso2c". Unresolved entries return NA.

Hyphenated codes ("BQ-BO" for Bonaire, "BQ-SE" for Sint Eustatius, "BQ-SA" for Saba) are accepted directly. Bare "BQ" is ambiguous within the bundled dataset; pass the specific island code or the country name instead.

Value

A logical vector the same length as x.

Examples

is_sids(c("Aruba", "Curacao", "Bonaire", "Brazil"))
is_snij(c("Aruba", "Curacao", "Bonaire", "Brazil"))
is_small_island(c("AW", "CW", "BQ-BO", "BR", "AX"))

Get coordinates for islands and territories

Description

Returns the latitude and longitude of a vector of country names or ISO codes, one row per input and in input order (with NA rows for unresolved inputs). Two location semantics are available: a representative point on the territory's main landmass (the default), or the capital city.

Usage

island_coords(x, which = c("point", "capital"))

Arguments

x

A character vector of ISO codes or country names.
which

Which location to return: "point" (default), a representative point on the main landmass, or "capital", the capital city.

Details

Inputs are resolved the same way as the predicate helpers (see is_sids): by iso_code, then label, then the XLSForm name slug, then a fallback through countrycode.

Coordinates are WGS84 decimal degrees. A handful of territories carry no coordinate and return NA: the representative point is missing only for United States Minor Outlying Islands (a scattered, centroid-less collection), while capitals are missing for uninhabited or capital-less territories (Antarctica, Bouvet Island, the British Indian Ocean Territory, Heard Island, South Georgia, Tokelau, US Minor Outlying Islands, and Western Sahara).

Value

A data frame with one row per element of x. For which = "point" the columns are label (the readable place name), iso_code, latitude, and longitude. For which = "capital" a capital city-name column is inserted before the coordinates.

See Also

island_lookup for arbitrary columns, add_island_cols to attach coordinates to a data frame.

Examples

island_coords(c("Aruba", "Curacao", "Bonaire"))

# Capital cities instead of landmass points
island_coords(c("AW", "PF", "GL"), which = "capital")

# The two can differ substantially for dispersed territories
island_coords("French Polynesia")
island_coords("French Polynesia", which = "capital")

Great-circle distance between islands

Description

Haversine (great-circle) distance between the coordinates of islands and territories, resolved from country names or ISO codes via the same matching as the rest of the package (see is_sids). A natural primitive for connectivity and isolation work on small islands.

Usage

island_distance(
  x,
  y = NULL,
  which = c("point", "capital"),
  unit = c("km", "mi", "nmi")
)

Arguments

x

A character vector of ISO codes or country names.
y

Optional second character vector. If NULL (the default) a full symmetric distance matrix among the elements of x is returned. If supplied, distances are computed element-wise between x and y, recycling the shorter of the two, so a single origin against many destinations gives the distance from that origin to each.
which

Coordinate to use: "point" (representative landmass point, the default) or "capital" (capital city).
unit

Output unit: "km" (kilometres, the default), "mi" (statute miles), or "nmi" (nautical miles).

Value

When y is NULL, a numeric matrix (length(x) by length(x)) with iso_code dimnames. Otherwise a named numeric vector. Unresolved inputs and territories without the requested coordinate propagate as NA.

See Also

island_coords

Examples

# Spread of the Dutch Caribbean (ABC + SSS), in km
round(island_distance(c("AW", "CW", "BQ-BO", "SX", "BQ-SA", "BQ-SE")))

# One origin to many
island_distance("Aruba", c("Curacao", "Bonaire", "Sint Maarten"))

# Capital-to-capital, in nautical miles
island_distance("AW", "CW", which = "capital", unit = "nmi")

Look up rows in the islands reference list

Description

Returns the matching rows of islands for a vector of country names or ISO codes. Useful when you want more than a single classification and want to keep the original input order, including NA rows for unresolved inputs.

Usage

island_lookup(x, fields = NULL)

Arguments

x

A character vector of ISO codes or country names.
fields

Optional character vector of column names to return. If NULL (default) all columns of islands are returned.

Value

A data frame with one row per element of x. Rows that could not be resolved are filled with NA.

Examples

island_lookup(c("Aruba", "Bonaire", "Brazil"))
island_lookup(c("AW", "BQ-BO"), fields = c("name", "is_sids", "is_snij"))

Distance-decayed market access

Description

Market access of each origin as the sum of destination mass discounted by distance, MAi=∑j≠imjdij−θMA_i = \sum_{j \neq i} m_j d_{ij}^{-\theta}. This is the standard reduced-form measure used in economic geography and in the remote-sensing literature on rural connectivity, where access rather than raw distance is the quantity that predicts economic outcomes.

Usage

island_market_access(
  x,
  mass,
  to = NULL,
  theta = 1,
  which = c("point", "capital"),
  unit = c("km", "mi", "nmi"),
  self = NULL
)

Arguments

x

A character vector of ISO codes or country names: the origins.
mass

Numeric vector of destination mass. If named, names are resolved the same way as x and matched to the destinations, so the vector may be in any order and may cover more territories than are used. If unnamed, it must be the same length as the destinations and in the same order.
to

Optional character vector of destinations. Defaults to NULL, meaning the destinations are x itself (access within the set).
theta

Positive distance-decay elasticity. Default 1.
which

Coordinate to use: "point" (representative landmass point, the default) or "capital".
unit

Distance unit the decay operates on: "km" (default), "mi", or "nmi". Changing it rescales the result by a constant factor, so it matters for levels but not for rankings.
self

Optional internal distance, in unit, used to include each origin's own mass as m_i * self^-theta. A single number, or one per element of x. NULL (default) excludes own mass.

Details

The package supplies the geometry, not the mass. Population, GDP, tourist arrivals, and trade volumes are all time-varying and contested, so mass is always user-supplied and the reference year is the caller's to document. theta is likewise a modelling choice: values near 1 are conventional for trade gravity, higher values concentrate weight on near neighbours.

Own mass is excluded by default, because the internal distance of a territory to itself is undefined at this resolution. Supply self to include it under an explicit internal-distance assumption.

Distances are great-circle, computed by island_distance. See the "Profiling the world's small island developing states" vignette for what that does and does not represent for archipelagos.

Value

A named numeric vector of market access, one element per element of x, named by iso_code. Origins that cannot be resolved, or that carry no coordinate, return NA. Destinations with missing mass or missing coordinates are dropped from the sum rather than propagating.

See Also

island_distance, island_coords

Examples

# Illustrative population masses (thousands) for the Dutch Caribbean six.
# Supply your own sourced figures in real work.
pop <- c(AW = 108, CW = 156, SX = 43, "BQ-BO" = 25, "BQ-SE" = 3, "BQ-SA" = 2)
round(island_market_access(names(pop), pop), 3)

# Stronger decay concentrates weight on the nearest neighbours, separating
# the ABC and SSS groups sharply.
round(island_market_access(names(pop), pop, theta = 2), 6)

# Access to the wider region rather than to each other. Illustrative
# population in thousands.
region <- c(US = 335000, CO = 52000, VE = 28000, DO = 11000)
round(island_market_access(c("AW", "CW", "SX"), region, to = names(region)), 2)

Reference list of countries and territories with small-island classifications

Description

A curated dataset of 251 countries and territories, including sub-sovereign island jurisdictions (Aruba, Curacao, Bonaire, Sint Maarten, the French overseas collectivities, Aaland Islands, and others) that are typically collapsed or omitted by ISO 3166-1 country-code lists.

Usage

islands

Format

A data frame with 251 rows and 18 columns:

name

Short common name (e.g. "Aruba", "Curacao", "Bonaire").

label

Display label, used by the upstream XLSForm survey.

iso_code

ISO 3166-1 alpha-2 code, with hyphenated extensions for the three BES islands (BQ-BO Bonaire, BQ-SE Sint Eustatius, BQ-SA Saba) so they can be distinguished within the shared BQ prefix.

wb_region

World Bank region.

wb_income_group

World Bank income group.

political_association

Sovereign power for non-independent territories; "Independent" otherwise.

is_sids

1 if a UN-DESA recognised Small Island Developing State (member or associate); 0 otherwise.

sids_tier

"Sovereign member", "Associate member", or NA where not applicable.

is_snij

1 if a sub-national island jurisdiction; 0 otherwise.

criterion_small

1 if meets the small-population/small-area criterion; 0 otherwise.

criterion_island

1 if an island or archipelago; 0 otherwise.

criterion_developing

1 if classified as developing; 0 otherwise.

criterion_sovereign

1 if a sovereign state; 0 otherwise.

latitude

Representative point on the main landmass, WGS84 decimal degrees. NA for United States Minor Outlying Islands.

longitude

Representative point on the main landmass, WGS84 decimal degrees.

capital

Capital city name, or NA for uninhabited / capital-less territories.

capital_latitude

Capital city, WGS84 decimal degrees.

capital_longitude

Capital city, WGS84 decimal degrees.

Source

University of Aruba, Digital Competence Dutch Caribbean (DCDC) Network. island-research-reference-data, CC BY 4.0. https://github.com/University-of-Aruba/island-research-reference-data

Examples

head(islands)

# SIDS by World Bank region
table(islands$wb_region[islands$is_sids == 1])

# Dutch Kingdom territories (an example of the SNIJ axis)
islands[islands$political_association == "Dutch Kingdom",
        c("name", "iso_code", "is_sids", "is_snij")]

# Coordinates: representative landmass point and capital city
islands[islands$iso_code == "AW",
        c("name", "latitude", "longitude", "capital",
          "capital_latitude", "capital_longitude")]

Return a filtered subset of small-island states and territories

Description

Convenience wrapper around islands that returns the subset matching commonly used small-island filters.

Usage

small_islands(sids_only = FALSE, snij_only = FALSE, criteria = NULL)

Arguments

sids_only

Logical. If TRUE, return only UN-DESA SIDS.
snij_only

Logical. If TRUE, return only sub-national island jurisdictions.
criteria

Optional named logical vector with elements drawn from c("small", "island", "developing", "sovereign"). Each element constrains the corresponding criterion_* column.

Value

A data frame, the relevant subset of islands.

Examples

nrow(small_islands(sids_only = TRUE))
nrow(small_islands(snij_only = TRUE))
small_islands(criteria = c(small = TRUE, island = TRUE))