readNFIcoords: readNFIcoords

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

readNFIcoords

Description

readNFIcoords: read an NFI table and append coordinate columns.

Read one Spanish National Forest Inventory table, locate the matching plot-coordinate table, and append UTM coordinates and CRS metadata as ordinary columns. The wrapper discovers files with listNFI_tables() once and then reuses the local files present in dir; it does not intentionally download the same source twice.

Usage

readNFIcoords(nfi, nfi.nr = 4, 
    dt.nm = "PCMayores", 
    coord.nm = NULL, 
    file_ext = NULL, 
    file_name = NULL, 
    validate = TRUE, 
    ..., 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, 
    infer.huso = FALSE)

Arguments

nfi	Input accepted by listNFI_tables and readNFI: province identifier, zip archive, decompressed files, or a previously loaded data frame.
nfi.nr	integer. Inventory stage: 2, 3, or 4.
dt.nm	Table to import and preserve as the main output.
coord.nm	Optional coordinate table name. If NULL, the function validates DATEST* in listNFI_tables() but passes the generic DATEST stem for IFN2, and uses PCDatosMap/Listado definitivo for IFN3/IFN4 when available.
file_ext	Optional file extension passed to listNFI_tables().
file_name	Optional file name filter for the main-table read. Coordinate discovery ignores this argument.
validate	logical. Validate coordinate-table discovery and warn about unmatched plot keys.
...	Additional arguments passed to listNFI_tables(), such as dir or timeOut. The resulting local paths are then passed to readNFI().
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	Allow overwriting existing coordinate columns.
keep.raw.coords	Keep raw source coordinates before conversion.
infer.huso	Fill missing UTM zones from province code only when requested. A Huso column in the coordinate table has precedence. Province-filled values are marked in huso_source.

Details

The wrapper first calls listNFI_tables() to discover and, when necessary, fetch the available files. After that discovery step, the main table and the coordinate table are read from the local paths returned by listNFI_tables(), respecting the package cache philosophy and avoiding a second intentional download.

The argument dt.nm controls the main table. The coordinate table only supplies plot positions. For IFN2 the coordinate table is detected as the generic DATEST stem after validating available DATESTXX files. For IFN3 and IFN4 the function looks for PCDatosMap or Listado definitivo, unless coord.nm is supplied explicitly.

The output remains a regular data.frame enriched with coordinate and CRS metadata columns. Use readNFIsf() when an sf geometry column is preferred.

Value

A readNFI data frame enriched with plot-level spatial coordinates. The imported table named by dt.nm remains the main output; coordinate fields are joined by province and plot identifier.

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

## Synthetic example for the joining helper.
trees <- data.frame(
    nfi.nr = 3,
    pr = 28,
    Estadillo = c(10, 10, 11),
    Especie = c(21, 21, 25)
)
attr(trees, "nfi.nr") <- 3

coords <- data.frame(
    Provincia = 28,
    Estadillo = c(10, 11),
    CoorX = c(440000, 441000),
    CoorY = c(4488000, 4489000),
    Huso = 30
)

addNFIcoords(trees, coords)

## Real use with a persistent cache directory. This may download data
## the first time and reuse the local files later.
## cache <- tools::R_user_dir("basifoR", "cache")
## x <- readNFIcoords(45, nfi.nr = 4, dt.nm = "PCMayores", dir = cache)
## unique(x[, c("huso", "huso_source", "datum", "epsg")])

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