Package 'mappingAS'

Description

Turns the occurrence-based AOO (the lower bound) and the Area of Habitat (AOH; the suitable/natural habitat within the range, an upper bound) into a bracketed AOO and the corresponding range of Criterion B2 size categories, following the IUCN guidance that the true AOO lies between an occurrence-based minimum and a habitat-based maximum (Brooks et al. 2019; IUCN Standards and Petitions Committee 2024), as implemented in sRedList (Cazalis et al. 2024).

Usage

aoo_bounds(aoo_lower_km2, aoh_km2 = NA_real_, eoo_km2 = NA_real_)

Arguments

Details

The upper bound is the AOH clamped so it is never below the lower bound and never above the EOO (occupancy cannot exceed the extent of occurrence). When the AOH is not available (aoh_km2 = NA, e.g. land cover was not computed) the upper bound falls back to the lower bound and the range collapses to a single category.

Value

A list with aoo_lower, aoo_upper, aoh (the clamped habitat area used), cat_lower / cat_upper (the B2 size category at each bound, e.g. "EN (B2 size)") and cat_range (a compact string such as "EN-VU", or a single category when both bounds agree).

References

Brooks T.M. et al. (2019) Measuring terrestrial Area of Habitat (AOH) and its utility for the IUCN Red List. Trends in Ecology & Evolution 34:977-986. doi:10.1016/j.tree.2019.06.009

Cazalis V. et al. (2024) Accelerating and standardising IUCN Red List assessments with sRedList. Biological Conservation 298:110761. doi:10.1016/j.biocon.2024.110761

See Also

calc_aoo, iucn_category_B, iucn_category_B_range

Examples

# Occurrence AOO of 48 km^2, but 900 km^2 of natural habitat within a
# 6000 km^2 EOO: AOO is bracketed EN (lower) to VU (upper).
aoo_bounds(aoo_lower_km2 = 48, aoh_km2 = 900, eoo_km2 = 6000)

Description

Clusters occurrences into subpopulations - groups of occurrences no further apart than an isolation distance - and quantifies how much of the population lies in small subpopulations, to guide the "severely fragmented" judgement of IUCN Criterion B sub-criterion (a). This mirrors the fragmentation step of sRedList (Cazalis et al. 2024, after Santini et al. 2019) but from occurrence data alone, so no habitat model or density estimate is required.

Usage

assess_fragmentation(
  points,
  isolation_km,
  weights = NULL,
  small_size = NULL,
  n_thresholds = 50
)

Arguments

Details

Two occurrences are placed in the same subpopulation when they are within isolation_km of each other (a circular-buffer clustering with radius isolation_km / 2, unioned on a data-centred equal-area projection, as in calc_subpop). The relative size of each subpopulation is the sum of its occurrence weights (the number of occurrences by default; supply, for example, per-occurrence occupied area for an area-weighted size). The fragmentation curve then gives, for a range of candidate "small subpopulation" sizes, the proportion of the total population contained in subpopulations no larger than that size; the median_subpop_size is the size at which that proportion reaches one half (half the population lives in subpopulations smaller than this). If the assessor considers a subpopulation of median_subpop_size to be "small", the population can be considered severely fragmented.

This is a screening proxy: occurrence counts are sampling-biased and are not individuals. Use the result only when the mapped clusters make ecological sense as subpopulations, exactly as sRedList advises.

Value

A list with n_subpop, isolation_km, sizes (a data.frame of cluster, size, n_points, ordered largest first), clusters (the subpopulation hulls/buffers as an sfc in WGS84), curve (a data.frame of size and prop_pop_le), median_subpop_size, largest_subpop_pct (percent of the population in the single largest subpopulation), prop_in_small / severe_suggested (when small_size is given, else NA) and crs_laea.

References

Santini L. et al. (2019) Applying habitat and population-density models to land-cover time series to inform IUCN Red List assessments. Conservation Biology 33:1084-1093. doi:10.1111/cobi.13279

Cazalis V. et al. (2024) Accelerating and standardising IUCN Red List assessments with sRedList. Biological Conservation 298:110761. doi:10.1016/j.biocon.2024.110761

See Also

calc_subpop, iucn_criterion_B

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
fr <- assess_fragmentation(sp1, isolation_km = 20)
fr$n_subpop
fr$median_subpop_size

Description

End-to-end pipeline. For each species it computes the EOO (minimum convex polygon) and AOO (2 km grid), then quantifies the percentage of converted (anthropic) and remaining natural habitat from the most recent MapBiomas collection inside both the EOO and the AOO. When fire = TRUE it also adds the percentage of the EOO/AOO that has burned and the mean fire recurrence, from the MapBiomas Fire accumulated layer.

Usage

assess_species(
  occ,
  initiative = "brazil",
  year = NULL,
  collection = NULL,
  backend = c("local", "gee"),
  fallback = c("sentinel2", "none"),
  cell_km = 2,
  subpop = TRUE,
  subpop_resol_km = NULL,
  loc_km = 10,
  loc_scale = NULL,
  loc_method = c("no_more_than_one", "other"),
  mapbiomas = TRUE,
  fire = FALSE,
  fire_collection = 4,
  fire_host_collection = 9,
  protected = FALSE,
  pa_src = NULL,
  src = NULL,
  fire_src = NULL,
  water_in_denominator = FALSE,
  area_max_pixels = 5e+07,
  decline = NA,
  extreme_fluctuation = NA,
  severe_fragmentation = NA,
  assume_decline = TRUE,
  infer_decline_from_habitat = TRUE,
  decline_years = 10,
  min_records = 1,
  verbose = TRUE
)

Arguments

Value

An object of class geoconv_assessment: a list with summary (one row per species, including n_subpop and n_locations) and detail (per-species points, eoo, aoo, subpop, locations, eoo_conversion, aoo_conversion, and - when fire = TRUE

• eoo_fire, aoo_fire).

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
# EOO/AOO, subpopulations and locations only (offline, no network):
res <- assess_species(occ, mapbiomas = FALSE, verbose = FALSE)
res$summary

# Full screening with MapBiomas land cover and fire (reads data over the web):
# (one species: the habitat-trend test reads six more years of land cover)
sp1 <- occ[occ$species == occ$species[1], ]
res2 <- assess_species(sp1, year = 2024, fire = TRUE, verbose = FALSE)
res2$summary

Description

Builds a written, interpretive summary of a species' preliminary Criterion B screening from an assess_species result. Beyond restating the headline numbers, the text interprets them: the EOO/AOO composition divergence, the effectiveness (not just the extent) of protected-area overlap, and an honest framing of continuing decline (subcriterion b). When the land-cover and/or fire time series are supplied it also analyses their temporal trend. Habitat conversion, fire and protected-area passages appear only when those modules were run. It can be returned as HTML (on-screen preview), plain text, or a Word .docx file (via officer) - the format used by the Shiny app's Report tab.

Usage

assessment_report(
  assessment,
  species = NULL,
  lang = c("en", "pt"),
  output = c("html", "text", "docx"),
  file = NULL,
  cover_series = NULL,
  fire_series = NULL,
  applied_category = NULL,
  applied_code = NULL,
  population = NULL,
  figures = FALSE
)

Arguments

Value

For "html"/"text", a length-one character string. For "docx", the file path (written as a side effect), invisibly.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
res <- assess_species(occ, mapbiomas = FALSE, verbose = FALSE)
cat(assessment_report(res, output = "text"))

# Word (.docx) report written to a temporary file:
f <- file.path(tempdir(), "report.docx")
assessment_report(res, output = "docx", file = f)
unlink(f)

Description

Computes the terrestrial Area of Habitat as the suitable land cover within a range polygon, optionally restricted to an elevation band, following the Area-of-Habitat concept (Brooks et al. 2019) and the sRedList workflow (Cazalis et al. 2024). "Suitable" defaults to the natural conservation group of the land-cover legend, so the result is consistent with the natural-versus-converted metrics used elsewhere in mappingAS; supply suitable_groups to change it.

