readNFI: Read raw SNFI tables from archives, URLs, or local files

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

Read raw SNFI tables from archives, URLs, or local files

Description

Import raw inventory tables from the Spanish National Forest Inventory (SNFI) or compatible tabular exports. Use readNFI() when you need the original table structure before computing metrics with higher-level workflows.

Usage

readNFI(nfi, nfi.nr = 4, 
    dt.nm = "PCMayores", 
    file_ext = NULL, 
    file_name = NULL, 
    ...)

Arguments

nfi	character. Inventory source to read. Accepted values are: (i) a province name or province code to be resolved to an official SNFI download URL; (ii) a local or remote .zip archive; or (iii) one or more direct paths to decompressed .csv, .dbf, .mdb, or .accdb files.
nfi.nr	integer. SNFI stage used when nfi is given as a province identifier or when the inventory stage cannot be inferred from file names. Use 2, 3, or 4.
dt.nm	character. Table name or names to import from the selected inventory source. For second-stage DBF inputs, "PCMayores" is internally remapped to "PIESMA". For many third- and fourth-stage tree workflows, "PCMayores" is the main tree table.
file_ext	character. Optional file extension or extensions forwarded to fetchNFI when nfi is a province identifier or a .zip archive. Leave NULL to use the default Access/DBF extensions handled by fetchNFI(). Use "csv" for zipped CSV exports.
file_name	character. Optional file name or stem passed to fetchNFI to keep only specific files inside a .zip archive.
...	Additional arguments passed to fetchNFI, such as dir or timeOut.

Details

The input nfi can be supplied in three main forms. First, it can be a province name or code; in that case, readNFI() resolves the identifier to an official SNFI download URL according to nfi.nr. Second, it can be a local or remote .zip archive; the function then delegates extraction to fetchNFI. Third, it can be one or more already decompressed file paths.

When the selected files are .csv, the function detects the field separator automatically and returns either one data frame or a named list of data frames. When the selected files are Access or DBF tables from the SNFI, the function reads the requested table, converts numeric-looking factors back to numeric values, preserves character columns, and adds province and inventory-stage metadata.

Access backends are platform dependent. On Windows, reading .mdb or .accdb files requires package RODBC and an installed Microsoft Access driver. On Unix-like systems, it requires package Hmisc together with the external mdbtools utilities. Use file_ext = "csv" to bypass those dependencies when you work with zipped CSV exports.

Value

Returns one of three object types, depending on the input. First, when nfi resolves to .csv file paths, the function returns a single data.frame for one file or a named list of data.frames for several files. Second, when it reads Access or DBF tables from the SNFI, it returns a data.frame of class c("readNFI", "data.frame"). This object includes leading columns nfi.nr and pr, stores the province vector in attr(x, "pr."), and stores the inferred inventory stage in attr(x, "nfi.nr"). Third, the function returns NULL when fetching, extraction, or import fails, or when no requested file can be read.

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

## Minimal example using a local CSV file created on the fly
tmp <- tempfile(fileext = ".csv")
utils::write.table(
    data.frame(
        plot = 1:2,
        species = c("sp1", "sp2"),
        dbh_cm = c(12.5, 18.0)
    ),
    file = tmp,
    sep = ";",
    row.names = FALSE,
    quote = FALSE
)

x <- readNFI(tmp)
str(x)

unlink(tmp)

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