readNFI_spatial: readNFI spatial

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

readNFI spatial

Description

Read SNFI data and store plot geometry as an attribute sidecar

This function is a conservative spatial companion to readNFI(). It keeps the ordinary tabular output of readNFI() and stores a plot-level geometry registry in attr(x, "nfi_geometry_registry"). By default, the returned object remains a data frame and carries geometry as an attribute sidecar. If spatial = "sf", the function returns an sf object by joining the sidecar geometry back to each row. The attribute-sidecar default lets downstream metric functions carry spatial information without pushing a geometry column through tabular routines.

Usage

readNFI_spatial(nfi, 
    nfi.nr = 4, dt.nm = "PCMayores", 
    file_ext = NULL, 
    file_name = NULL, 
    ..., spatial = c("attribute", 
        "sf", "none"), 
    geometry.dt.nm = dt.nm, 
    coord.nm = NULL, 
    schema = NULL, coords = NULL, 
    x.col = NULL, y.col = NULL, 
    pr.col = NULL, plot.col = NULL, 
    crs = NULL, coord.units = "m", 
    coord.accuracy.note = NULL, 
    geometry.source = c("auto", 
        "snfi", "external", 
        "none"), validate = TRUE, 
    coord.factor = NULL, 
    huso.method = c("auto", 
        "candidate", 
        "xgap", "province", 
        "none"), huso.candidates = NULL, 
    repair.table.huso = TRUE, 
    target.crs = NULL, 
    boundary = FALSE, 
    boundary.source = c("auto", 
        "gisco", "gadm", 
        "user", "none"), 
    boundary.object = NULL, 
    boundary.level = 2, 
    boundary.path = tools::R_user_dir("basifoR", 
        "cache"), boundary.ext = "json", 
    boundary.version = "4.1", 
    boundary.crs = NULL, 
    infer.huso = NULL)

Arguments

nfi	Inventory source passed to readNFI(): province code or name, local/remote zip archive, decompressed files, or a data frame.
nfi.nr	Spanish NFI stage. Use 2, 3, or 4.
dt.nm	Main table to read and return as tabular data.
file_ext	Optional file extension passed to readNFI() and readNFIsf() when the input must be fetched or filtered.
file_name	Optional file-name filter passed to readNFI(). The spatial registry reads coordinates independently.
...	Additional arguments passed to readNFI() and readNFIsf(), such as dir or timeOut.
spatial	"attribute" stores a plot-level spatial registry in an attribute and keeps a tabular output. "sf" returns an sf object by joining the sidecar geometry to each row. "none" returns the ordinary readNFI() output.
geometry.dt.nm	Table used to build the geometry registry. In most SNFI workflows this can match dt.nm.
coord.nm	Optional SNFI coordinate table name. If NULL, the function detects DATEST for IFN2 and PCDatosMap/Listado definitivo for IFN3/IFN4.
schema	Optional external_schema. For external inventories, spatial metadata can be stored in schema$defaults$spatial, for example a named list containing plot, x, y, and crs entries. Explicit coordinate arguments below override schema values.
coords	Optional external coordinate table. Use this for non- Spanish inventories when coordinates live in a separate table. It can be a data frame or an sf object.
x.col	Optional X/easting/longitude column for external coordinate tables. If NULL, common names such as x, coord_x, easting, and longitude are detected.
y.col	Optional Y/northing/latitude column for external coordinate tables. If NULL, common names such as y, coord_y, northing, and latitude are detected.
pr.col	Optional province, region, or stratum key for external coordinate matching. It is not required for one-region external inventories.
plot.col	Optional plot identifier column for external coordinate matching. If NULL, common plot names such as plot_id, sample_id, and site_id are detected.
crs	Optional CRS for external coordinates, passed to sf::st_as_sf(). Use an EPSG code such as 25830 or 4326.
coord.units	Coordinate units recorded in the external spatial sidecar metadata.
coord.accuracy.note	Optional note describing the accuracy or provenance of user-supplied coordinates. This is most useful when replacing public inventory coordinates with field-validated plot-centre coordinates. Spanish NFI public coordinates receive an automatic accuracy note.
geometry.source	Source used to build the sidecar. "auto" first uses explicit external coordinates when available, then tries SNFI geometry only for province-like sources.
validate	Warn when duplicate plot geometries are found or when geometry cannot be attached.
coord.factor	Optional coordinate multiplier for SNFI coordinate tables. By default IFN2 kilometre coordinates are detected and converted to metres.
huso.method	Method for assigning SNFI UTM zones when the coordinate table does not contain a direct Huso column. "auto" uses table Huso, then the historical huso1/huso2/huso3 + CoorX rule, then province fallback.
huso.candidates	Optional candidate UTM zones for SNFI Huso inference. Use, for example, c(29, 30) for provinces that span zones 29 and 30 when no Huso columns are available.
repair.table.huso	logical. If TRUE, direct table-supplied Huso values are checked against the candidate-zone CoorX threshold rule before building geometry. This repairs boundary-zone cases such as plots stored in the neighbouring UTM zone.
target.crs	Optional common CRS for projected SNFI geometries. When NULL, a single source EPSG is kept, or mixed ED50 zones are transformed to EPSG:23030.
boundary	logical. If TRUE, attach an optional boundary sidecar in attr(x, "nfi_boundary"). Spanish NFI province-like inputs can use built-in GISCO/GADM download helpers; external inventories must provide boundary.object.
boundary.source	Boundary source. "auto" uses a user object when supplied and otherwise tries GISCO/NUTS before GADM for Spanish province-like inputs.
boundary.object	Optional user-provided sf polygon or multipolygon layer. External inventories must use this route; automatic built-in boundary selection is limited to Spanish NFI inputs.
boundary.level	GADM administrative level used when boundary.source = "gadm". GISCO uses NUTS-3.
boundary.path	Cache directory used for optional boundary downloads.
boundary.ext	GADM extension used by gadm_spatial().
boundary.version	GADM version used by gadm_spatial().
boundary.crs	CRS assigned to boundary.object when it lacks CRS metadata. It is required when the supplied object has no CRS.
infer.huso	Backward-compatible argument forwarded to the fallback readNFIsf() route. The new SNFI table route prefers huso.method.