Usage

calc_aoh(
  range,
  year = NULL,
  collection = NULL,
  initiative = "brazil",
  backend = "local",
  src = NULL,
  elev_src = NULL,
  elev_min = NA,
  elev_max = NA,
  z = 9,
  suitable_groups = "natural",
  suitable_codes = NULL,
  marginal_codes = NULL,
  points = NULL,
  max_pixels = 5e+07
)

Arguments

Details

The land cover is read over the range with the same backend as assess_species (MapBiomas or Sentinel-2/Esri) and, when an elevation band is given, an elevation model read over the same extent (windowed; via elev_src or the optional elevatr package) is resampled to the land-cover grid and used to mask out pixels outside [elev_min, elev_max]. The remaining suitable area is the AOH. The read is bounded by max_pixels: beyond it the land cover is decimated on read (nearest-neighbour sampling, which keeps class areas unbiased, unlike a majority rule that erases fragmented habitat) so a large range never streams its native pixels or exhausts memory. This AOH can be passed as the habitat-based upper AOO bound to aoo_bounds.

Every failure (no DEM, no land cover, an unsupported backend) degrades to NA with a message rather than an error.

Value

A list with aoh_km2 (suitable area within the elevation band, the AOH), aoh_max_km2 (the broader AOH including marginal classes; equal to aoh_km2 when none), aoo_upper_km2 / aoo_upper_cells (the AOH rescaled to the 2 km reference scale - the IUCN-compliant AOO upper bound - and its cell count), model_prevalence (share of the range that is suitable habitat) and point_prevalence (share of points inside the habitat; NA without points), suitable_km2 (suitable area without the elevation mask, for reference), elev_min, elev_max, elev_applied, suitable_groups, suitable_codes and marginal_codes.

References

Brooks T.M. et al. (2019) Measuring terrestrial Area of Habitat (AOH) and its utility for the IUCN Red List. Trends in Ecology & Evolution 34:977-986. doi:10.1016/j.tree.2019.06.009

Cazalis V. et al. (2024) Accelerating and standardising IUCN Red List assessments with sRedList. Biological Conservation 298:110761. doi:10.1016/j.biocon.2024.110761

See Also

aoo_bounds, elevation_preferences, summarise_conversion

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
hull <- calc_eoo(sp1)$hull
# Reads MapBiomas land cover (and a DEM if elevatr is installed):
calc_aoh(hull, year = 2024, elev_min = 0, elev_max = 1500)

Description

Computes the AOO as the number of occupied grid cells multiplied by the cell area, following the IUCN Red List guidelines (reference scale: 2 x 2 km cells = 4 km^2 each) and the approach used by the ConR package. Points are snapped to a regular grid defined on a data-centred equal-area projection.

Usage

calc_aoo(points, cell_km = 2, n_rep = 100)

Arguments

Details

Because the occupied-cell count depends on where the grid is placed, this function tests several translated grids and returns the smallest count, as ConR does. The translations follow a deterministic, evenly spread lattice, so the result is reproducible (no random seed needed). The returned cells correspond to the grid placement that produced the reported value.

Value

A list with area_km2, n_cells, cell_km, cells (occupied cells as an sfc polygon set in WGS84) and crs_laea.

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
calc_aoo(sp1)$area_km2

Description

Computes the EOO as the area of the convex hull (minimum convex polygon) enclosing all occurrence points, following the IUCN Red List guidelines and the approach used by the ConR package. The hull is built in longitude/latitude, its edges are densified with st_segmentize() so that they follow great circles, and the area is measured directly on the WGS84 ellipsoid (a "spheroid" measurement).

Usage

calc_eoo(points, segmentize_km = 20)

Arguments

Details

Degenerate cases are handled so the function never errors:

• With fewer than three unique points a polygon cannot be built and the EOO is NA.

• When the unique points are perfectly collinear (they would form a line of area zero) a small amount of noise is added to the coordinates (jitter), exactly as in ConR, so that a valid polygon can still be produced.

• If, for any other reason, a valid polygon still cannot be built, the EOO is returned as NA rather than throwing an error.

Value

A list with area_km2 (numeric), n_records (integer), n_unique (distinct coordinates), hull (the hull as an sfc in WGS84, or NULL when the EOO is undefined) and crs_laea (a data-centred equal-area proj string, kept for mapping).

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
calc_eoo(sp1)$area_km2

Description

Estimates the number of "locations" (in the IUCN sense: geographically or ecologically distinct areas in which a single threatening event can rapidly affect all individuals) by overlaying a regular grid and counting the occupied cells, optionally decoupling occurrences that fall inside protected areas from those outside. This mirrors the two complementary approaches used by the ConR package (Dauby et al. 2017): the grid method, and the protected-area integration (method_protected).

Usage

calc_locations(
  points,
  grid_km = 10,
  n_rep = 100,
  protected = NULL,
  method_protected = c("no_more_than_one", "other"),
  cell_scale = NULL
)

Arguments

Details

As for the AOO, the occupied-cell count depends on where the grid is placed, so several translated grids (a deterministic lattice) are tested and the smallest count is returned (the most conservative, i.e. most threatened, estimate). The grid is built on a data-centred Lambert Azimuthal Equal-Area projection and this function reuses mappingAS's own AOO grid machinery, so it differs from calc_aoo only in the (larger) default cell size.

Cell size. By default a fixed cell of grid_km (10 km) is used, representing the scale at which a single threat could affect the whole occupied cell. Alternatively a species-specific "sliding scale" (Rivers et al. 2010) is available: set cell_scale to a fraction (e.g. 0.05) and the cell side becomes that fraction of the maximum distance between two occurrences (cell_scale then overrides grid_km).

Protected areas. When protected is a protected-area layer (e.g. from protected_areas), occurrences are split into those inside and outside protected areas, because a subpopulation inside a protected area is not subject to the same threats as one outside:

• method_protected = "no_more_than_one" (default): every protected area holding at least one occurrence counts as exactly one location (all occurrences within a protected area share a location); occurrences outside protected areas are gridded as usual. Overlapping or nested designations (common in WDPA, e.g. a national park inside an environmental protection area) are counted once: the smallest set of protected areas that holds every inside occurrence is used. The total is (occupied cells outside) + (size of that set).

• method_protected = "other": occurrences inside protected areas are gridded separately from those outside, and the two counts are added. Two occurrences closer than the cell size are then still counted as separate locations when one is inside and the other outside a protected area.

With protected = NULL (the default) no protected-area information is used and the plain grid count is returned.

Value

A list with n_locations (integer estimate), grid_km (the cell size actually used), method ("grid", "no_more_than_one" or "other"), n_out / n_in (locations outside / inside protected areas; n_in is NA for the plain grid), n_cells, cells (gridded location cells as an sfc in WGS84), pa_locations (the protected areas counted as locations under "no_more_than_one", else NULL) and crs_laea.

References

Dauby G. et al. (2017) ConR: An R package to assist large-scale multispecies preliminary conservation assessments using distribution data. Ecology and Evolution 7:11292-11303. doi:10.1002/ece3.3704

Rivers M.C. et al. (2010) How many herbarium specimens are needed to detect threatened species? Biological Conservation 143:2545-2560.

IUCN Standards and Petitions Committee. Guidelines for Using the IUCN Red List Categories and Criteria.

See Also

calc_subpop, calc_aoo, protected_areas

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
calc_locations(sp1)$n_locations

Description

Estimates the number of subpopulations by the "circular buffer" method: a circle of radius resol_km is drawn around every occurrence, the circles are dissolved (unioned), and the number of resulting disjoint polygons is the estimated number of subpopulations. Occurrences whose buffers overlap are treated as belonging to the same subpopulation.

Usage

calc_subpop(points, resol_km = NULL)

Arguments

Details

