# basifoR 0.8.0

## Bug fixes

* The legacy over-bark volume (`v`, from the `parEqVcc` equations) was
  computed with height in dm instead of m. Values were too large by a factor
  of about 4 to 12 (median about 9) and exceeded the volume of the enclosing
  cylinder for every tree tested. The equations take diameter in mm and height
  in m and return dm3, as the official IFN equations do. With the correction
  they agree with the official `VCC` equations (median ratio 1.00 in a sample
  of 14 province-species pairs). This changes every legacy `v`, and every `vcc`
  that fell back to it.

* The legacy equation now chooses its form class (`cub.met = "freq"`) within
  each province and species, not once for the whole dataset. Before, a species
  without the dataset's most frequent form class lost its legacy volume
  whenever it shared a dataset with other species. The tie within a species is
  broken by frequency in the whole dataset, so species that had the dataset
  mode keep their previous value, and no previously computed value changes.
  For a species with several form classes in its province, the form class
  chosen therefore depends on the composition of the dataset.

* `metrics2Vol()` no longer computes volume from another species'
  coefficients. When a species had no coefficient row for its province and
  inventory cycle, the previous release silently used the first row of that
  province, which belongs to a different species, and reported it as an
  equation result. The same happened when a species had rows for other
  parameters but none for the requested one, and when the species code was
  missing. Volume results may therefore change for affected species.

