addNFIcoords: addNFIcoords

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

addNFIcoords

Description

addNFIcoords: attach NFI plot coordinates as ordinary columns.

Join a processed Spanish National Forest Inventory table with a plot-level coordinate table and append UTM coordinate metadata. This function is intentionally independent from readNFI(), so it can enrich already loaded tables without creating circular calls.

Usage

addNFIcoords(nfi, coords, 
    nfi.nr = attr(nfi, 
        "nfi.nr"), x.col = NULL, 
    y.col = NULL, huso.col = NULL, 
    x.name = "x", y.name = "y", 
    huso.name = "huso", 
    huso.source.name = "huso_source", 
    datum.name = "datum", 
    epsg.name = "epsg", 
    crs.name = "crs", 
    overwrite = FALSE, 
    keep.raw.coords = FALSE, 
    coord.factor = NULL, 
    validate = TRUE, 
    infer.huso = FALSE)

Arguments

nfi	data.frame. Inventory table, commonly an object returned by readNFI.
coords	data.frame or one-table list. Coordinate table. For IFN2 this is usually DATESTXX.DBF or the parcel layer table with CX/CY. For IFN3/IFN4 this is usually PCDatosMap or Listado definitivo.
nfi.nr	integer. Inventory stage: 2, 3, or 4. IFN2 coordinates are converted from kilometres to metres by default.
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.
x.name	Output X-coordinate column name, in metres.
y.name	Output Y-coordinate column name, in metres.
huso.name	Output UTM-zone column name when available.
huso.source.name	Output column describing whether Huso comes from the coordinate table or was inferred from province code.
datum.name	Output geodetic datum column name.
epsg.name	Output EPSG code column name when known.
crs.name	Output CRS label column name when known.
overwrite	logical. Allow overwriting existing output coordinate columns.
keep.raw.coords	logical. Keep raw source coordinate values before unit conversion.
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	logical. Fill missing UTM zones from the province code. A Huso column in coords has precedence when present. Province-filled values are marked in huso_source.

Details

The function uses province and plot identifiers to match rows in nfi with records in coords. It searches common IFN column names such as pr, Provincia, ESTADILLO, Estadillo, and NUMPAR. The main table keeps its original row order and number of rows; tree-level tables therefore receive repeated plot coordinates.

Coordinate values are treated as UTM coordinates. IFN2 coordinate columns, normally COORDEX/COORDEY or CX/CY, are interpreted as kilometres and multiplied by 1000 by default. IFN3 and IFN4 coordinate columns, normally CoorX/CoorY or CoorXC/CoorYC, are interpreted as metres.

A Huso column in the coordinate table always has priority. When infer.huso = TRUE, missing UTM zones are filled from the province code and marked as province_inferred in huso_source; otherwise the corresponding CRS fields remain NA.

Value

A data frame with the same rows and row order as nfi, plus coordinate columns. Output x and y are always in metres. Attributes record the source coordinate columns, source units, and multiplier used during conversion.

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

x <- addNFIcoords(trees, coords, infer.huso = TRUE)
x[, c("pr", "ESTADILLO", "x", "y", "huso", "datum", "epsg")]

## Keep raw IFN2 kilometre coordinates for checking.
addNFIcoords(trees, coords, keep.raw.coords = TRUE)

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