This is the approach popularised by the ConR package (Dauby et al. 2017) and originally proposed by Rivers et al. (2010). The buffering is done on a data-centred Lambert Azimuthal Equal-Area projection (see laea_crs), consistent with the EOO/AOO computations elsewhere in mappingAS.

The buffer radius follows the widely used default of one tenth of the greatest distance separating two occurrences (Rivers et al. 2010): when resol_km is NULL it is computed from the data. Because the most distant pair of points always lies on the convex hull, the maximum distance is measured over the hull vertices only (great-circle distance on the WGS84 ellipsoid), which keeps the computation fast for large datasets.

Value

A list with n_subpop (integer estimate), resol_km (the radius actually used), n_unique (distinct coordinates), subpop (the dissolved subpopulation polygons as an sfc in WGS84, or NULL) and crs_laea (the equal-area proj string).

References

Dauby G. et al. (2017) ConR: An R package to assist large-scale multispecies preliminary conservation assessments using distribution data. Ecology and Evolution 7:11292-11303. doi:10.1002/ece3.3704

Rivers M.C. et al. (2010) How many herbarium specimens are needed to detect threatened species? Biological Conservation 143:2545-2560.

See Also

calc_locations, calc_aoo

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
calc_subpop(sp1)$n_subpop

Description

Returns, for each species, the area and percentage of every MapBiomas class found inside the EOO and/or the AOO. This complements the headline natural-versus-converted summary in assess_species with the full class-by-class breakdown.

Usage

class_table(assessment, species = NULL, range = c("both", "eoo", "aoo"))

Arguments

Value

A long data.frame with columns species, range ("EOO"/"AOO"), code, class_pt, class_en, group, area_km2 and pct (percentage of the mapped area within that range). Empty (with a warning) if MapBiomas was not computed.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
# reads MapBiomas (one year; the multi-year habitat trend is skipped)
res <- assess_species(occ, year = 2024, infer_decline_from_habitat = FALSE,
                      verbose = FALSE)
class_table(res)

Description

Derives the list of countries a taxon occurs in - and an approximate biogeographical realm - by intersecting its range with the public Natural Earth country base map, mirroring the "countries of occurrence" and "realms" supporting information that the IUCN Red List requires/recommends and that sRedList extracts automatically (Cazalis et al. 2024).

Usage

countries_of_occurrence(
  range,
  points = NULL,
  scale = c("medium", "small", "large")
)

Arguments

Details

Following the Red List convention, every country the range polygon overlaps is reported, and each is flagged by presence:

• Extant - the country holds at least one occurrence record;

• Possibly Extant - the country overlaps the range but holds no record in the supplied points.

When no polygon is supplied (fewer than three points, so no EOO hull) the countries are taken from the points alone and are all reported as Extant.

Realm. The biogeographical realm is a coarse approximation derived from the continent of each country (Neotropical, Nearctic, Afrotropical, Palearctic, Indomalayan, Australasian, Oceanian or Antarctic); it is exact for the South-American ranges mappingAS is built around but should be checked for taxa spanning continental transitions (e.g. North/Central America, North Africa, South-East Asia), where realm boundaries do not follow country borders.

Value

A data.frame with one row per country: country, presence ("Extant"/"Possibly Extant"), n_records (occurrences in that country), continent and realm. Rows are ordered by presence then country. An empty data.frame (with a message) is returned when rnaturalearth is not installed or no country overlaps.

References

Cazalis V. et al. (2024) Accelerating and standardising IUCN Red List assessments with sRedList. Biological Conservation 298:110761. doi:10.1016/j.biocon.2024.110761

See Also

calc_eoo, assess_species

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
# Needs the 'rnaturalearth' package (Suggests):
countries_of_occurrence(calc_eoo(sp1)$hull, points = sp1)

Description

For a given area (e.g. an EOO hull or the union of AOO cells), computes the area of each MapBiomas class (or conservation group) for several years, returning a tidy long table suitable for a stacked-area chart of percentage of area versus year (as in the MapBiomas coverage figures).

Usage

cover_timeseries(
  geom,
  years = NULL,
  collection = NULL,
  initiative = "brazil",
  backend = c("local", "gee"),
  src = NULL,
  by = c("class", "group"),
  include_not_observed = FALSE,
  verbose = TRUE,
  max_pixels = 5e+07
)

Arguments

Details

Each year is read independently (local windowed read or Earth Engine), so a long span of annual data can take a while. By default a 5-year step is used; pass years = mb_years() for the full annual series.

Value

A data.frame (long) with columns year, label, hex, group, area_km2 and pct (percentage of the mapped area in that year). For by = "class" it also has code and class_en.

See Also

plot_timeseries, timeseries_for_species

Description

Extracts the elevation of each occurrence from a digital elevation model and suggests the species' elevation limits, mirroring the sRedList step that pre-fills elevation preferences from occurrence records (Cazalis et al. 2024). The suggested minimum is rounded down and the maximum rounded up to the nearest round_to metres, as sRedList does.

Usage

elevation_preferences(points, z = 9, src = NULL, round_to = 100)

Arguments

Details

The DEM is read only over the occurrences' extent (windowed), from src or the public AWS Terrain Tiles via the optional elevatr package. When no DEM is available the function returns NA values with a message rather than raising an error.

Value

A list with n (occurrences with a value), min, max, median (metres), suggested_min / suggested_max (rounded limits) and values (the per-occurrence elevations). All-NA when no DEM is available.

References

Cazalis V. et al. (2024) Accelerating and standardising IUCN Red List assessments with sRedList. Biological Conservation 298:110761. doi:10.1016/j.biocon.2024.110761

See Also

calc_aoh

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
# Needs the 'elevatr' package (Suggests) and internet:
elevation_preferences(sp1)

Description

Returns the 9-class legend of the Esri / Impact Observatory / Microsoft "10 m Annual Land Use Land Cover" product (derived from ESA Sentinel-2, the data behind the ArcGIS Living Atlas Land Cover Explorer), with each pixel class mapped to the same conservation groups used by mappingAS for MapBiomas ("natural", "anthropic", "water", "other", "not_observed"). This lets a range assessed with the global fallback flow through the exact same conversion, plotting and report pipeline as a MapBiomas one (see summarise_conversion).

Usage

esri_legend()

Details

Group mapping: Trees, Rangeland and Flooded Vegetation are natural; Crops and Built Area are anthropic (converted habitat); Water is water; Bare Ground and Snow/Ice are other (ambiguous, excluded from the conversion denominator by default); Clouds are not_observed.

Value

A data.frame with columns code, class_en, class_pt, hex (official Esri colour), level1 and group.

See Also

mb_legend, summarise_conversion

Examples

esri_legend()
subset(esri_legend(), group == "anthropic")$class_en

Description

Writes the Extent of Occurrence (EOO) polygons and the Area of Occupancy (AOO) polygons produced by assess_species() to disk, with the area, habitat-conversion and provisional-category attributes attached to each feature (one feature per species by default). Handy for opening the results in QGIS/ArcGIS or sharing them.

Usage

export_ranges(
  assessment,
  dir = tempdir(),
  layer_prefix = "mappingAS",
  what = c("both", "eoo", "aoo"),
  format = c("shapefile", "gpkg"),
  crs = 4326,
  aoo_as = c("cells", "union"),
  class_csv = TRUE,
  zip = FALSE,
  quiet = TRUE
)

Arguments

Details

Because the ESRI Shapefile format limits field names to 10 characters, the attribute fields use compact names (see the Attribute fields section). A GeoPackage (format = "gpkg") stores both ranges as two layers (eoo, aoo) inside a single file and has no such limitation.

Value

(Invisibly) a character vector with the file paths written, or the path to the .zip when zip = TRUE.

Attribute fields

species; eoo_km2 or aoo_km2 (and n_cells for AOO); conv_pct (percent converted/anthropic within that range); nat_pct (percent natural); cat_B1 or cat_B2 (provisional size-only category); prov_cat; mb_year; mb_coll (MapBiomas year and collection). Conversion fields are NA when MapBiomas was not computed.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
res <- assess_species(occ, mapbiomas = FALSE, verbose = FALSE)

