region.tree: Phylogenetic tree(s) for a taxon within a geographic area

In aptg: Automatic Phylogenetic Tree Generator

Phylogenetic tree(s) for a taxon within a geographic area

Description

Retrieves the species of a given clade recorded in an area from the Global Biodiversity Information Facility (GBIF, via rgbif), then builds the tree(s) with taxa.tree (inheriting the per-phylum split and the source option). The area is specified in one of two ways:

Usage

region.tree(
  taxon,
  lat = NULL,
  lon = NULL,
  radius_km = NULL,
  province = NULL,
  gadm = NULL,
  source = c("otl", "fish"),
  max_species = 2000L,
  plot = TRUE,
  verbose = TRUE
)

Arguments

taxon	Required. A single clade name to constrain the search (e.g. "Aves", "Mammalia", "Salmonidae"). Without it, a populated area returns an unusable number of species.
lat, lon, radius_km	Radius mode: latitude, longitude (decimal degrees) and radius in kilometres. Supply all three.
province	Admin mode: a Canadian province/territory name or postal code (e.g. "Quebec", "QC", "Nunavut", "BC").
gadm	Admin mode: a GADM GID (e.g. "CAN.11_1" for Quebec, or any GID worldwide). Takes precedence over province.
source	Passed to taxa.tree: "otl" (default) or "fish".
max_species	Cap on the number of distinct species retrieved from GBIF (facet limit). Default 2000.
plot, verbose	Passed to taxa.tree.

Details

• Radius mode: a circle of radius_km around (lat, lon).

• Admin mode: an administrative area given by gadm (a GADM GID, works worldwide) or province (a Canadian province or territory name/abbreviation; all 13 are supported).

Value

Invisibly, the taxa.tree result (list(trees, unmatched)) with an added species element: the distinct species names GBIF returned for the area.

Requirements

Needs the suggested rgbif package (both modes) and geosphere (radius mode only). Both hit the network.

Caveats

GBIF returns occurrence records, not a curated checklist. The result is presence-only and sampling-biased (some groups and places are far better recorded than others), so it reflects what has been observed and digitised, not a definitive species inventory. Only records with coordinates and without flagged geospatial issues are counted, but coordinate precision still varies. Treat the species list as a starting point, not ground truth.

Canadian areas

The province lookup covers Alberta, British Columbia, Manitoba, New Brunswick, Newfoundland and Labrador, Northwest Territories, Nova Scotia, Nunavut, Ontario, Prince Edward Island, Quebec, Saskatchewan and Yukon (and their postal codes). The GIDs follow GADM's alphabetical level-1 ordering; the resolved GID is printed when verbose = TRUE. If GBIF's GADM version ever disagrees, pass the GID directly via gadm (browse them at https://api.gbif.org/v1/geocode/gadm/browse/CAN).

See Also

taxa.tree, downto.tree

Examples

## Not run: 
# Birds within 50 km of Montreal:
region.tree("Aves", lat = 45.50, lon = -73.57, radius_km = 50)

# Mammals of Nunavut (admin mode, Canadian territory):
region.tree("Mammalia", province = "Nunavut")

# Freshwater fishes of Quebec, as a dated tree:
region.tree("Actinopterygii", province = "QC", source = "fish")

# Anywhere in the world via a raw GADM GID:
region.tree("Reptilia", gadm = "USA.5_1")

## End(Not run)

aptg documentation built on July 19, 2026, 9:07 a.m.