addNFIsf: addNFIsf

In basifoR: Retrieval and Processing of the Spanish National Forest Inventory

addNFIsf

Description

addNFIsf: convert an NFI table and coordinate table to sf points.

Join an already loaded inventory table to an already loaded coordinate table and return an sf point data frame. The inventory table is preserved as the attribute table, while coordinates are used to build a geometry column instead of being returned as ordinary x/y columns.

Usage

addNFIsf(nfi, coords, 
    nfi.nr = attr(nfi, 
        "nfi.nr"), x.col = NULL, 
    y.col = NULL, huso.col = NULL, 
    crs = NULL, keep.coord.meta = FALSE, 
    mixed.crs = c("na", 
        "error"), na.action = c("keep", 
        "drop", "error"), 
    overwrite = FALSE, 
    keep.raw.coords = FALSE, 
    coord.factor = NULL, 
    validate = TRUE, 
    infer.huso = NULL)

Arguments

nfi	data.frame. Inventory table, commonly returned by readNFI.
coords	data.frame or one-table list. Coordinate table.
nfi.nr	integer. Inventory stage: 2, 3, or 4.
x.col	Optional source X-coordinate column in coords.
y.col	Optional source Y-coordinate column in coords.
huso.col	Optional source UTM-zone column in coords.
crs	Optional CRS passed to sf::st_as_sf. When NULL, the function uses the unique EPSG derived from coordinate metadata, if one is available.
keep.coord.meta	Keep Huso/datum/EPSG metadata columns in the sf attribute table. When FALSE, these are stored only in attributes.
mixed.crs	What to do when rows imply more than one EPSG code. The default creates sf with CRS NA and warns.
na.action	Handling of rows that do not match a coordinate record.
overwrite	Allow overwriting coordinate metadata columns when keep.coord.meta = TRUE.
keep.raw.coords	Passed to addNFIcoords; mainly useful for debugging and ignored in the final sf output unless keep.coord.meta = TRUE.
coord.factor	Numeric multiplier applied to raw coordinates. Defaults to 1000 for IFN2 and 1 for IFN3/IFN4.
validate	logical. Warn about duplicate coordinate keys and unmatched plots.
infer.huso	Fill missing UTM zones from province code. By default, TRUE for IFN2 and FALSE for IFN3/IFN4.

Details

This helper is the spatial analogue of addNFIcoords(). It first creates temporary coordinate and CRS metadata columns, then converts the result to an sf point object with sf::st_as_sf(). Temporary coordinate columns are removed from the final object unless keep.coord.meta = TRUE.

An sf geometry column can store only one active CRS. If rows imply more than one EPSG code, mixed.crs = "na" creates the object with an undefined CRS and stores the detected metadata in attr(x, "coord_reference"); mixed.crs = "error" stops instead.

Rows without matching coordinates can be kept as missing point geometries, dropped, or rejected with na.action. This is useful when external CSV files contain partial plot coverage.

Value

An sf data frame with point geometries. The geometry coordinates are UTM metres. CRS is assigned only when a unique EPSG is available or when crs is supplied explicitly.

Author(s)

Wilson Lara [aut, cre] (ORCID: <https://orcid.org/0000-0003-3527-1380>), Cristobal Ordonez [aut] (ORCID: <https://orcid.org/0000-0001-5354-3760>), Aitor Vázquez-Veloso [aut] (ORCID: <https://orcid.org/0000-0003-0227-506X>), Felipe Bravo [aut] (ORCID: <https://orcid.org/0000-0001-7348-6695>)

Examples

trees <- data.frame(
    nfi.nr = 2,
    pr = 45,
    ESTADILLO = c(1, 1, 2),
    ESPECIE = c(21, 21, 25)
)
attr(trees, "nfi.nr") <- 2

coords <- data.frame(
    PROVINCIA = 45,
    ESTADILLO = c(1, 2),
    COORDEX = c(412, 413),
    COORDEY = c(4411, 4412)
)

if (requireNamespace("sf", quietly = TRUE)) {
    x <- addNFIsf(trees, coords, infer.huso = TRUE)
    sf::st_crs(x)
    sf::st_geometry(x)
}

basifoR documentation built on Aug. 26, 2026, 9:06 a.m.