d <- file.path(tempdir(), "mappingAS_ranges")
dir.create(d, showWarnings = FALSE)

# Two shapefiles (EOO + AOO) written to a temporary directory:
export_ranges(res, dir = d)

# A single GeoPackage with both layers:
export_ranges(res, dir = d, format = "gpkg")


# Everything bundled into one .zip (good for downloads):
export_ranges(res, dir = d, zip = TRUE)

Description

Builds a single, self-contained HTML file that presents one species as a printable/shareable factsheet - the kind hosted on a supplementary website. It combines two sources of information:

1. Everything the assessment already computes - range metrics (EOO/AOO and provisional Criterion B category), habitat conversion, fire and protected-area overlap - rendered as a key-metrics grid, the standard charts (composition, protection, and any land-cover / fire time series supplied), a "top anthropic activities" chart derived from the per-class land-cover breakdown, and the interpretive narrative of assessment_report.

2. Information the package cannot know, supplied by the user: the taxonomy (Family, Genus, Authority), the supporting-information block (Countries, Life Form, Substrate, Habitat, Biome, Vegetation), free-text land use and conservation units, a list of examined vouchers, a taxonomic reference (a Reflora / POWO link, or - for a newly described species - the article citation) and up to four photographs.

The whole page is self-contained (fonts fall back to the system stack, images and charts are embedded as base64 data URIs), so the returned file can be opened offline or published as-is (e.g. on GitHub Pages). Each photograph carries a watermark in its lower-right corner with the owner name given in photo_credit.

Usage

factsheet_html(
  assessment,
  species = NULL,
  lang = c("en", "pt"),
  file = NULL,
  family = NULL,
  genus = NULL,
  authority = NULL,
  countries = NULL,
  life_form = NULL,
  substrate = NULL,
  habitat = NULL,
  biome = NULL,
  vegetation = NULL,
  land_use = NULL,
  conservation_units = NULL,
  vouchers = NULL,
  reference = NULL,
  photos = NULL,
  photo_credit = NULL,
  cover_series = NULL,
  fire_series = NULL,
  applied_category = NULL,
  applied_code = NULL,
  map = TRUE,
  map_interactive = TRUE,
  top_n_threats = 5L
)

Arguments

Value

The HTML string, or (when file is given) the file path, invisibly.

See Also

assessment_report for the narrative-only report.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
# reads MapBiomas (one year; the multi-year habitat trend is skipped)
res <- assess_species(occ, year = 2024, infer_decline_from_habitat = FALSE,
                      verbose = FALSE)
out <- file.path(tempdir(), "factsheet.html")
factsheet_html(res, file = out, map = FALSE,
               family = "Gentianaceae", countries = "Brazil",
               life_form = "Herb", biome = "Atlantic Forest")
unlink(out)

Description

Fire analogue of mb_class_areas_raster. For the accumulated product, freq is the fire frequency (years burned).

Usage

fire_areas(r)

Arguments

Value

A data.frame with columns freq and area_km2.

Description

Sequential palette for fire frequency (YlOrRd)

Usage

fire_palette(n = 6)

Arguments

Value

A character vector of hex colours.

Description

Thin wrapper over mb_raster_local; reuses its windowed /vsicurl/ read and on-disk cache.

Usage

fire_raster_local(
  aoi,
  year = 2024,
  product = c("accumulated", "annual", "frequency"),
  fire_collection = 4,
  host_collection = 9,
  src = NULL,
  mask = TRUE,
  cache = TRUE,
  cache_dir = NULL
)

Arguments

Value

A terra SpatRaster of fire values clipped to the AOI.

Description

Fire analogue of cover_timeseries: reads the annual burned layer for each year and returns burned area (km^2) and percentage of the range. Each year is one windowed read, so a full annual series can be slow.

Usage

fire_timeseries(
  geom,
  years = NULL,
  fire_collection = 4,
  host_collection = 9,
  range_km2 = NULL,
  verbose = TRUE
)

Arguments

Value

A data.frame with year, burned_km2, burned_pct.

Description

Convenience wrapper around fire_timeseries that pulls the stored EOO hull or AOO geometry (and its area) from an assessment.

Usage

fire_timeseries_for_species(
  assessment,
  species = NULL,
  range = c("eoo", "aoo"),
  years = NULL,
  verbose = TRUE
)

Arguments

Value

The data frame from fire_timeseries with attributes species and range.

Description

Implements the habitat-and-density fragmentation method of the IUCN Red List guidelines (Santini et al. 2019), as used by sRedList (Cazalis et al. 2024): the suitable habitat (Area of Habitat) within the range is split into patches, patches within a dispersal / isolation distance of one another are grouped into isolated subpopulations, and each subpopulation's size in individuals is its habitat area times the population density. This is the guideline-compliant companion to assess_fragmentation (which uses occurrence counts as a rough proxy when no habitat model or density is available).

Usage

fragment_habitat(
  range,
  isolation_km,
  density,
  year = NULL,
  collection = NULL,
  initiative = "brazil",
  src = NULL,
  suitable_groups = "natural",
  suitable_codes = NULL,
  elev_min = NA,
  elev_max = NA,
  z = 9,
  elev_src = NULL,
  max_pixels = 4000,
  small_size = NULL
)

Arguments

Details

Following Santini et al. (2019): contiguous suitable cells form patches; each patch is buffered by half the isolation distance and buffers that touch are merged, so patches closer than the isolation distance share a subpopulation; the number of individuals in a subpopulation is its total suitable area (km^2) times density (individuals km^-2), and a subpopulation of fewer than two individuals is treated as unoccupied. The curve then gives the proportion of the population in subpopulations no larger than a given size, whose median_subpop_size is the size below which half the population lives; if the assessor considers a subpopulation of that size "small", the population can be treated as severely fragmented (Criterion B sub-criterion a). The largest subpopulation's size (max_subpop, Criterion C2a(i)) and its share of the population (pct_largest, Criterion C2a(ii)) are also returned.

Use with care: use the result only when the mapped clusters make ecological sense as subpopulations, exactly as sRedList advises. Barriers (water, mountains, infrastructure) are not accounted for.

Value

A list with method = "habitat", n_subpop (occupied subpopulations), isolation_km, density, sizes (a data.frame of cluster, aoh_km2, pop and, for a density range, pop_high), clusters (subpopulation polygons as an sfc in WGS84), curve, median_subpop_size, max_subpop (C2a(i)), pct_largest (C2a(ii)), total_pop, and prop_in_small / severe_suggested. Values degrade to NA when the land cover cannot be read.

References

Santini L. et al. (2019) Applying habitat and population-density models to land-cover time series to inform IUCN Red List assessments. Conservation Biology 33:1084-1093. doi:10.1111/cobi.13279

Cazalis V. et al. (2024) Accelerating and standardising IUCN Red List assessments with sRedList. Biological Conservation 298:110761. doi:10.1016/j.biocon.2024.110761

See Also

assess_fragmentation, calc_aoh

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
sp1 <- occ[occ$species == occ$species[1], ]
hull <- calc_eoo(sp1)$hull
# Reads land cover; density in mature individuals per km^2:
fr <- fragment_habitat(hull, isolation_km = 20, density = 5)
fr$n_subpop
fr$max_subpop      # C2a(i)

Description

Returns the category implied by the EOO (B1) and AOO (B2) size thresholds only. This is a screening aid, exactly like GeoCat: a full Criterion B listing additionally requires at least two of the sub-criteria (a) severe fragmentation / few locations, (b) continuing decline, and (c) extreme fluctuation. Never report these as final categories.

Usage

iucn_category_B(eoo_km2 = NA_real_, aoo_km2 = NA_real_)

Arguments

Details