Details

For Spanish NFI sources, the coordinate note is stage-specific and is stored in attr(x, "nfi_geometry_registry")$coord_accuracy_note. IFN2 coordinates are treated as official public locations derived from the kilometre UTM sampling grid. IFN3 coordinates are treated as official cartographic plot-location coordinates in UTM metres; when their Huso is not explicit, CRS metadata may be reconstructed from candidate Huso fields, coordinate rules, or fallback methods. IFN4 CoorX/ CoorY are treated as official public coordinates available before fieldwork for the plot centre. These stage notes document coordinate interpretation; they do not claim field-validated exact plot-centre precision.

External inventories or user-supplied coordinate tables do not receive an automatic coordinate-accuracy note because basifoR cannot know their measurement protocol or precision. If better coordinates become available, for example field GPS or institutional plot-centre coordinates, pass them through coords, x.col, y.col, plot.col, and optionally pr.col, with geometry.source = "external" and provide coord.accuracy.note only when the coordinate source is known. This replaces the spatial sidecar while keeping the ordinary readNFI() table and downstream metric calculations unchanged.

Value

A data frame with the same tabular content returned by readNFI(). When spatial = "attribute", the object also carries a plot-level geometry sidecar in attr(x, "nfi_geometry_registry"). The sidecar stores one geometry per inventory plot, CRS metadata, coordinate provenance, and normalized join keys for later *_spatial() metric functions.

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

	toy <- data.frame(
	    nfi.nr = 4,
	    pr = 28,
	    esta = c("P1", "P1", "P2"),
	    espe = c(21, 21, 25),
	    Dn = c(120, 185, 260),
	    altura = c(7.1, 9.4, 13.2),
	    x = c(-3.70, -3.70, -3.69),
	    y = c(40.40, 40.40, 40.41)
	)
	attr(toy, "nfi.nr") <- 4

	x <- readNFI_spatial(
	    toy,
	    spatial = "attribute",
	    geometry.source = "external",
	    plot.col = "esta",
	    x.col = "x",
	    y.col = "y",
	    crs = 4326,
	    boundary = FALSE
	)

	hasNFIgeometry_spatial(x)
	names(getNFIgeometry_spatial(x))

	## Keep the ordinary readNFI() output but carry plot geometry in attributes.
	## cache <- tools::R_user_dir("basifoR", "cache")
	## x <- readNFI_spatial(28, nfi.nr = 3, dt.nm = "PCMayores", dir = cache)
## is.data.frame(x)
## hasNFIgeometry_spatial(x)
## reg <- getNFIgeometry_spatial(x)
## reg$geometry

## Return a true sf object when direct spatial output is wanted.
## xsf <- readNFI_spatial(28, nfi.nr = 3, dt.nm = "PCMayores",
##                        dir = cache, spatial = "sf")
## inherits(xsf, "sf")

## External inventory: keep tabular data but store geometry sidecar.
## ext <- data.frame(plot_id = 1:2, x = c(440000, 441000),
##                   y = c(4488000, 4489000), d = c(20, 30))
## y <- readNFI_spatial(ext, spatial = "attribute",
##                      geometry.source = "external",
##                      plot.col = "plot_id", x.col = "x", y.col = "y",
##                      crs = 25830)
## hasNFIgeometry_spatial(y)
##
## External inventory with schema-stored spatial metadata:
## sch <- new_external_schema(
##     colmap = list(plot = "plot_id", d = "d"),
##     units = list(d = "cm"),
##     levels = "plot_id",
##     defaults = list(spatial = list(plot = "plot_id", x = "x", y = "y", crs = 25830))
## )
## y2 <- readNFI_spatial(ext, spatial = "attribute", schema = sch)
## hasNFIgeometry_spatial(y2)
##
## Replacing public SNFI coordinates with improved coordinates uses the
## same external sidecar mechanism.  The improved table must contain the
## inventory plot keys and coordinate columns.
## improved <- data.frame(pr = 28, Estadillo = c(1, 2),
##                        x_gps = c(440000, 441000),
##                        y_gps = c(4488000, 4489000))
	## z <- readNFI_spatial(28, nfi.nr = 4, spatial = "attribute",
	##                      geometry.source = "external", coords = improved,
	##                      pr.col = "pr", plot.col = "Estadillo",
	##                      x.col = "x_gps", y.col = "y_gps", crs = 25830,
	##                      coord.accuracy.note = "Field-validated plot-centre coordinates.")

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