Package {islandcodes}

Title: Reference Data and Helpers for Small Island States and Territories
Version: 0.1.1
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-05-11 09:31:26 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-05-15 20:30:14 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"))

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

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

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