Vectorised: eoo_km2 and aoo_km2 may be columns of an assessment summary. Following the IUCN Guidelines (sect. 4.10), when the EOO is smaller than the AOO the EOO is set equal to the AOO before applying the thresholds.

Value

A list with eoo_category, aoo_category and combined (the more threatened of the two size-based flags), each a character vector of the input length.

Description

Combines the fixed EOO (B1) size flag with the bracketed AOO (B2) size flags - from a lower (occurrence-based) and an upper (habitat-based) AOO bound - into the plausible range of Criterion B screening categories. This is the size-only companion to iucn_category_B that lets an assessment report the uncertainty explicitly, as the sRedList summary does, rather than a single point estimate. Like iucn_category_B it reflects size thresholds only (the sub-criteria still apply on top).

Usage

iucn_category_B_range(
  eoo_km2 = NA_real_,
  aoo_lower_km2 = NA_real_,
  aoo_upper_km2 = NA_real_
)

Arguments

Details

Because the EOO is a single value, the most-threatened plausible flag pairs B1 with B2 at the lower AOO, and the least-threatened plausible flag pairs B1 with B2 at the upper AOO; in each case the more threatened of the two axes wins (as in iucn_category_B).

Value

A list with b1_category (from EOO), b2_lower / b2_upper (B2 size flags at the two AOO bounds), worst and best (the most- and least-threatened plausible screening categories, as short codes "CR"/"EN"/"VU"/"NT-/LC-level") and range (a compact label such as "EN-VU", or a single code when they agree).

See Also

iucn_category_B, aoo_bounds

Examples

iucn_category_B_range(eoo_km2 = 6000, aoo_lower_km2 = 48, aoo_upper_km2 = 900)

Description

Combines the EOO (B1) and AOO (B2) size thresholds of Criterion B with the sub-criteria required for a threatened listing, following the IUCN Red List Categories and Criteria (v3.1) and the Guidelines for Using them (Section 6, Criterion B; Section 10, DD/NT/NE), and aligning the category selection with the ConR package (Dauby et al. 2017, cat_criterion_b()). Unlike iucn_category_B (size flags only), this returns a category that can actually be applied.

Usage

iucn_criterion_B(
  eoo_km2 = NA_real_,
  aoo_km2 = NA_real_,
  n_locations = NA_real_,
  severe_fragmentation = NA,
  decline = NA,
  extreme_fluctuation = NA,
  assume_decline = TRUE,
  decline_detail = NULL
)

Arguments

Details

A taxon qualifies for a threatened category (CR, EN, VU) only if it meets the size threshold and at least two of these three sub-criteria:

• (a) severely fragmented or number of locations $\le$ 1 (CR), 5 (EN) or 10 (VU);

• (b) continuing decline (in EOO, AOO, area/extent/quality of habitat, number of locations/subpopulations, or mature individuals);

• (c) extreme fluctuations.

Relation to the number of locations. Sub-criterion (a) is derived from n_locations (and severe_fragmentation when supplied), and it caps the category exactly as ConR does: the returned category is the less threatened of the level implied by range size and the level implied by the number of locations. A range whose EOO/AOO alone would be CR or EN but that is spread over, say, eight locations is therefore returned as VU ($\le 10$ locations), not EN - the number of locations, not size alone, sets the category. Equivalently, per level: CR needs a single location, EN $\le 5$, VU $\le 10$ (unless severely fragmented, which meets condition (a) at any level).

Continuing decline (b), assumed by default. Sub-criteria (b) and (c) cannot be read from occurrence points. Following ConR - and because mappingAS is built around habitat-conversion data, which is direct evidence of a continuing decline in the area, extent and quality of habitat (sub-criterion b(iii)) - a continuing decline is assumed to be present when it is not explicitly documented (decline = NA with assume_decline = TRUE, the default). This is what makes the screening track the IUCN thresholds instead of collapsing every undocumented taxon to NT: with the location condition (a) met and decline (b) assumed, a small-range, few-location taxon is returned at its CR/EN/VU size-and-location level. Set assume_decline = FALSE (or decline = FALSE) to require a documented decline instead, in which case a size-and-location match with no second sub-criterion falls to NT. Extreme fluctuation (c) is never assumed.

Following Section 10: a taxon that meets a size threshold but not two sub-criteria (for example a small range spread over too many locations, or with decline explicitly absent) is returned as NT (Near Threatened, it "nearly meets" the requirements); one clearly far from every threshold as LC. DD and NE are never assigned automatically - they require the assessor's judgement about data adequacy and are left to the user.

Value

A list with category (one of "CR", "EN", "VU", "NT", "LC", or NA when neither EOO nor AOO is available), code (e.g. "VU B1ab"), qualifies_size (the highest size level met, or NA), the evaluated sub-criteria a, b, c, and decline_assumed (TRUE when sub-criterion (b) was assumed rather than documented).

References

Dauby G. et al. (2017) ConR: An R package to assist large-scale multispecies preliminary conservation assessments using distribution data. Ecology and Evolution 7:11292-11303. doi:10.1002/ece3.3704

See Also

iucn_category_B

Examples

# EN-sized range with few locations: decline assumed by default -> EN B1ab
iucn_criterion_B(eoo_km2 = 3000, aoo_km2 = 400, n_locations = 4)$code
# Same size but spread over 8 locations -> capped to VU by the location count
iucn_criterion_B(eoo_km2 = 3000, aoo_km2 = 400, n_locations = 8)$category
# Require a documented decline: with none, a size/location match falls to NT
iucn_criterion_B(eoo_km2 = 3000, aoo_km2 = 400, n_locations = 4,
                 assume_decline = FALSE)$category

Description

Builds a leaflet map of the terrestrial Area of Habitat: the suitable land-cover classes within the EOO, optionally restricted to an elevation band, drawn as a single green overlay together with the EOO hull and the occurrence points. It is the map companion to calc_aoh and uses the same suitable-class and elevation definitions, so the map shows exactly the area calc_aoh() measures.

Usage

map_aoh(
  assessment,
  species = NULL,
  suitable_groups = "natural",
  suitable_codes = NULL,
  elev_min = NA,
  elev_max = NA,
  z = 9,
  elev_src = NULL,
  src = NULL,
  max_pixels = 800,
  lang = c("pt", "en")
)

Arguments

Details

Suitable habitat is, by default, the natural conservation group of the land-cover legend; pass suitable_groups (one or more groups) or suitable_codes (specific land-cover class codes, e.g. the classes that make ecological sense for the species) to change it. When an elevation band is given, an elevation model read over the EOO (via elev_src or the optional elevatr package) masks out the habitat outside [elev_min, elev_max].

Value

A leaflet widget, or a base map with just the points/EOO when the land cover cannot be read.

See Also

calc_aoh, map_species

Description

Builds a leaflet map with the occurrence points, EOO hull and occupied AOO cells. Optionally overlays the MapBiomas land-cover raster and the MapBiomas Fire accumulated layer (fire recurrence: number of years burned), both clipped to the EOO, as toggleable layers with legends.

Usage

map_species(
  assessment,
  species = NULL,
  mapbiomas = TRUE,
  fire = FALSE,
  src = NULL,
  fire_src = NULL,
  max_pixels = 800,
  lang = c("pt", "en"),
  clip = c("eoo", "aoo", "all"),
  protected = FALSE,
  pa_src = NULL,
  pa_occ_only = TRUE
)

Arguments

Value

A leaflet widget.

Description

Builds an exportable ggplot2 map for one species: the MapBiomas land-cover layer clipped to the EOO (with the official colour legend of the classes actually present, drawn beside the map so it never overlaps the EOO/AOO), the EOO minimum convex polygon, the occupied AOO cells, the occurrence points, plus a north arrow and a scale bar with the geographic reference (datum/projection) printed beneath it. The map is drawn in the species' equal-area projection so the scale bar is meaningful, and is returned as a ggplot object you can save with ggplot2::ggsave() to make a usable, georeferenced-looking figure.

Usage

