Package {islandcodes}

Title: Reference Data and Helpers for Small Island States and Territories
Version: 0.2.0
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.
License: CC BY 4.0
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.2.3
Depends: R (≥ 4.1.0)
Imports: countrycode (≥ 1.5.0)
Suggests: dplyr, tibble, knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
URL: https://github.com/University-of-Aruba/islandcodes, https://university-of-aruba.github.io/islandcodes/
BugReports: https://github.com/University-of-Aruba/islandcodes/issues
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-07-06 13:36:42 UTC; Rendell CE
Author: Rendell de Kort ORCID iD [aut, cre], University of Aruba [cph, fnd] (Digital Competence Dutch Caribbean (DCDC) Network)
Maintainer: Rendell de Kort <rendell.dekort@ua.aw>
Repository: CRAN
Date/Publication: 2026-07-06 14:20:13 UTC

Reference data and helpers for small island states and territories

Description

Provides 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.

Details

The package is deliberately small. It exposes:

It imports countrycode so country names entered by the user are coerced to ISO codes before lookup. The intent is to extend rather than replace countrycode: pass country names in, get small-island classifications out.

Source data

The bundled dataset is mirrored from https://github.com/University-of-Aruba/island-research-reference-data under CC BY 4.0. Run citation("islandcodes") for the canonical references.

Acknowledgments

With thanks 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 so children in his home country would have something concrete to point to on the telescope. The aruba function in this package is a small homage in the same style: A.R.U.B.A. as Annotated Reference for Under-coded Border Areas.

Author(s)

Maintainer: Rendell de Kort rendell.dekort@ua.aw (ORCID)

Other contributors:

See Also

Useful links:

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

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