* External volume path: a volume column in the source is no longer picked up
  by the implicit alias `v`. Before, when the input to `externalMetrics2Vol()`
  already carried standardized metrics and kept a column named `V` or `v` (for
  example the French NFI `V`, IGN's own "bois fort" volume), trees whose
  volume method could not run, such as trees without height, received that
  column's value labelled `"fallback"`. In a 10,000-tree slice of the 2024
  French export this affected 5,685 trees. Pre-existing volume is now read only
  when the schema or `colmap` maps `v` explicitly. Without that mapping and
  without a volume method, `v` is `NA`. The `inventoryMetrics()` and
  `external_dendroMetrics()` route from raw data was not affected, because the
  column was not carried to the volume step.

* An explicit `v` mapping in `new_external_schema()` now works through
  `external_dendroMetrics()` and `inventoryMetrics()`: the mapped column is
  carried to the volume step with the unit declared in the schema. Before, it
  stopped with "Missing required column".

## New behaviour

* When the official equation cannot be used for a tree, `metrics2Vol()` now
  falls back to the corrected legacy equation for the same province and
  species if it has coefficients, and returns `NA` otherwise. A warning names
  the species, the province and the cycle. With `track_provenance = TRUE`,
  `*_source` is `"fallback_legacy"` (or `"missing"` when no value is
  available) and `*_status` names the reason: `"no_species_coefficients"`,
  `"no_parameter_coefficients"`, `"no_parameters"`, `"no_function"`,
  `"no_arguments"`, `"returned_na"` or the error message. A fallback is never
  reported as `"ok"`.

* New argument `legacy_fallback` in `metrics2Vol()` (default `TRUE`). Set it
  to `FALSE` to use official equations only and get `NA` where they cannot be
  applied. It can be passed through `dendroMetrics()` and `inventoryMetrics()`.

* With `track_provenance = TRUE`, grouped summaries from `dendroMetrics()` and
  `inventoryMetrics()` gain one column per summarised volume variable, for
  example `vcc_na_share`: the share (0 to 1) of the group's expansion factor
  (trees per hectare) whose tree volume is missing. The volume total sums only
  the trees with a value, so a non-zero share means the total is incomplete.
  Like the `*_source` and `*_status` columns, it is not returned by default,
  so the default summary has the same columns as in 0.7.9.

# basifoR 0.7.9

## Bug fixes

* The downloadable Toledo example in `inventoryMetrics()` moved from `\donttest{}`
  to `\dontrun{}`. It needs internet access and an Access backend (mdbtools or
  ODBC), so it could not run during CRAN checks, and it now uses a session
  temporary directory rather than a persistent user cache.

# basifoR 0.7.8

## Major changes

* Added `listNFI_tables()`, which lists available raw tables in Spanish National Forest Inventory sources and supports cached/local table discovery.

* Added `readNFIcoords()`, `addNFIcoords()`, `readNFIsf()`, and `addNFIsf()` to attach plot-level UTM coordinates to Spanish NFI tables and optionally return `sf` point objects while reusing locally cached NFI files.

* Added spatial workflow functions `readNFI_spatial()`, `nfiMetrics_spatial()`, `metrics2Vol_spatial()`, and `inventoryMetrics_spatial()`. These functions preserve the tabular workflow while carrying plot geometries as sidecar attributes and optionally returning `sf` objects.

* Added spatial sidecar helpers `hasNFIgeometry_spatial()`, `getNFIgeometry_spatial()`, `copyNFIgeometry_spatial()`, and `asNFI_spatial_sf()` to inspect, propagate, and reconstruct plot-level geometries.

* Added optional boundary sidecars through `gadm_spatial()`, `filter_gadm_province_spatial()`, `hasNFIboundary_spatial()`, `getNFIboundary_spatial()`, `copyNFIboundary_spatial()`, and `copyNFIspatial_sidecars()` for plotting and spatial quality control without requiring the `geodata` package.

* Added S3 plot methods for `readNFI_spatial`, `nfiMetrics_spatial`, `metrics2Vol_spatial`, and `inventoryMetrics_spatial` objects. The methods can draw mapped metric panels with optional boundary sidecars, quantile-based point-size classes, `ggplot2` rendering when available, and a base-graphics fallback otherwise.

* Added dominant-diameter support through the paired `Dd` and `dd` variables. `nfiMetrics()` and `externalMetrics()` can now return tree-record `Dd` values, while `dendroMetrics()` and `external_dendroMetrics()` can summarize them as stand-level `dd`.

* Extended `dominant_height_method_registry()` so bundled dominant-height methods also carry paired dominant-diameter methods and metadata. Dominant diameter uses the same diameter ordering, threshold, and fallback convention as the selected dominant-height method, but it requires only valid diameters and expansion factors.

## API and unit changes

* `nfiMetrics()` now includes `Dd` in its default `var` set. `Dd` requires `d` and `n`; `Hd` continues to require `h`, `d`, and `n`.

* `externalMetrics()` and `external_dendroMetrics()` now support `Dd` and `dd`, including custom paired functions through `domdiameter_fun`.

* Tree-level height outputs now use metres consistently. `nfiMetrics()` reports `h` and `Hd` in metres, `dbhMetric(..., met = "h")` returns height in metres, and dominant-height method metadata reports `unit = "m"`.

* External workflows now standardize declared raw height units (`"m"`, `"dm"`, or `"cm"`) to metres for `h` and `Hd`.

* Grouped summaries now distinguish tree expansion factors from group totals more explicitly: tree-level outputs keep `n`, while grouped outputs report total density as `n_tot`.

* Stand-level summaries report `d` and `dd` in centimetres, `h` and `hd` in metres, `ba` in `m2 ha-1`, `n_tot` in `ha-1`, and volume variables in `m3 ha-1`.

## External-inventory workflow

* Improved external workflow support for `externalMetrics()`, `externalMetrics2Vol()`, `external_dendroMetrics()`, and `inventoryMetrics(backend = "external")`, including propagation of unit metadata, design metadata, dominant-height metadata, dominant-diameter metadata, and volume metadata.

* `externalMetrics2Vol()` can now derive missing standardized inputs through `externalMetrics()` when `compute_metrics_if_needed = TRUE`, including `Hd` and `Dd` when those are required by downstream methods.

* `external_dendroMetrics()` now supports optional tree-level output units through `tree_d_unit_out` and `tree_h_unit_out` when `summ.vr = NULL`. Grouped outputs use the package's stand-level units.

* `inventoryMetrics()` now uses `"Estadillo"` as the default SNFI grouping level and uses schema levels or detected plot identifiers for external inventories when `summ.vr` is omitted.

* Added support for user-supplied coordinates and boundary polygons in external spatial workflows. External inventories can participate in the spatial sidecar workflow when coordinates are supplied through an `sf` input, `coords`, or `schema$defaults$spatial`.

* External spatial workflows now use user-provided boundary objects through `boundary.object`; they no longer infer Spanish GADM boundaries for external inventories.

## Spatial improvements

* Improved Spanish NFI coordinate handling with stage-specific coordinate notes, invalid-coordinate filtering, mixed-Huso handling, per-plot Huso inference, and coordinate diagnostics stored in the spatial registry.

* `inventoryMetrics_spatial()` can summarize grouped geometries as centroids when possible and keeps compatible grouping keys between metric outputs and geometry sidecars.

* Spatial plot methods now document that quantile classes are computed from finite, non-missing values in the object supplied to `plot()`. Quantile classes are unweighted and are based on P5, P25, P50, P75, and P95 thresholds for each selected variable.

* Improved spatial plot dispatch by keeping basifoR spatial classes before `sf` classes so `plot()` reaches the package-specific S3 methods.

## Volume and metadata improvements

* Hardened the legacy volume compatibility path. `metrics2Vol()` now makes current tree-metric units explicit before calling `metrics2Vol_legacy()`, and the legacy helper assumes `d = "mm"` and `h = "m"` when older inputs arrive without unit metadata before converting height to the legacy equation unit.

* `metrics2Vol()` continues to use the modern registry path for normal volume outputs and reserves the legacy path for explicit legacy requests such as `parametro = "V"` or `keep.legacy = TRUE`.

* `metrics2Vol()` and `externalMetrics2Vol()` now preserve dominant-height and dominant-diameter metadata when volume outputs are added.

## Documentation fixes

* Expanded inline documentation for exported functions, S3 methods, registries, spatial accessors, and external workflow arguments.

* Clarified dominant height and dominant diameter documentation, including the difference between `Hd`, `Hd_strict`, and `Hd_mean_fallback`, and the fact that `Dd` may be available when missing heights leave `Hd` undefined.

* Clarified spatial plotting documentation for quantile classes, boundary sidecars, and base-graphics versus `ggplot2` rendering.

# basifoR 0.7.7

## Major changes

* Expanded **basifoR** from an SNFI-focused toolkit into a design-aware inventory workflow package that also supports external inventories with custom schemas, sampling designs, and volume methods.

* Added a unified workflow dispatcher, `inventoryMetrics()`, with `backend = "auto"`, `"snfi"`, or `"external"` to route complete workflows through the appropriate backend.

* Added external-inventory workflow functions: `externalMetrics()`, `externalMetrics2Vol()`, and `external_dendroMetrics()`.

* Added reusable sampling-design helpers: `new_inventory_design()`, `new_concentric_design()`, `snfi_design()`, `trees_per_ha()`, and print methods for design objects.

* Refactored SNFI volume computation into a registry-based system through `metrics2Vol()`, `default_snfi_volume_equations()`, and `snfi_volume_method_registry()`.

* Added external volume-method infrastructure through `new_volume_method()`, `default_external_volume_methods()`, `external_volume_method_registry()`, and `new_external_schema()` to support custom mappings, parameter tables, and equation selection.

* Added `update()` methods for `dendroMetrics`, `external_dendroMetrics`, and `inventoryMetrics` objects to support reproducible re-evaluation of stored calls.

## API changes

* `metrics2Vol()` now uses a registry-based interface with `parametro`, `method_registry`, `keep.legacy`, and `track_provenance`.

* `metrics2Vol()` no longer behaves as a legacy `v`-only wrapper by default. Users who need the previous behavior should request the legacy output explicitly.

* `dbhMetric()` and `nfiMetrics()` now accept an explicit `design` argument instead of relying only on hard-coded SNFI expansion logic for tree-density calculations.

* `dendroMetrics()` now accepts lists of inputs and supports parallel execution through `mc.cores`.

## Improvements

* `fetchNFI()` gained `file_name` filtering so users can extract specific files from compressed archives.

* `readNFI()` gained explicit `nfi.nr`, `file_ext`, and `file_name` arguments, and now documents zipped CSV workflows in addition to Access and DBF inputs.

* `readNFI()` now performs clearer platform-specific backend checks and provides installation guidance for Microsoft Access drivers on Windows and `mdbtools` on Unix-like systems.

* `dendroMetrics()` now preserves workflow metadata more consistently while aggregating stand-level summaries from tree-level outputs.

* Package examples and documentation now emphasize reproducible, design-aware workflows and broader inventory support beyond the original SNFI-only interface.

## Deprecated and removed

* Removed the long-deprecated `urlToTemp()` helper from the exported interface and documentation. Use `fetchNFI()` instead.

# basifoR 0.6

## Major changes

* The package became installable on 64-bit Windows systems.

* Added `getNFI()`, which can download data from the 2nd to the 4th stages of the Spanish National Forest Inventory using province names or codes as the main argument, removing the need to specify URLs manually.

* `readNFI()` added support for `RODBC::odbcConnectAccess2007()`.

* `urlToTemp()` was deprecated in favor of `fetchNFI()`.

## Minor improvements

* `readNFI()` now converts numeric columns stored as factors back to numeric while preserving character columns.

# basifoR 0.5

## Major changes

* Added support for Access files from the fourth Spanish National Forest Inventory.

## Minor improvements

* `urlToTemp()` gained two new arguments. See the package documentation.

# basifoR 0.4.1

## Documentation fixes

* Fixed missing Rd links by adding package anchors for `readNFI.Rd` and `urlToTemp.Rd`.

# basifoR 0.4

## Major changes

* `urlToTemp()` was updated after the SNFI web API changed from `www.mapama.gob.es` to `www.miteco.gob.es`.

* Internet resources began to fail gracefully with informative messages when the resource was unavailable or had changed.