map_static(
  assessment,
  species = NULL,
  mapbiomas = TRUE,
  fire = FALSE,
  src = NULL,
  max_pixels = 600,
  crs = NULL,
  scalebar = TRUE,
  north = TRUE,
  title = NULL,
  lang = c("pt", "en"),
  clip = c("eoo", "aoo", "all"),
  protected = FALSE,
  pa_src = NULL,
  pa_occ_only = TRUE
)

Arguments

Details

The MapBiomas layer is read with the cached windowed reader and aggregated to max_pixels for display, so it is fast and reuses the raster already fetched during assess_species (same EOO window).

Value

A ggplot object.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
res <- assess_species(occ, mapbiomas = FALSE, verbose = FALSE)
m <- map_static(res, mapbiomas = FALSE)

# Save it wherever you like (a temporary file here):
f <- file.path(tempdir(), "eoo_map.png")
ggplot2::ggsave(f, m, width = 8, height = 7)
unlink(f)

Description

Converts a ggplot2 object produced by the mappingAS plot_* functions (plot_conversion, plot_protection, plot_timeseries, plot_fire_timeseries) into an interactive plotly widget. Those functions attach the tidy data and palette needed, so the widget is built as native plotly (correct per-segment hover tooltips and in-bar labels) rather than through ggplotly(). Any other ggplot falls back to ggplotly(). This is the single place that controls the interactive look across the package and the Shiny app.

Usage

mas_plotly(p, tooltip = c("fill", "x", "y"), ...)

Arguments

Value

A plotly htmlwidget (or p unchanged when it is not a ggplot or plotly is not installed).

Examples

if (interactive()) {
  occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                      package = "mappingAS"))
  res <- assess_species(occ, year = 2024, verbose = FALSE)  # reads MapBiomas
  mas_plotly(plot_conversion(res))
}

Description

Computes the area (km^2) of each MapBiomas pixel class inside aoi entirely on Google Earth Engine, without downloading any raster. This is the recommended backend for very large ranges (e.g. continental EOOs) where a local windowed read would transfer too much data.

Usage

mb_class_areas_gee(
  aoi,
  year = 2024,
  collection = 10,
  version = "v1",
  asset = "projects/mapbiomas-public/assets/brazil/lulc/v1",
  scale = 30,
  max_pixels = 1e+13
)

Arguments

Details

Requires the rgee package and an initialised Earth Engine session (rgee::ee_Initialize()); see the package README for one-time setup.

Value

A data.frame with columns code and area_km2.

Description

Computes the true (geodesic, latitude-corrected) area of each MapBiomas pixel class inside a cropped/masked raster. Works for rasters in geographic CRS, where pixel area varies with latitude, by using terra::cellSize().

Usage

mb_class_areas_raster(r)

Arguments

Value

A data.frame with columns code and area_km2.

Description

"frequency" is the fire-frequency layer (pixel = number of years burned over period, 1-40); "accumulated" is binary (burned at least once); "annual" is the per-year burned area.

Usage

mb_fire_url(
  year = 2024,
  product = c("accumulated", "annual", "frequency"),
  fire_collection = 4,
  host_collection = 9,
  period = c(1985, 2024)
)

Arguments

Value

A length-1 character URL.

Examples

mb_fire_url(product = "accumulated")
mb_fire_url(2024, "annual")

Description

Convenience wrapper returning the pixel codes that belong to each group.

Usage

mb_groups(collection = 10, initiative = "brazil")

Arguments

Value

A named list with elements natural, anthropic, water, other and not_observed, each an integer vector of MapBiomas pixel codes.

Description

mappingAS can read land-use/land-cover from several public MapBiomas initiatives, all streamed as annual Cloud-Optimized GeoTIFFs from the public storage.googleapis.com/mapbiomas-public bucket via GDAL's /vsicurl/ driver - no Google Earth Engine account and no Google Drive download required. Each initiative is one coherent product with its own default collection, year span and file layout, but all share the same standardised legend (see mb_legend), so a species whose range spans more than one product can be assessed with consistent class names, colours and conservation groups.

Usage

mb_initiatives()

Details

"brazil"

MapBiomas Brazil, Collection 10 (1985-2024).

"amazonia"

MapBiomas Amazonia / Pan-Amazon (RAISG), Collection 6 (1986-2023). The whole Amazon basin across countries.

"colombia"

MapBiomas Colombia, Collection 3 (1985-2024).

"argentina"

MapBiomas Argentina, Collection 2 (1985-2024).

"bolivia"

MapBiomas Bolivia, Collection 3 (1985-2024).

"chile"

MapBiomas Chile, Collection 1 (2000-2022).

"ecuador"

MapBiomas Ecuador, Collection 3 (1985-2024).

"peru"

MapBiomas Peru, Collection 3 (1985-2024).

"venezuela"

MapBiomas Venezuela, Collection 2 (1985-2023).

"paraguay"

MapBiomas Paraguay, Collection 2 (1985-2023).

"uruguay"

MapBiomas Uruguay, Collection 1 (1985-2022).

Value

A named list, one element per initiative, each a list with label (human-readable name), collection (default collection number), years (integer vector of available years) and key.

See Also

mb_source_url, mb_legend, assess_species

Examples

names(mb_initiatives())
mb_initiatives()$peru$years

Description

Returns the standardised MapBiomas land-use/land-cover legend used across every initiative supported by mappingAS (Brazil, Pan-Amazon / Amazonia, Colombia, Argentina, Bolivia, Chile, Ecuador, Peru, Venezuela, Paraguay and Uruguay - see mb_initiatives), with each pixel class assigned to a conservation-relevant group: "natural", "anthropic", "water", "not_observed" or "other". The "anthropic" classes are what counts as converted habitat; "natural" is the remaining (current) natural habitat. By default "water", "not_observed" and "other" are excluded from the conversion denominator (see summarise_conversion).

Usage

mb_legend(collection = 10, initiative = "brazil")

Arguments

Details

MapBiomas harmonises pixel codes across its initiatives, so a single legend can label every country's raster consistently - this is what makes cross-border assessment possible for a species whose range spans more than one product. The table is the union of the classes that occur in any of the products; a code that does not occur in a given raster simply contributes zero area. Besides the Brazil Collection 10 classes it includes the classes specific to the other countries - e.g. Andinean formations (81, 82), Glacier (34), primary/secondary/dwarf forest (59, 60, 67), scrubland/steppe/fog oasis/peatlands (66, 63, 70, 73), Pinus/Eucalyptus plantations (79, 80) and salt flat (61).

Value

A data.frame with columns code, class_en, class_pt, hex (standardised MapBiomas colour), level1 and group.

Examples

head(mb_legend())
subset(mb_legend(), group == "anthropic")$class_en

Description

Official MapBiomas colours for a set of class codes

Usage

mb_palette(
  codes = NULL,
  collection = 10,
  initiative = "brazil",
  by = c("code", "class_pt", "class_en")
)

Arguments

Value

A named character vector of hex colours.

Examples

mb_palette(c(3, 15, 39, 33))

Description

Reads the MapBiomas national mosaic and crops/masks it to aoi using terra. By default it streams a windowed read of only the AOI's bounding box from the public GeoTIFF via GDAL's /vsicurl/ driver, so there is no Google Earth Engine account and no full-country download. For offline or repeated use, point src to a local GeoTIFF instead.

Usage

mb_raster_local(
  aoi,
  year = 2024,
  collection = NULL,
  initiative = "brazil",
  src = NULL,
  mask = TRUE,
  cache = TRUE,
  cache_dir = NULL
)

Arguments

Details

For very large ranges (e.g. continental EOOs) the windowed read can still transfer a lot of data; in that case prefer mb_class_areas_gee.

Value

A terra SpatRaster of MapBiomas pixel codes restricted to the AOI, in the raster's native CRS.

Description

Returns the public Google Cloud Storage URL of the MapBiomas land-use/land-cover annual mosaic for the chosen initiative. All supported initiatives publish annual single-year Cloud-Optimized GeoTIFFs on the same public bucket, so they can be streamed with GDAL's /vsicurl/ driver (no Google Earth Engine, no Google Drive). See mb_initiatives for the full list of initiatives, their default collections and year spans.

Usage

mb_source_url(year = 2024, collection = NULL, initiative = "brazil")

Arguments

Value

A length-1 character URL.

Examples

mb_source_url(2024)
mb_source_url(2023, initiative = "amazonia")
mb_source_url(2024, initiative = "peru")

Description

Years available for a MapBiomas initiative/collection

Usage

mb_years(collection = 10, initiative = "brazil")

Arguments

Value

An integer vector of years available for the initiative (e.g. Brazil 1985-2024, Amazonia 1986-2023, Paraguay 1985-2023, Uruguay 1985-2022).

Examples

range(mb_years())
range(mb_years(initiative = "amazonia"))

Description

Long data.frame (one row per species x UC) listing each federal UC that contains occurrences of, or overlaps the EOO of, each assessed species. Requires assess_species(..., protected = TRUE).

Usage

pa_table(assessment, species = NULL)

Arguments

Value

A data.frame with species, pa_name, pa_category, pa_group, n_occ (occurrences of that species inside the UC) and overlap_eoo_km2.

Description

Fits a regression of a single land-cover class (or conservation group) percentage of area against year and plots the observed points with the fitted curve, its equation, R-squared and p-value. When the ggtrendline package is installed (https://CRAN.R-project.org/package=ggtrendline) it is used to draw the trendline and annotate the statistics; otherwise the function falls back to a plain ggplot2 linear fit carrying the same statistics, and finally to base graphics.

Usage

plot_class_trendline(
  ts,
  class_label = NULL,
  model = "line2P",
  title = NULL,
  lang = c("en", "pt")
)

Arguments

Value

A ggplot object when ggplot2 is available; otherwise NULL (invisibly) after drawing a base plot.

See Also

plot_timeseries, timeseries_for_species

Description

Draws, for one species, two horizontal stacked bars (EOO and AOO) showing the MapBiomas composition as a percentage of the mapped (observed) area: natural, altered (anthropic), water and other. Segment labels are placed inside each bar and the legend sits below the plot, so nothing overlaps. The headline terrestrial converted percentage is shown as a subtitle.

Usage

plot_conversion(assessment, species = NULL, lang = c("en", "pt"))

Arguments

Details

When ggplot2 is available (a hard dependency) the function returns a ggplot object, which mas_plotly can turn into an interactive chart; otherwise it draws a base-graphics fallback and returns the percentage matrix invisibly.

Value

A ggplot object (ggplot2 available) or, in the base-graphics fallback, invisibly the plotted percentage matrix.

See Also

mas_plotly for the interactive version.

Description

Two side-by-side donut (ring) charts summarising the MapBiomas composition of the Extent of Occurrence (EOO) and Area of Occupancy (AOO) of a species, in the official MapBiomas colours. Slices can be individual land-cover classes (by = "class") or the four conservation groups (by = "group"). Designed to be exported as a transparent-background PNG (all panel/plot/legend backgrounds are transparent), and the interactive plotly version (via mas_plotly) adds outside labels with leader lines and a transparent export.

Usage

plot_conversion_donut(
  assessment,
  species = NULL,
  by = c("class", "group"),
  lang = c("en", "pt")
)

Arguments

Value

A ggplot object (with mappingAS metadata attached in attribute "mas" so mas_plotly can build the interactive donut). Stops with an informative message if no class data are available.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
# reads MapBiomas (one year; the multi-year habitat trend is skipped)
res <- assess_species(occ, year = 2024, infer_decline_from_habitat = FALSE,
                      verbose = FALSE)
plot_conversion_donut(res, by = "class")

Description

Bar/line chart of burned area (%) over time

Usage

plot_fire_timeseries(ts, title = NULL, lang = c("en", "pt"))

Arguments

Value

A ggplot object when ggplot2 is available; otherwise NULL after a base plot.

Description

Two horizontal stacked bars (EOO and AOO) showing the share of the range inside federal Protected areas (Protected areas, UCs) versus outside, from assess_species(..., protected = TRUE). When MapBiomas was also computed (mapbiomas = TRUE), the inside-UC part is split into natural and altered habitat, so the dark-green segment is the range that is natural and protected. Layout mirrors plot_conversion: title, one subtitle with the occurrence count, and a legend on the right.

Usage

plot_protection(assessment, species = NULL, lang = c("en", "pt"))

Arguments

Value

A ggplot object (ggplot2 available) or, in the base-graphics fallback, invisibly the plotted percentage matrix (rows EOO/AOO).

See Also

mas_plotly for the interactive version.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
# reads WDPA and one year of MapBiomas (the multi-year habitat trend is skipped)
res <- assess_species(occ, protected = TRUE, infer_decline_from_habitat = FALSE,
                      verbose = FALSE)
plot_protection(res)

Description

Draws percentage of area versus year as stacked areas, one band per class (or group), using the official MapBiomas colours, in the style of the MapBiomas coverage figures. Uses ggplot2 when available, otherwise base graphics.

Usage

plot_timeseries(ts, title = NULL, legend = TRUE, lang = c("en", "pt"))

Arguments

Value

A ggplot object (invisibly) when ggplot2 is available; otherwise NULL after drawing a base plot.

Description

Returns the protected-area polygons that fall within the bounding box of aoi. By default it reads the global World Database on Protected Areas (WDPA) via wdpa_areas() (see there for the source), so the overlap works anywhere in the world. For offline use, point src to a local protected-area file (.shp, .gpkg, .geojson) instead; it is then filtered to the AOI bounding box and standardised to the same columns.

Usage

protected_areas(aoi, src = NULL, cache = TRUE, cache_dir = NULL, quiet = TRUE)

Arguments

Details

The result carries three standardised columns: pa_name, pa_category and pa_group, plus all original attributes.

Value

An sf of protected-area polygons in EPSG:4326 (possibly with zero rows when none intersects the AOI), or NULL if the source could not be read.

See Also

wdpa_areas()

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
sp1 <- occ[occ$species == occ$species[1], ]
pas <- protected_areas(calc_eoo(sp1)$hull)  # reads WDPA over the web
unique(pas$pa_name)

Description

Imports occurrence records from a spreadsheet (.xlsx/.xls), delimited text (.csv/.tsv/.txt) or a vector file (.shp, .gpkg, .geojson; for shapefiles you may also pass a .zip containing the .shp/.shx/.dbf/.prj set) and returns a clean point sf in WGS84 (EPSG:4326) with a standardised species column.

Usage

read_occurrences(
  path,
  species_col = NULL,
  lon_col = NULL,
  lat_col = NULL,
  crs = 4326,
  sheet = NULL,
  sep = NULL,
  dec = NULL,
  encoding = "UTF-8",
  default_species = "sp1"
)

Arguments

Details

Longitude, latitude and species columns are auto-detected from common header names (Darwin Core decimalLongitude/decimalLatitude, lon/lat, x/y, scientificName, etc.). You can override the detection with the corresponding arguments. Rows with missing or out-of-range coordinates are dropped with a message.

For delimited text the field separator and decimal mark are auto-detected, so Brazilian-style CSVs exported from Excel (; separator, , decimals, optional UTF-8 BOM) are read correctly without extra arguments.

Value

An sf of POINT geometries in EPSG:4326 with a species column plus all original attributes.

Examples

f <- system.file("extdata", "example_occurrences.csv", package = "mappingAS")
occ <- read_occurrences(f)
table(occ$species)

Description

Starts the interactive app for uploading occurrences, computing EOO/AOO and MapBiomas habitat conversion, and exploring/exporting the results.

Usage

run_app(launch.browser = TRUE, max_upload_mb = 500, ...)

Arguments

Value

Invisibly NULL; called for its side effect.

Examples

if (interactive()) {
  run_app()
  # allow uploads up to 2 GB
  run_app(max_upload_mb = 2048)
}

Description

Global analogue of mb_raster_local for the Esri / Impact Observatory 10 m Annual Land Use Land Cover product. Determines the MGRS grid-zone tile(s) intersecting aoi, streams a windowed read of each via GDAL's /vsicurl/ driver (no Google Earth Engine, no account), masks to the polygon and, when the AOI spans more than one tile, merges the pieces (reprojected to geographic coordinates for display). For accurate area statistics the assessment path tabulates each tile in its native projection and sums, rather than reprojecting; use summarise_conversion on the class areas for that.

Usage

s2_raster_local(
  aoi,
  year = 2023,
  src = NULL,
  base_url = NULL,
  mask = TRUE,
  cache = TRUE,
  cache_dir = NULL
)

Arguments

Value

A terra SpatRaster of Esri land-cover codes for the AOI.

See Also

esri_legend, s2_source_url, mb_raster_local

Description

Returns the public Cloud-Optimized GeoTIFF URL of one MGRS grid-zone tile of the Esri / Impact Observatory 10 m Annual Land Use Land Cover product. The global mosaic is tiled by MGRS grid-zone designator (e.g. "47P"); an area of interest usually intersects one or a few tiles, which the local backend resolves automatically (see s2_raster_local).

Usage

s2_source_url(tile, year = 2023, base_url = NULL)

Arguments

Value

A length-1 character URL of the form <base>/<tile>_<year>.tif.

See Also

s2_raster_local, esri_legend

Examples

s2_source_url("47P", 2023)

Description

Years available for the global Sentinel-2 / Esri land-cover series

Usage

s2_years()

Value

An integer vector of the years covered by the Esri / Impact Observatory 10 m Annual Land Use Land Cover product (currently 2017-2023).

See Also

esri_legend, s2_source_url, assess_species

Examples

range(s2_years())

Description

Aggregates a table of per-class areas into conservation groups and computes the percentage of converted (anthropic) versus remaining natural habitat.

Usage

summarise_conversion(
  class_areas,
  collection = 10,
  initiative = "brazil",
  water_in_denominator = FALSE
)

Arguments

Details

The headline metrics use a terrestrial denominator (natural + anthropic), excluding water, not-observed and ambiguous "other" classes, which is the most defensible measure of habitat conversion. A total-area version (denominator = everything except not-observed) is also returned for transparency.

Value

A list with: converted_pct, natural_pct (terrestrial, the headline numbers), converted_pct_total, natural_pct_total, the group areas (natural_km2, anthropic_km2, water_km2, other_km2, not_observed_km2, total_km2) and by_class (the per-class table joined to the legend).

Examples

ca <- data.frame(code = c(3, 15, 24, 33), area_km2 = c(60, 30, 10, 5))
summarise_conversion(ca)$converted_pct

Description

Fire analogue of summarise_conversion. Pass the known range area (range_km2, e.g. eoo$area_km2) as denominator so the percentage is exact and robust to the raster's NoData handling.

Usage

summarise_fire(fire_areas, range_km2 = NULL)

Arguments

Value

A list with burned_km2, total_km2, burned_pct, freq_mean, freq_max and by_freq.

Description

Given a species' occurrence points and (optionally) its EOO and AOO, plus a UC layer from protected_areas(), computes how much of the range is legally protected: the share of occurrences inside UCs, the percentage/area of the EOO and AOO that fall within UCs, and the list of UCs touched.

Usage

summarise_protected(points, pa, eoo = NULL, aoo = NULL)

Arguments

Details

Percentages are computed on the species' equal-area projection so ratios are exact; the reported eoo_km2/aoo_km2 inside UCs are derived from the headline EOO/AOO so they stay consistent with assess_species(). The AOO overlap follows the grid nature of the metric: an occupied 2-km cell counts as protected when it intersects any UC.

Value

A list: n_occ, n_occ_in, occ_pct; eoo_pct, eoo_km2; aoo_pct, aoo_km2, aoo_cells_in; n_uc; list (per-UC data.frame) and layer (the UC sf).

Description

Convenience wrapper that pulls the stored EOO hull or AOO geometry from an assessment and runs cover_timeseries on it, reusing the assessment's collection and backend by default.

Usage

timeseries_for_species(
  assessment,
  species = NULL,
  range = c("eoo", "aoo"),
  years = NULL,
  by = c("class", "group"),
  src = NULL,
  verbose = TRUE,
  max_pixels = 8e+06
)

Arguments

Value

The long data frame from cover_timeseries, with attributes species and range set.

Description

Derives a character vector of herbarium-style voucher citations from the attribute columns of an occurrence table (or the sf returned by read_occurrences), so the "Examined vouchers" box of the factsheet can be filled automatically instead of by hand.

Usage

vouchers_from_occ(
  occ,
  species = NULL,
  voucher_col = NULL,
  collector_col = NULL,
  number_col = NULL,
  herbarium_col = NULL,
  unique = TRUE,
  sort = TRUE
)

Arguments

Details

Two strategies are tried, in order:

1. If a ready-made voucher column exists (e.g. voucher, exsiccata, material) its non-empty values are used verbatim.

2. Otherwise a collector column (e.g. collector, recordedBy) is combined with a collection-number column (e.g. collectorNumber, recordNumber) into "Collector Number". When a herbarium/institution column is present (e.g. herbarium, institutionCode) its code is appended in parentheses, giving "Collector Number (RB)".

Column names are matched case-insensitively from a set of common Darwin Core and herbarium aliases; pass the *_col arguments to override the detection. When no relevant column is found, an empty character vector is returned (so the caller simply leaves the box empty).

Value

A character vector of voucher strings (possibly empty).

Examples

df <- data.frame(
  species = c("Aus bus", "Aus bus"),
  collector = c("Barreira", "Silva"),
  collectorNumber = c("123", "456"),
  herbarium = c("RB", "R"),
  stringsAsFactors = FALSE)
vouchers_from_occ(df)

Description

Queries the public WDPA ArcGIS FeatureServer for the protected-area polygons whose envelope intersects the bounding box of aoi and returns them as an sf in WGS84 with the same three standardised columns used by protected_areas(): pa_name (WDPA NAME), pa_category (designation / IUCN category) and pa_group (Strict protection for IUCN Ia-III, Sustainable use for IUCN IV-VI, else the reported status), plus all original WDPA attributes.

Usage

wdpa_areas(
  aoi,
  url = wdpa_query_url(),
  marine = c("all", "terrestrial"),
  cache = TRUE,
  cache_dir = NULL,
  quiet = TRUE
)

Arguments

Details

Only the AOI's bounding box is requested (server-side envelope filter) and the server's transfer limit is followed with pagination, so this stays light even though WDPA is a global dataset. Results are cached on disk by bounding box. This is the recommended protected-area source for the "amazonia" and "colombia" initiatives (and anywhere outside Brazil), where the ICMBio service does not apply.

Value

An sf of WDPA polygons in EPSG:4326 (possibly zero rows), or NULL if the service could not be read.

Examples

occ <- read_occurrences(system.file("extdata", "example_occurrences.csv",
                                    package = "mappingAS"))
sp1 <- occ[occ$species == occ$species[1], ]
pas <- wdpa_areas(calc_eoo(sp1)$hull)  # reads WDPA over the web
unique(pas$pa_name)

Description

The public ArcGIS FeatureServer layer that serves the World Database on Protected Areas (WDPA) polygons, used by wdpa_areas() as a global alternative to the Brazil-only ICMBio Conservation Units. This is the layer behind the ArcGIS Living Atlas "WDPA" item and returns GeoJSON on demand, so no Google Earth Engine or bulk download is required.

Usage

wdpa_query_url()

Value

A length-1 character URL (the /query endpoint).

See Also

https://www.protectedplanet.net/en, wdpa_areas()