Package {FeNEU}

Type:	Package
Title:	Routines for Evaluating Forest Inventory Data
Version:	3.0.2
Date:	2026-08-27
Description:	Provides a collection of routines for evaluating data from larger forest management units, typically sample inventories, but also stand-wise inventories. The idea is to support modern forest planning approaches and to be open by design to new data sources and evaluation methods. For the methodological background of forest inventories see Kangas and Maltamo (2006) "Forest Inventory: Methodology and Applications" <doi:10.1007/1-4020-4381-3>.
License:	AGPL (≥ 3)
Encoding:	UTF-8
Imports:	tibble, dplyr, purrr, rlang, Rdpack, tidyr, readr, ggplot2, tidyselect (≥ 1.2.0), foreach, doSNOW, lifecycle, parallel, progressr, stringr, stringdist, sf
RdMacros:	Rdpack
Depends:	R (≥ 4.4), ForestElementsR (≥ 3.0.0)
Suggests:	knitr, kableExtra, rmarkdown, tinytex, testthat (≥ 3.0.0)
SystemRequirements:	pandoc (>= 1.12.3) and a LaTeX distribution (e.g. TinyTeX, see ?tinytex::install_tinytex) with the booktabs, longtable, siunitx, and makecell LaTeX packages are required for the *_pdf() output functions.
Config/testthat/edition:	3
LazyData:	true
VignetteBuilder:	knitr
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-08-27 16:15:25 UTC; casto
Author:	Peter Biber [aut, cre], Astor Toraño Caicoya [aut]
Maintainer:	Peter Biber <peter.biber@lwf.bayern.de>
Repository:	CRAN
Date/Publication:	2026-09-09 15:00:10 UTC

Require a Complete Stand Age for an Age-Based Increment Estimate

Description

Two of FeNEU's three increment strands - the yield-table estimate and the gnfi3 (BWI 3) estimate - are driven by stand age: they age a tree forward (or backward) and take the difference. A tree without an age simply yields NA there, and because the aggregation drops NAs, the resulting table looks complete while silently covering only part of the collective. Rather than let that happen, the affected functions stop.

Usage

.assert_age_complete(x, fn_name)

Arguments

Details

The check runs on the collective the calling function actually evaluates (after its own layer / removal filtering), so an inventory whose understorey lacks ages can still be evaluated for the main stand.

Value

x, invisibly and unchanged, when every tree carries an age.

Require an explicit output directory

Description

The raw->pre converters write files, so they must be told where. Earlier versions defaulted to the raw-data folder, which writes into the user's own filespace – not permitted by CRAN policy, and against the package's principle of never guessing silently. output_dir is therefore a mandatory argument, and this helper turns the bare "argument missing" into a message that says what to pass. Shared by all three raw->pre converters so they stay symmetric.

Usage

.assert_output_dir(output_dir, fn)

Arguments

Value

Invisibly TRUE; called for the error it raises.

Reconstruct the Numeric Breaks of a Factor Produced by cut()

Description

Levels generated by cut read "(a,b]", so the break vector can be read back off them. Used to classify an aggregated value with exactly the breaks the incoming tree data were classified with, instead of guessing an interval that might differ from the caller's.

Usage

.breaks_from_cut_levels(f)

Arguments

Value

A numeric vector of breaks, or NULL if the levels do not have the expected shape.

File-Name Tag for an Increment Table's Tree Collective

Description

Derives the file-name fragment identifying which tree collective an increment table describes, from the collective descriptor the increment pipeline carries along (see .collective_from_filter). The standard kinds ("main_stand", "all_layers") are already file-safe and are used as they are; a "custom" collective is tagged with its sanitised definition (the tree-filter expression) rather than the bare word "custom", so that two PDFs built from different user-defined filters do not overwrite each other. This mirrors what .table_pdf_meta does for the base and structure tables.

Usage

.collective_file_tag(collective)

Arguments

Value

A length-one character, safe to embed in a file name.

Convert plot-centre coordinates to a metric CRS for the pre files

Description

The BaySF-style pre columns are named gauss_rw/gauss_hw but, by convention, carry a projected metric CRS – real BaySF exports store UTM32 there (the “gauss” name is a legacy misnomer; verified on native FDINVKRS files, whose GAUSS_RW/GAUSS_HW hold UTM32 and whose GAUSS_KZ zone field is unreliable). FeNEU follows that convention when it writes a pre: geographic input (lonlat / ETRS89-geographic) is reprojected to UTM32 (EPSG:25832, ETRS89 / UTM zone 32N) so a pre file never holds degrees in a gauss_* column, while already-projected input (gk*, utm*) is passed through unchanged. The returned coord_sys describes the returned coordinates and is what the converter writes into the pre's coord_sys column, keeping the pre self-describing.

Usage

.coords_to_pre_metric(x, y, coord_sys)

Arguments

Value

list(x, y, coord_sys): the (possibly reprojected) coordinates and the key of their CRS.

Resolve the inventory year for a raw-to-pre conversion

Description

Downstream only the survey year is used: each plot object carries a single time_yr, and fe_inventory() validates that a plot covers one survey year. The converters therefore need a year, not a full date.

Usage

.derive_inventory_year(date_vec, inventory_year = NULL)

Arguments

Details

An explicit inventory_year always wins, and the file dates are then not parsed at all. Otherwise the year is taken as the plain calendar year of the per-plot file date. If neither an inventory_year nor a usable file date is available, the caller must stop and ask for inventory_year.

The vegetation-period convention (a survey in, e.g., April counts for the previous growing season) is deliberately not applied automatically – that is a silvicultural judgement the user expresses through inventory_year, not a hidden cut-off inside the importer.

Value

A list list(ok, years, key, arg). On success ok = TRUE and years is either a single year (override) or one year per element of date_vec. On failure ok = FALSE and key names the i18n message to report (with optional arg).

Detect the character encoding of a text file

Description

Returns the encoding of a source text file without the user having to know it. The detection is deterministic for the only distinction that occurs in practice for this package's German-language forestry exports – UTF-8 vs. Latin-1/Windows-1252 – because valid UTF-8 is a self-identifying byte pattern: a Latin-1 file with umlauts (e.g. a lone 0xE4 for "ä") is almost never a valid UTF-8 byte sequence. A byte-order mark (BOM) is honoured when present.

Usage

.detect_file_encoding(path)

Arguments

Details

Logic: (1) an UTF-8 BOM -> "UTF-8"; a UTF-16 BOM -> "UTF-16"; (2) otherwise, if the raw bytes form valid UTF-8 -> "UTF-8"; (3) otherwise "windows-1252" (a superset of ISO-8859-1 that also covers the few CP1252 punctuation bytes, harmless for umlaut data).

Not covered: UTF-16 without a BOM (extremely rare for these exports); such a file would be mis-read and is treated as an input error elsewhere.

Value

A single encoding string usable in readr::locale(encoding=).

Drop trees that need a position but do not have one

Description

The BaySF-style pre format needs no tree coordinates for trees of the innermost concentric circle: those are tallied as a group rather than located individually, so a missing azimuth / distance is legitimate and they are kept (with NA coordinates). Every larger tree does need a position – without one it cannot be placed on its circle and would be meaningless downstream.

Usage

.drop_trees_without_coords(normalised_trees, second_circle_dbh_cm)

Arguments

Details

Such trees are excluded rather than treated as a fatal error, so a user with not-yet-complete data can carry on working; the caller is expected to surface the returned message prominently (report and console), as the excluded trees take part in no evaluation.

The DBH limit is not hard-coded: it is the lower DBH bound of the second circle, i.e. it follows the circle definition of the actual inventory. With only one circle every tree is an innermost-circle tree, so nothing is dropped.

Both concentric raw formats normalise to the same column names before this runs (koord, bhd in cm, pol_wink, pol_entf), which is what lets Format 1 and Format 2 share this helper and stay symmetric.

Value

list(trees, msg): the (possibly reduced) tree data, and either NULL or a ready-to-emit warning message naming the count, the threshold and the affected inventory points.

Drop trees that carry no stand-layer code (with an identifiable report)

Description

Every living tree must be assigned to a stand layer – it is what places the tree in the main stand, the understorey, etc. A raw file may leave the layer blank for an individual tree (empty layer / bestku); such a tree ends up with best_ku = NA after normalisation, which ForestElementsR::fe_ccircle_spatial() later rejects with the cryptic “column(s) layer_key must be complete”, aborting the whole import over a single defective tree. FeNEU cannot guess the layer, so – exactly like a tree without a required position – the tree is excluded (not a fatal error, so the rest of the intact plot and inventory still build), and reported identifiably so the user can add the missing code and re-import. Dead trees always carry best_ku = -1 (set during normalisation), so only living trees with a genuinely missing layer are affected. Both concentric raw formats normalise the layer to the same best_ku column, which lets Format 1 and Format 2 share this helper and stay symmetric.

Usage

.drop_trees_without_layer(normalised_trees)

Arguments

Value

list(trees, msg): the (possibly reduced) tree data, and either NULL or a ready-to-emit warning message naming the affected trees.

Aggregate Per-Tree gnfi3 Increments to the Inventory Level

Description

Shared aggregation core for the single-inventory gnfi3 increment. Takes a per-tree frame that already carries iv_hub_m3_ha_yr (the tree's increment scaled to a per-hectare contribution) and aggregates it to the level of the whole inventory, overall and by species group.

Usage

.gnfi3_overview_core(trees_with_iv, area_info, fill_label)

Arguments

Details

Plots without trees of a given species group enter with an increment of zero in the numerator but with their full area in the denominator, so the species groups sum to the overall value.

Confidence intervals are deliberately NA throughout: a gnfi3 estimate carries no empirical between-plot variation of a measured increment. The columns exist so that the result is structurally identical to the corresponding block of the repeated-survey overview.

Value

A list with the elements overall and by_species_group, structured exactly like one collective block of inv_inc_big_overview.

Take the Per-Tree Frame Out of an Increment Bundle

Description

The class-table functions work on a per-tree increment frame. They accept either that frame directly or one of the bundles that carry it – the result of inv_increment_repeated_survey or of inv_increment_gnfi3, both of class fe_increment.

Usage

.increment_bundle_trees(x, fn_name)

Arguments

Details

Not every fe_increment object holds trees: the yield-table strand estimates at stand level and has no per-tree increment at all. Such an object is refused here with a pointer to the function that does fit, rather than failing later on a missing column.

Value

A per-tree increment data frame, with its inc_meta attribute intact.

File-Name Tag for an Increment Table's Method

Description

Derives the file-name fragment identifying which of the three increment strands a base table came from. Without it the three strands collide: the file name is built from the table title, the tree collective and the class axis, all three of which a repeated-survey, a gnfi3 and a yield-table table of the same enterprise share. The rendered PDFs are distinguishable (their subtitle names the method) – only the file names were not, so the last one rendered silently replaced the others.

Usage

.increment_method_tag(meta)

Arguments

Details

The tag is read from the source element of the header meta the pipeline already carries: inv_inc_tree_extend_single stamps "gnfi3" and increment_ytables_base_table stamps "ytable". The repeated survey sets no source – it is the reference case and keeps its file name unchanged, so PDFs and scripts that already exist do not shift.

Value

A length-one character: the sanitised method tag, or "" for the repeated survey (and whenever no source is recorded). Callers append it with a separator only when it is non-empty.

Reject inventory points without plot-centre coordinates

Description

Every concentric sample plot is built around its centre coordinate – the whole circle geometry (and every tree position derived from it) hangs off that one point. A plot whose centre coordinate is empty cannot be placed and must not travel into the pre files, where it would otherwise surface much later as a cryptic “missing values in coordinates not allowed” error from sf when the pre reader turns the centre into a geometry. Catching it here, at the raw->pre stage, turns that into a clear, early failure. Called after the coordinate columns have been parsed to numeric (so an empty cell is already NA). Shared by both concentric raw->pre converters so they stay symmetric.

Usage

.missing_coords_msg(points, x_col, y_col, id_col, filename)

Arguments

Value

NULL when every plot has both coordinates, otherwise a ready-to-emit error message naming the affected plots.

Null incomplete positions of innermost-circle trees (with an identifiable report)

Description

Innermost-circle trees (dbh below the second circle) need no position. A raw file may nonetheless give such a tree only PART of a position – a distance but no azimuth, or vice versa. A half-position is unusable and, left in place, makes ForestElementsR::fe_ccircle_spatial() build an NA geometry that sf rejects with “missing values in coordinates not allowed”, aborting the import. This nulls both components so the tree is treated as unpositioned (it stays in the evaluation – count / volume – but is not placed spatially), and returns an identifiable report of the affected trees. Trees that DO require a position were already handled by .drop_trees_without_coords, which is why only innermost trees remain here. Shared by both concentric raw->pre converters so they stay symmetric; make_object_lists() nulls the same case again as a safety net for pre files supplied directly (not produced by these converters).

Usage

.null_partial_positions(normalised_trees, second_circle_dbh_cm)

Arguments

Value

list(trees, msg): the tree data with incomplete positions nulled, and either NULL or a ready-to-emit warning message naming the affected trees.

Parse selected columns of a raw/pre import table as numbers

Description

Decimal-mark-tolerant numeric parsing for exactly the columns a reader actually consumes. Only the columns named in cols are touched (via .parse_numeric_vec); every other column is passed through unchanged. This is deliberately a whitelist: a raw or pre file that comes from outside may carry extra, optional, or free-text columns FeNEU does not use – those ride through untouched, and legitimate commas in text fields are never harmed (unlike the older df-global convert_numbers_with_commas).

Usage

.parse_numeric_cols(df, cols)

Arguments

Details

Column names in cols that are not present in df are silently skipped, so an optional numeric column that a given file happens to omit is no problem. Identifier columns (plot / stand / tree keys) must NOT be listed here: they are kept as character and guarded separately (see .assert_id_cols_integer()).

cols is expected to hold canonical column names, so the call belongs after any header normalisation / alias renaming has run. The canonical numeric-column sets are defined per format next to the alias maps in R/import_column_standards.R, so a format change is a single-file edit.

Value

df with the targeted character columns converted to numeric.

Parse one vector as numbers, tolerant of the decimal mark

Description

Locale-agnostic numeric parsing for a single column. Accepts both point decimals ("1.69") and German comma decimals ("1,69") as well as plain integers, so a file exported on a German-locale system and one exported on an English-locale system yield the same numbers. A value that already parses as a plain point-decimal number is taken as is; a pure comma-decimal value has its comma turned into a point and is then parsed. Empty strings and NA become NA.

Usage

.parse_numeric_vec(x, col_label = NULL)

Arguments

Details

Anything else – free text, a thousands separator, scientific notation, mixed punctuation – is returned as NA and reported with a warning: a measurement column should not contain such tokens, and turning them into NA silently would hide a data problem. A vector that is already numeric is returned unchanged.

Value

A numeric vector the same length as x.

Reject a duplicated plot identifier in the inventory-point file

Description

The plot-identifier column of the inventory-point file (koord in Format 2, plot_id in Format 1) must be unique – it is THE key that links a plot to its trees, its coordinates and its circle definition. A duplicate is never harmless: the pre reader nests each plot's circle definition by that key, so two rows sharing an id silently collapse into one plot carrying both circle sets, which only surfaces much later as the cryptic “dbh_lower is not unique” error. Catching it here, at the raw->pre stage, turns that into a clear, early failure. Shared by both concentric raw->pre converters so they stay symmetric.

Usage

.plot_id_duplicate_msg(points, id_col, filename)

Arguments

Value

NULL when the identifier is unique, otherwise a ready-to-emit error message naming the duplicated ids.

Read a delimited text file with automatic encoding detection

Description

The single entry point every raw/pre reader in this package uses to read a delimited text file, so that character encoding is handled uniformly and users never have to choose one. With encoding = "auto" (the default) the encoding is detected via .detect_file_encoding; any other value is passed through as an explicit override for pathological cases.

Usage

.read_delim_auto(
  file,
  delim = "\t",
  encoding = "auto",
  decimal_mark = ".",
  as_text = FALSE,
  ...
)

Arguments

Details

Project convention: do not call readr::read_delim() (or set a fixed locale(encoding = )) directly in a reader. Route every text-file read through this helper and expose an encoding = "auto" argument on the reader so the override is available. This keeps encoding handling in one place and consistent across all import functions.

Value

A tibble, as returned by readr::read_delim().

Sanitise a String for Use in a File Name

Description

Turns an arbitrary string - a user-supplied table title, a plot identifier, or a captured tree_filter expression - into a compact, file-name-safe token: runs of characters outside [A-Za-z0-9.] collapse to single underscores, and leading or trailing dots and underscores are trimmed.

Usage

.safe_filename_part(s, empty = "x")

Arguments

Details

Dots are kept inside the token on purpose, because plot identifiers are commonly dotted (900000002.1.99900002) and should stay recognisable in the file name. Only a leading dot is removed - it would make the rendered PDF a hidden file on unix-alikes - along with a trailing one, which Windows does not accept in a file name.

This is the single sanitiser used by all *_pdf() functions, so the rendered file names follow one convention across the table families.

Value

A length-one character, safe to embed in a file name.

Build the species-guessing mapping report

Description

Summarises how each raw species abbreviation was resolved during check_and_guess_species: one row per distinct (normalised) raw abbreviation with its tree count, the canonical abbreviation it maps to, the resulting species_id/name_ger, and a tier of either "confirmed" (exact or case-insensitive match) or "review" (resolved only by substring / fuzzy / mojibake matching, so worth a manual check). Rows are ordered review-first, then by descending tree count.

Usage

.species_map_report(work_raw, rev_map, species_table)

Arguments

Value

A tibble with columns raw, n_trees, canonical, species_id, name_ger, tier.

Derive Renderer Meta-Information from an Output Table

Description

Reads the self-describing attributes an output base/structure table carries (class_type and tree_selection, stamped by output_base_table / output_structure_table) and turns them into everything the *_pdf() functions need without a user-supplied type or layer_filter argument.

Usage

.table_pdf_meta(x, fn_name)

Arguments

Value

A list with type ("age"/"dq"), cohort (the raw tree-selection tag: "mainstand", "alllayers", or a raw tree_filter expression), and file_tag (the cohort in a file-name-safe form).

Compact per-tree identifier list for report messages

Description

When FeNEU excludes or alters individual trees (missing position, partial position, ...), the report must let the user find those trees in their OWN raw data. A per-plot identifier is not enough – a plot has many trees. This builds a compact, per-plot listing that names each affected tree by its tree number when the raw file supplied one (baumnummer / tree_nr, both optional under the grouping taxonomy) and otherwise by its dbh (cm) – so the trees stay identifiable even without tree numbers. The format is symbolic and language-neutral ("<plot>: <dbh>, <dbh>; <plot>: #<nr>(<dbh>)"); the surrounding message text explains it.

Usage

.tree_ident_label(trees, plot_col = "koord")

Arguments

Value

A single character string.

Warn When Structure Table Input Shows No Concentric-Circle Structure

Description

Structure tables break an inventory down by single-tree diameter class within age or dq classes. That is worth doing for a sample inventory, where the diameter distribution is estimated from a sample of trees; for a standwise inventory the same table can be computed but says much less. Nothing is refused here - the table is produced either way - the caller is only told what the data look like.

Usage

.warn_if_not_sample_inventory(inv_trees_plus, fn_name)

Arguments

Details

What can actually be observed is dbh_trshld: pull_trees fills that column with each tree's concentric-circle threshold if - and only if - the plot is an fe_ccircle_spatial, and leaves it NA otherwise. An all-NA column therefore means "no concentric-circle structure in these data", which today implies a standwise inventory but will not stay equivalent to it: a sample inventory taken by relascope would look exactly the same here while being a perfectly legitimate case. That is why this is a warning naming the observation, not a rule refusing a combination - the wording has to survive the day FeNEU supports more (type x method) pairs. Deciding it properly needs the inventory type declared on the fe_inventory object and carried down; that is a post-CRAN item recorded in CLAUDE.md. An attribute cannot do the carrying, incidentally - measured: group_by() plus ungroup() already drops one, and the aggregation code groups constantly.

Value

Invisibly TRUE; called for the warning it may raise.

Species-Group Overview From the Per-Cohort Yield-Table Increments

Description

Aggregates the cohort-level estimate (plot_agg_for_yt followed by apply_ytables) to one row per species group plus a total row. All volume figures are harvested volume under bark (Erntefestmeter ohne Rinde); the collective is the main stand, because yield-table species areas are only formed there.

Usage

.ytables_overview_from_cohorts(cohorts, plot_area_weight = TRUE, fe_inv = NULL)

Arguments

Value

A tibble with one row per species group, an optional is_no_main_stand_row, and a total row whose site_index is NA because the index scales differ between yield tables.

Calculate ha-wise Increments per Species Group and Age Class on Inventory Level

Description

Aggregates the plot level output of ha_inc_main_stand_age_class to the level of the whole inventory

Usage

agg_ha_inc_main_stand_age_class(x, plot_area_weight)

Arguments

Value

A data frame which is an aggregation of the input x to the inventory level

Aggregate Yield Table Increments From Plot Level to Inventory Level

Description

Aggregate Yield Table Increments From Plot Level to Inventory Level

Usage

agg_ha_yt_inc_main_stand_age_class(x, plot_area_weight)

Arguments

Value

A data frame (tibble) with the grouping variables species_group, and age_class. For each so-defined group the tibble provides the area/ha, the average site index, and the yield table average increments per year and ha.

Apply the Selected Yield Tables on Plot Level

Description

Apply the Selected Yield Tables on Plot Level

Usage

apply_ytables(x, ytable_selection)

Arguments

Value

An extended version of the input x, containing yield table names, site index, stocking level and yield table increments. The increment iv_hub_m3_ha_yr_yt is the table's unreduced periodic annual increment (pai_m3_ha_yr, Vorratsfestmeter mit Rinde), corrected by the stocking level and then reduced exactly once to harvested volume under bark (Erntefestmeter ohne Rinde) via v_red_harvest_ubark. The pre-reduced red_pai_m3_ha_yr is not used, because it is not guaranteed to be present in every yield table.

Create a Background Table for All Mean Diameter Class Based Evaluations From an Inventory Tree Data Frame

Description

Calculates the quadratic mean diameter on the nested levels of layer in species group in plot, attributes these values to categories which are the basis for further aggregation with other functions. The function was designed for producing often required information only once.

Usage

back_table_dclass(inv_trees_plus, d_q_interval = 10)

Arguments

Value

A data frame which reports for each plot, species group and layer the actual quadratic mean diameter and the d_q-class (as an ordered factor) it belongs to.

Examples

# The prepared tree list ships with the package; see
# ?data_ex3_trees_essentials for the chain that builds it.
data_ex3_sample_trees_essentials |>
  back_table_dclass()

Species Group Information Table by Age Class

Description

Inventory tree data are grouped by species group and age class. A data frame with group-wise aggregated inventory information is returned.

Usage

base_table_age_class(inv_trees_plus, tree_filter = !.data$removal)

Arguments

Value

A list containing four data frames. The first one, called detail contains the aggregated information by species group and age class. The second one, total is aggregated on species level, i.e. one level higher. These values are mostly sums, but not in all cases. Confidence intervals must be calculated differently and also n_plot in total will not always be the sum of the values in detail, as there might be plots which contain two layers with different d_q classes. The third data frame, all_species, holds the cross-species aggregation by age class (the body of the "Summe" block of the base table (Basistabelle)); the fourth, all_total, is the grand total across all species and all classes.

Attached attribute

The returned list carries a tree_selection attribute recording which tree cohort it represents: "mainstand" for the *_main_stand() functions, "alllayers" for the general functions called with their default tree_filter, or the raw tree_filter expression for a custom filter. output_base_table / output_structure_table carry this attribute through to their own output, where the *_pdf() renderers read it for a self-describing file name and the cohort disclaimer.

See Also

Other inventory tables: base_table_age_class_main_stand(), base_table_d_q_class(), base_table_d_q_class_main_stand(), output_base_table(), output_increment_overall(), output_structure_table(), structure_table_age_class(), structure_table_age_class_main_stand(), structure_table_d_q_class(), structure_table_d_q_class_main_stand()

Examples

# The prepared tree list ships with the package; see
# ?data_ex3_trees_essentials for the chain that builds it.
data_ex3_sample_trees_essentials |>
  base_table_age_class()

Species Group Information Table by Age Class For the Main Stand Cohort

Description

Species Group Information Table by Age Class For the Main Stand Cohort

Usage

base_table_age_class_main_stand(inv_trees_plus)

Arguments

Value

A list containing four data frames, similar as the output from base_table_age_class, however restricted to the main stand, but with information about the areas covered by species (sub-groups). The first data frame in the list, called detail contains the aggregated information by species group and age class. The second one, total is aggregated on species level, i.e. one level higher. These values are mostly sums, but not in all cases. Confidence intervals must be calculated differently. The third data frame, all_species, holds the cross-species aggregation by age class (the body of the "Summe" block of the base table (Basistabelle)); the fourth, all_total, is the grand total across all species and all classes.

Attached attribute

The returned list carries a tree_selection attribute recording which tree cohort it represents: "mainstand" for the *_main_stand() functions, "alllayers" for the general functions called with their default tree_filter, or the raw tree_filter expression for a custom filter. output_base_table / output_structure_table carry this attribute through to their own output, where the *_pdf() renderers read it for a self-describing file name and the cohort disclaimer.

See Also

Other inventory tables: base_table_age_class(), base_table_d_q_class(), base_table_d_q_class_main_stand(), output_base_table(), output_increment_overall(), output_structure_table(), structure_table_age_class(), structure_table_age_class_main_stand(), structure_table_d_q_class(), structure_table_d_q_class_main_stand()

Examples

# The prepared tree list ships with the package; see
# ?data_ex3_trees_essentials for the chain that builds it.
data_ex3_sample_trees_essentials |>
  base_table_age_class_main_stand()

Species Group Information Table by Mean Diameter Class

Description

Inventory tree data are grouped by species group and mean diameter class. A data frame with group-wise aggregated inventory information is returned.

Usage

base_table_d_q_class(inv_trees_plus, dclass_back, tree_filter = !.data$removal)

Arguments

Value

A list containing four data frames. The first one, called detail contains the aggregated information by species group and mean diameter class. The second data frame, total is aggregated on species level, i.e. one level higher. These values are mostly sums, but not in all cases. Confidence intervals must be calculated differently and also n_plot in total will not always be the sum of the values in detail, as there might be plots which contain two layers with different d_q classes. The third data frame, all_species, holds the cross-species aggregation by mean diameter class (the body of the "Summe" block of the base table (Basistabelle)); the fourth, all_total, is the grand total across all species and all classes.

Attached attribute

The returned list carries a tree_selection attribute recording which tree cohort it represents: "mainstand" for the *_main_stand() functions, "alllayers" for the general functions called with their default tree_filter, or the raw tree_filter expression for a custom filter. output_base_table / output_structure_table carry this attribute through to their own output, where the *_pdf() renderers read it for a self-describing file name and the cohort disclaimer.

See Also

Other inventory tables: base_table_age_class(), base_table_age_class_main_stand(), base_table_d_q_class_main_stand(), output_base_table(), output_increment_overall(), output_structure_table(), structure_table_age_class(), structure_table_age_class_main_stand(), structure_table_d_q_class(), structure_table_d_q_class_main_stand()

Examples

# The prepared tree list is shipped with the package: it is this inventory
# put through pull_trees() -> height_complete_inventory() ->
# fill_heights_back() -> pull_trees() -> trees_add_essentials(). See
# ?data_ex3_trees_essentials for that chain spelled out.
trees_with_heights <- data_ex3_sample_trees_essentials

peg_back_d <- back_table_dclass(trees_with_heights)

base_table_d_q_class(trees_with_heights, dclass_back = peg_back_d)

Species Group Information Table by Mean Diameter Class and Single Tree Diameter Class For the Main Stand Cohort

Description

Very similar aggregation table to the one produced by base_table_d_q_class, but restricted to to the main stand (layer_key == 1) only. It contains, however, estimates of areas covered by species (sub-)groups and ha-related values o these cohorts. Due the methodological dubiousness of species area calculations in mixed stands, this is only done for the main stand (comparably to how this was handled in the 3rd German National Forest Inventory).

Usage

base_table_d_q_class_main_stand(inv_trees_plus, dclass_back)

Arguments

Value

A list containing four data frames, similar as the output from base_table_d_q_class, however restricted to the main stand, but with information about the areas covered by species (sub-groups). The first data frame in the list, called detail contains the aggregated information by species group and mean diameter class. The second one, total is aggregated on species level, i.e. one level higher. These values are mostly sums, but not in all cases. Confidence intervals must be calculated differently. The third data frame, all_species, holds the cross-species aggregation by mean diameter class (the body of the "Summe" block of the base table (Basistabelle)); the fourth, all_total, is the grand total across all species and all classes.

Attached attribute

The returned list carries a tree_selection attribute recording which tree cohort it represents: "mainstand" for the *_main_stand() functions, "alllayers" for the general functions called with their default tree_filter, or the raw tree_filter expression for a custom filter. output_base_table / output_structure_table carry this attribute through to their own output, where the *_pdf() renderers read it for a self-describing file name and the cohort disclaimer.

See Also

Other inventory tables: base_table_age_class(), base_table_age_class_main_stand(), base_table_d_q_class(), output_base_table(), output_increment_overall(), output_structure_table(), structure_table_age_class(), structure_table_age_class_main_stand(), structure_table_d_q_class(), structure_table_d_q_class_main_stand()

Examples

# The prepared tree list is shipped with the package: it is this inventory
# put through pull_trees() -> height_complete_inventory() ->
# fill_heights_back() -> pull_trees() -> trees_add_essentials(). See
# ?data_ex3_trees_essentials for that chain spelled out.
trees_with_heights <- data_ex3_sample_trees_essentials

peg_back_d <- back_table_dclass(trees_with_heights)

base_table_d_q_class_main_stand(
  trees_with_heights, dclass_back = peg_back_d
)

Build fcbestku (standard BaySF layer definition)

Description

Returns the standard BaySF layer code table. This default is used whenever no external layers_filename is supplied to the orchestrator.

Usage

build_fcbestku()

Value

Data frame ready to be written as fcbestku.txt.

Build fdinvba from normalised tree data

Description

Build fdinvba from normalised tree data

Usage

build_fdinvba(normalised_trees)

Arguments

Value

Tibble ready to be written as fdinvba.txt.

Build fdinvbhd from normalised tree data

Description

Build fdinvbhd from normalised tree data

Usage

build_fdinvbhd(normalised_trees)

Arguments

Value

Tibble ready to be written as fdinvbhd.txt.

Build fdinvkrs from normalised inventory-point data

Description

Build fdinvkrs from normalised inventory-point data

Usage

build_fdinvkrs(normalised_points)

Arguments

Value

Tibble ready to be written as fdinvkrs.txt.

Build fdinvtot from normalised deadwood data

Description

Converts normalised deadwood measurements into the fdinvtot format used by the BaySF processing chain. Per BaySF instructions (Erstanlage 2024, §6.2.8), deadwood is always recorded on a fixed 500 m² circle (radius 12.62 m), independent of the live-tree concentric circles.

Usage

build_fdinvtot(normalised_deadwood, source = "inputmask")

Arguments

Details

Volume per piece is estimated with a half-cylinder approximation (form factor 0.5):

v_{ha} = 0.5 \cdot \pi \cdot \left(\frac{d_{cm}}{200}\right)^2 \cdot h_m \cdot n_{ha}

Two input sources are supported via the source argument:

"inputmask" (Eingabemaske / input mask app export) — normalised input must contain:

koord

Plot identifier.

lfd_tot

Sequential deadwood piece number within plot.

totholz_lage

Position code: "1" = standing, "2" = lying. Standing pieces cannot be distinguished as whole vs. partial stem, so all are mapped to totkat = 91.

totzer

Decomposition grade (integer 1–5).

totbag

Species group code; 4 (Nicht bestimmbar) is recoded to 0.

dm

Mid-diameter in mm (converted to cm internally).

hoehe

Length / height in dm (converted to m internally).

fe_nr, fe_period, bestkey, bestlfd

Administrative keys.

"concentric" (Kraus / concentric-circle survey) — normalised input must contain:

koord

Plot identifier.

lfd_tot

Sequential deadwood piece number within plot.

kategorie

Position code: 1 = stehend ganzer Stamm (totkat = 90), 2 = stehend Stammteil (totkat = 91), 3 = liegend (totkat = 92). Any other value is mapped to NA and filtered out.

grad

Decomposition grade (integer 1–3), mapped directly to totzer.

totbag

Species group code: 1 = Eiche, 2 = Nadelholz, 3 = Laubholz, 4 = nicht zuzuordnen (recoded to 0).

dm

Mid-diameter in cm (no conversion needed).

hoehe

Length / height in m (no conversion needed).

fe_nr, fe_period, bestkey, bestlfd

Administrative keys.

Value

Tibble ready to be written as fdinvtot.txt with columns fe_period, bestkey, bestlfd, koord, lfd_tot, totkat, totzer, totbag, dm (cm), hoehe (m), fe_nr, v_ha, n_ha.

Build fdvikrs (circle definitions)

Description

Returns the standard fdvikrs data frame. When circle_definitions is NULL (the default), a single circle class (fe_ikl = 1) is created from bhds_from and radiuses. When circle_definitions is supplied, it must be a data frame with columns fe_ikl, bhd_von, and radius, and multiple circle classes are created.

Usage

build_fdvikrs(bhds_from = NULL, radiuses = NULL, circle_definitions = NULL)

Arguments

Value

Data frame ready to be written as fdvikrs.txt.

Internal Helper Function for Calculating Tree Volumes at Sampling Thresholds

Description

Required for all tree-increment calculation options in tree_inc_repsurv, where sampling thresholds have to be taken into account.

Usage

calc_v_hub_m3_at_thrsh(
  tree_matches,
  inv_1st,
  inv_2nd,
  inv_1st_trees,
  inv_2nd_trees
)

Check and guess species names

Description

This is a convenience function that helps in the context of inconsistently coded German species name abbreviations. It tries to guess correct species names and connects them to species codes that are supported by the package ForestElementsR. Despite the function applies clever techniques, a manual check ot the outcome is absolutely recommended.

Usage

check_and_guess_species(tree_list, species_table)

Arguments

Details

Remark by Peter: The current version operates on data frames and requires column naming conventions. A future streamlined version can be more generic and based on named vectors.

Value

A duplicate-free data frame containing all successful matches

Check Circle Definition Compatibility of Matched Inventory Plots

Description

Internal helper called by match_2_inventories. For each matched plot pair, the circle definitions (columns dbh_lower and c_area) are compared. Pairs with incompatible circle definitions are removed from matches and stored in a new list element circle_def_mismatch. The comparison uses tolerances: dbh_lower is rounded to 1 decimal place (0.1 cm = 1 mm) and c_area is rounded to 5 decimal places (0.00001 ha = 0.1 m²). This accounts for potential rounding artifacts in the data while still detecting genuine differences in circle setup. Plots with empty circle definitions (notrees plots) are always considered compatible, because ingrowth and mortality are handled separately in the increment calculation.

Usage

check_circle_def_compatibility(match_rslt, inv_a, inv_b)

Arguments

Value

The input list match_rslt with an additional element circle_def_mismatch containing the incompatible plot pairs. These pairs are removed from matches.

Check R Package and System Dependencies for PDF Rendering

Description

Gate function called at the top of every ⁠*_pdf()⁠ function. Throws an informative error when rmarkdown, kableExtra, or pandoc is missing, so users get a clear install message rather than a cryptic backtrace from inside rmarkdown::render().

Usage

check_pdf_dependencies(fun_name)

Arguments

Value

NULL invisibly when all dependencies are present.

See Also

pdf_dependencies, diagnose_pdf_toolchain

Other pdf_output: output_base_table_pdf(), output_increment_base_table_pdf(), output_increment_overall_pdf(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), output_structure_table_pdf(), pdf_dependencies, plot_info_sheet_pdf()

Examples

# The gate every *_pdf() function calls first: silent when everything is in
# place, an informative error otherwise. Guarded here so that the example
# itself stays harmless on a machine without the toolchain.
if (requireNamespace("kableExtra", quietly = TRUE) &&
    rmarkdown::pandoc_available()) {
  check_pdf_dependencies("output_base_table_pdf")
}

Checks if Input Data Compise all Necessary Information According to the Bavarian State Forest standards

Description

Checks if Input Data Compise all Necessary Information According to the Bavarian State Forest standards

Usage

check_raw_data_BaySF(raw_data)

Arguments

Value

If the check fails, the function terminates with an error. If not, it returns a list of column name vectors that are required to build an intermediate inventory list with the function read_rawdata_BaySF

Check Compatibility of a Yield Table Selection With Given Data

Description

Check Compatibility of a Yield Table Selection With Given Data

Usage

check_ytable_selection_vs_data(inv_dat, ytable_selection)

Arguments

Value

A list comprising a flag called success (TRUE if check result ok, FALSE otherwise), and a character string called message that contains an error message in case the check is not successful

Convert numbers with commas to point format

Description

Helper function for handling input data generated on German systems.

Usage

convert_numbers_with_commas(df)

Arguments

Details

Remark by Peter: Operates on a data frame. Future versions could be more simple and generic by just taking one vector as the input; the current version would also replace correct commas in text fields. The vector-based version would be called from outside only for those columns of a data frame, that are intended to be numeric.

Value

A data frame similar to the input, however with all commas replaced by points and all colums converted to numeric if possible

Count inventory points by regeneration plants per point (long format)

Description

Usage

count_reg_points_by_plants_long(
  inv_dat_trees_ext_reg,
  mixture_per_plot,
  pulled_circles
)

Arguments

Details

Counts the number of inventory points ("Probkreise") by classes of plant numbers per point, analogous to the "Zahl der Probkreise nach Pflanzenzahl je Probekreis" block in L43.

For each mixture_class × species_group, the function:

1. approximates the counted plants (tree_count) per inventory point,

2. sums plants per point across all regeneration trees on that point,

3. assigns each point to a plant-number class (e.g. 0, 1-9, 10-19, ...),

4. counts how many points fall into each class.

An additional "total" block aggregates across all mixture classes per species.

Value

Tibble with one row per mixture_class × species_group × plant_count_class (plus an overall "total" block), containing:

mixture_class

Mixture block ("total" or specific mixture)

species_group

Species identifier

plant_count_class

Class of plants per point (character)

n_inv_points

Number of inventory points in this class

Example raw sample inventory tables (Format 1, 10 inventory points)

Description

Artificial but realistic raw forest inventory tables (tree, plot and regeneration) in FeNEU's raw data Format 1 for sample inventories with concentric circles. They describe an inventory of only ten inventory points. The Gauss-Krueger coordinates in the point table are random numbers and do not refer to any real location. Only the columns the Format-1 converter consumes are kept (see import_sample_concentric_format1_raw_to_pre).

Format

data_ex1_sample_raw_points

Plot table linked by plot_id.

data_ex1_sample_raw_trees

Tree table linked by plot_id.

data_ex1_sample_raw_smalltrees

Regeneration table linked by plot_id.

Source

Internal example data (artificial, Format 1)

See Also

Other example data: data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Example raw inventory tables in BaySF style (forestry-mask format, 10 inventory points)

Description

Artificial but realistic raw forest inventory tables (plot and tree data) in FeNEU's raw data format 2 for sample inventories. They describe an inventory in the style of the Bavarian State Forest Enterprise (BaySF), comprising only ten inventory points. Any stored coordinates are random numbers and do not refer to any real location.

Format

data_ex2_sample_raw_points

Plot table linked by koord.

data_ex2_sample_raw_trees

Tree table linked by koord.

Source

Internal example data (artificial, BaySF style)

See Also

Other example data: data_ex1_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Interim Increment Stages of the ex3 Inventory Pair

Description

The repeated-survey increment runs through several steps, each of them an exported function with its own help page. The first two steps are shipped here as ready-made objects, so that the examples of the later steps can start at their own subject instead of rebuilding the chain that leads up to it.

Usage

data_ex3_increment_matched

data_ex3_increment_fills

Format

data_ex3_increment_matched is a list of six elements: tree_increments (152 rows, 22 columns), plot_matches, match_plot_stats, match_tree_stats, inv_period and method ("rep_classic").

data_ex3_increment_fills is a list of five estimate data frames – fills_forward (31 rows), fills_backward (47), fills_backward_nomatch (0), fills_backward_implausible (1) and fills_backward_reptrees (56) – plus inv_period, plot_matches and method carried through from the matching.

An object of class list of length 6.

An object of class list of length 8.

Details

data_ex3_increment_matched is what matching the two surveys yields: the per-tree increments derived from the measured data of both surveys, together with the plot and tree matching statistics and the survey period.

data_ex3_increment_fills holds the GNFI 3 estimates that stand ready to fill the gaps the matching leaves – trees found in only one of the surveys, and trees whose match was flagged implausible. It is not a filled tree list: which of these estimates is actually used is decided one step later by inv_inc_tree_consolidate through its fill_option. Because it was built with include_reptrees = TRUE, it also carries estimates for trees measured in both surveys, which have no gap at all; fill_option = "all_estimates" needs those.

Interim data for examples and tests

These objects exist for the documentation and the test suite, not as a processing stage of their own. They are built in data-raw/data_ex3_increment_interim.R from the shipped ex3 inventory pair and its prepared tree lists (data_ex3_trees_essentials):

data_ex3_increment_matched <- inv_increment_repsurv_ccirc(
  data_ex3_previous_sample_fe_inventory,
  data_ex3_sample_fe_inventory,
  data_ex3_previous_sample_trees_essentials,
  data_ex3_sample_trees_essentials,
  match_type = "plot_id", plot_id_style = "baysf"
)

data_ex3_increment_fills <- inv_inc_fill_gaps_gnfi3(
  data_ex3_increment_matched,
  data_ex3_previous_sample_trees_essentials,
  data_ex3_sample_trees_essentials,
  include_reptrees = TRUE
)

Those are the settings the examples use throughout. An example that deliberately shows a different one – another increment method, matching by centre coordinates, or include_reptrees = FALSE – calls the function itself, because that difference is its subject. Whenever the increment chain changes, these objects have to be rebuilt with the script above, just like the prepared tree lists.

See Also

inv_increment_repsurv_ccirc and inv_inc_fill_gaps_gnfi3, the functions that produce them; inv_increment_repeated_survey, which runs the whole chain in one call and is what most users want.

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Examples

  # Start at the consolidation step, without rebuilding what precedes it
  inv_inc_tree_consolidate(
    data_ex3_increment_fills, fill_option = "standard"
  )

Example Inventory Data as an fe_inventory object (10 inventory points, earlier survey)

Description

Example Inventory Data as an fe_inventory object (10 inventory points, earlier survey)

Details

This fe_inventory object holds artificial but realistic inventory data in the style of the Bavarian State Forest Enterprise (BaySF). It comprises only ten inventory points and was generated with fe_inventory from tab-delimited text files. The stored Gauss-Krueger coordinates are random numbers and do not refer to any real location. It contains the same inventory points as data_ex3_sample_fe_inventory and represents the earlier of two successive surveys (used to demonstrate increment estimation).

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Example Inventory Data as an fe_inventory object (10 inventory points)

Description

Example Inventory Data as an fe_inventory object (10 inventory points)

Details

This fe_inventory object holds artificial but realistic inventory data in the style of the Bavarian State Forest Enterprise (BaySF). It comprises only ten inventory points and was generated with fe_inventory from tab-delimited text files. The stored Gauss-Krueger coordinates are random numbers and do not refer to any real location. Five of the ten inventory points carry small-tree records, five do not.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Prepared Tree Lists of the ex3 Inventory Pair

Description

The tree lists of the two ex3 surveys, ready for analysis: heights complete, volumes, standing areas and species groups added. They are shipped so that the increment examples can start from a prepared tree list instead of repeating the five-step preparation in every single @examples block.

Usage

data_ex3_sample_trees_essentials

data_ex3_previous_sample_trees_essentials

Format

Each a tibble with one row per tree and 23 columns, among them plot_id, tree_id, species_id, species_group, age_yr, dbh_cm, height_m, n_rep_ha, area_rep_ha, layer_key, removal, g_m2, v_hub_m3 and standing_area_m2. data_ex3_sample_trees_essentials has 139 rows (second survey), data_ex3_previous_sample_trees_essentials 112 (first survey).

An object of class tbl_df (inherits from tbl, data.frame) with 139 rows and 23 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 112 rows and 23 columns.

Details

These are not a fourth processing stage of the inventory taxonomy (raw -> pre -> fe_inventory, see data_examples_overview). They sit after the import, on the analysis side: an fe_inventory object carries the inventory, and pulling and preparing its trees is the first step of evaluating it.

How they were built

With the canonical chain, spelled out in data-raw/data_ex3_trees_essentials.R:

trees_with_heights <- inv |>
  pull_trees() |>
  height_complete_inventory()

inv |>
  fill_heights_back(trees_with_heights) |>
  pull_trees() |>
  trees_add_essentials(method = "BaySF")

The second pull_trees is what makes the chain canonical: fill_heights_back writes the estimated heights into the inventory object, so the re-pulled trees carry them in height_m and none of the estimation helper columns (h_est_m, d_q_cm, h_q_m) ride along. Folding h_est_m into height_m by hand instead gives the same increments but a tree list of a different shape – a difference that has caused real breakage, see inv_inc_tree_extend.

See Also

data_ex3_sample_fe_inventory and data_ex3_previous_sample_fe_inventory, the inventories they were pulled from; inv_increment_repeated_survey, the usual consumer.

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Examples

  # What the two objects are
  dim(data_ex3_sample_trees_essentials)
  dim(data_ex3_previous_sample_trees_essentials)
  names(data_ex3_sample_trees_essentials)

  # They are ready to use, no preparation needed. The usual consumer is
  # inv_increment_repeated_survey(); its help page runs the whole chain on
  # exactly this pair, so it is not repeated here.
  head(data_ex3_sample_trees_essentials[, c("plot_id", "species_id",
                                            "dbh_cm", "height_m", "v_hub_m3")])

Example Inventory Data as an fe_inventory object (earlier survey)

Description

Example Inventory Data as an fe_inventory object (earlier survey)

Details

This fe_inventory object holds artificial but realistic inventory data in the style of the Bavarian State Forest Enterprise (BaySF). It was generated with fe_inventory from tab-delimited text files. The stored Gauss-Krueger coordinates are random numbers and do not refer to any real location. It represents the earlier of two successive surveys and contains the same inventory points as data_ex4_sample_fe_inventory, except for three points that were newly established in the later survey; it therefore comprises 97 inventory points.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Example Inventory Data as an fe_inventory object (100 inventory points)

Description

Example Inventory Data as an fe_inventory object (100 inventory points)

Details

This fe_inventory object holds artificial but realistic inventory data in the style of the Bavarian State Forest Enterprise (BaySF). It comprises one hundred inventory points and was generated with fe_inventory from tab-delimited text files. The stored Gauss-Krueger coordinates are random numbers and do not refer to any real location.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Simulated Inventory Data for Generic Matching Tests (10 plots, first survey)

Description

Simulated Inventory Data for Generic Matching Tests (10 plots, first survey)

Details

This fe_inventory object was derived from a simulated forest enterprise (pure spruce, 400 stands, 5 ha each). It contains a 10-plot subsample selected for unique within-plot tree IDs. The original simulation tree IDs are used as lfd_bhd, making the BaySF tree ID (paste(lfd_satz, lfd_bhd)) a permanent identifier that is stable across inventories. This enables testing of tree_id_style = "generic" (ID-based matching) in inv_increment_repsurv_ccirc.

Seven of the ten plots have both vanished and ingrown trees; three plots have all trees surviving between surveys. The dataset represents the first survey (year 2020). See data_ex5_sample_fe_inventory for the second survey.

Generated by data-raw/simulated_inventory_generic_matching.R.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Simulated Inventory Data for Generic Matching Tests (10 plots, second survey)

Description

Simulated Inventory Data for Generic Matching Tests (10 plots, second survey)

Details

This fe_inventory object represents the second survey (year 2030) of the same 10 plots as data_ex5_previous_sample_fe_inventory. See that object's documentation for details on the data source and the permanent tree ID scheme used for testing tree_id_style = "generic" matching.

Generated by data-raw/simulated_inventory_generic_matching.R.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Stand-Wise Inventory as an fe_inventory object

Description

Stand-Wise Inventory as an fe_inventory object

Details

This fe_inventory object (fe_stand plots) was built via the two-stage import chain (import_standwise_relascope_format1_raw_to_pre + import_standwise_relascope_pre_to_fe_inventory) from the raw Silvarith-style example data shipped at system.file("extdata", "data_ex6_standwise_raw", package = "FeNEU"). It has two fictitious stands and carries no plot coordinates, as is typical for stand-wise inventories with angle-count (relascopic, “Winkelzählprobe”) surveys.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Stand-Wise Inventory as an fe_inventory object

Description

Stand-Wise Inventory as an fe_inventory object

Details

This fe_inventory object (fe_stand plots) was built with import_standwise_relascope_pre_to_fe_inventory from the pre-processed Silvarith-style example data shipped at system.file("extdata", "data_ex7_standwise_pre", package = "FeNEU"). It has two fictitious stands and carries no plot coordinates, , as is typical for stand-wise inventories with angle-count (relascopic, “Winkelzählprobe”) surveys.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

FeNEU Example Data

Description

FeNEU ships a set of small example inventories used throughout the documentation, examples and tests. They are fully anonymised and artificial: plot coordinates are randomised and all identifiers are re-assigned, so the data carry no reference to any real forest enterprise and must not be used to draw conclusions about one. The sets are named data_ex1_... to data_ex7_.... The data represent three different processing stages, and the inventory types currently supported by FeNEU.

Processing stages

An inventory passes through up to three stages in FeNEU, and each example is provided at whichever stages are useful for demonstration:

raw

The unprocessed input tables as delivered by the field recording software, before any standardisation. Bundled as text files under system.file("extdata", ...), which is what the ⁠*_raw_to_pre()⁠ functions read. For ex1 and ex2, the same tables are additionally bundled as ⁠data/⁠ tibbles (⁠data_ex1_*⁠, ⁠data_ex2_*⁠) so that they can be inspected without reading a file; the text files are generated from those tibbles (⁠data-raw/⁠), so the two cannot drift apart.

pre (preprocessed)

The intermediate, standardised form the ⁠*_pre_to_fe_inventory()⁠ step consumes – BaySF-style tab-delimited text files for the concentric sample type, or a canonical WZP_Daten.txt for the stand-wise type. Bundled as folders under system.file("extdata", ...).

fe_inventory

The ready-to-analyse fe_inventory object, bundled as a ⁠data/⁠ object.

Inventory types

FeNEU supports sample and stand-wise inventories. Currently, we cover sample inventories that follow a concentric circle design, and stand-wise inventories with several angle-count samples per stand. In the overview table below, we refer to these types as sample, and standwise.

sample (concentric circles)

Sample-point inventory on concentric circles. Two raw input formats exist for sample inventories, "Format 1" and "Format 2"; both feed the same preprocessed BaySF-style form. Scope is counted in inventory points.

standwise (angle-count / relascope)

Stand-wise inventory in which each stand is sampled with several relascope angle-count (Winkelzaehlprobe) points. Currently, only one raw data format is supported for standwise relascope inventories ("Format 1"); the raw and the preprocessed data follow the Silvarith-style. Scope is counted in stands; in the resulting object every angle-count point becomes one fe_stand row.

Sample circle geometry

The raw formats of the sample inventories do not carry the geometry of the concentric circles – it is part of the inventory design, not of the field records. It therefore has to be passed to the ⁠*_raw_to_pre()⁠ functions, through the arguments dbh_cm_from (the lower dbh threshold of each circle, in cm) and radiuses_m (the matching radii, in m). Getting it wrong scales the representation factors and hence every per-hectare figure, so the designs of the two raw example sets are stated here:

These are the designs of the inventories the anonymised examples were derived from; use them when running the raw import of ex1 or ex2. The sets bundled from the preprocessed stage onwards (ex3 to ex5) carry their circle definition in the data and need no such argument.

Overview

Datasets in each set

ex1 – sample, Format 1, raw

extdata folder data_ex1_sample_raw (Baumschicht.txt, Inv_punkt.txt, Verjuengung.txt); objects data_ex1_sample_raw_trees (133 rows), data_ex1_sample_raw_points (10), data_ex1_sample_raw_smalltrees (43). Circle design: dbh_cm_from = c(0, 12, 30, 48), radiuses_m = c(2.82, 5.64, 11.28, 17.84). A dead-wood table exists for developers only (deadwood import is deferred); it is not shipped with the package.

ex2 – sample, Format 2, raw

extdata folder data_ex2_sample_raw (⁠02_probekreis.txt⁠, ⁠01_root_entity.txt⁠); objects data_ex2_sample_raw_trees (177 rows), data_ex2_sample_raw_points (10). Circle design: dbh_cm_from = c(0, 12, 30), radiuses_m = c(2, 6.31, 12.62). A small-tree and a dead-wood table are not bundled yet (see note).

ex3 – sample, concentric

extdata folder data_ex3_sample_pre; objects data_ex3_sample_fe_inventory and data_ex3_previous_sample_fe_inventory (an earlier survey of the same points, for increment estimation).

ex4 – sample, concentric

extdata folder data_ex4_sample_pre; objects data_ex4_sample_fe_inventory and data_ex4_previous_sample_fe_inventory. Same design as ex3, larger.

ex5 – sample, concentric, simulated

extdata folders data_ex5_sample_pre and data_ex5_previous_sample_pre; objects data_ex5_sample_fe_inventory and data_ex5_previous_sample_fe_inventory. Carries permanent tree ids (tree_id_style = "generic").

ex6 – standwise, relascope

extdata folders data_ex6_standwise_raw and data_ex6_standwise_pre; object data_ex6_standwise_fe_inventory.

ex7 – standwise, relascope

extdata folder data_ex7_standwise_pre; object data_ex7_standwise_fe_inventory.

Derived test fixtures

A few further bundled objects are derived from ex3 and kept under their historical names; they are not part of the ex1–ex7 scheme and exist for regression testing: inc_sub10_rep_classic, inc_sub10_rep_mean, inc_sub10_rep_end, inc_sub10_rep_trans (increment reference results), processed_pulled_sub10, processed_heights_nfi_sub10 and processed_heights_bav_sub10 (intermediate tree-preparation results).

Note on the Format-2 example (ex2)

ex2 currently provides only the tree and inventory-point tables. A Format-2 dead-wood table (the "07" sheet) and a regeneration table are not bundled yet; they can be added later.

Stand register (Revierbuch)

Besides the raw -> pre -> fe_inventory chain, FeNEU offers a separate strand that produces a stand register (Revierbuch) from the inventory input data. It needs stand-level attributes that an fe_inventory object does not carry. For stand-wise inventories these are read from a metadata file with import_standwise_relascope_format1_metadata(); import_standwise_relascope_format1_stand_register_bundle() orchestrates trees and metadata for stand_register_pdf(). Set ex6 bundles such a metadata file (stand_metadata.txt) as an example; the three processing stages above never touch it.

See Also

The exported import functions that move an inventory between the stages illustrated by these example data:

• raw to pre: import_sample_concentric_format1_raw_to_pre(), import_sample_concentric_format2_raw_to_pre(), import_standwise_relascope_format1_raw_to_pre()

• pre to fe_inventory: import_sample_concentric_pre_to_fe_inventory(), import_standwise_relascope_pre_to_fe_inventory()

• the inventory-type-agnostic dispatcher for the pre to fe_inventory step: read_and_convert_data()

• the object constructor itself: fe_inventory()

• the stand register strand: import_standwise_relascope_format1_metadata(), import_standwise_relascope_format1_stand_register_bundle(), stand_register_pdf()

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Add Essential Information to Deadwood Data

Description

Adds representative plot area (from an fe_inventory object) and fixed L46 diameter classes to a deadwood tibble imported from BaySF fdinvtot. No further transformations are performed; volume and number per hectare are already provided in the raw file.

Usage

deadwood_add_essentials(deadwood_dat, inventory_plots)

Arguments

Value

Tibble identical to deadwood_dat but with two additional variables:

area_rep_ha

Representative area of the sample plot (ha)

dclass_46

L46 diameter class (I, II, III)

Detect and validate a uniform date format in a character vector

Description

Attempts to determine the date format used in a character vector containing date strings. A small set of expected formats is tested on a representative non-empty value, and strict round-trip validation is applied. Exactly one format must match; otherwise the function raises an error. This ensures that all imported date fields follow a single, unambiguous, and internally convertible format.

Usage

detect_date_format(date_string)

Arguments

Value

A single character string representing the detected date format. If no format or more than one format matches, an informative error is thrown.

Diagnose the PDF Rendering Toolchain

Description

Checks whether the tools required for rendering PDF reports (pandoc and a LaTeX distribution) are available on the current system, and prints a message for each missing component explaining how to install it.

Usage

diagnose_pdf_toolchain()

Value

Invisibly, a named logical list with elements pandoc and latex.

See Also

setup_pdf_toolchain

Examples

diagnose_pdf_toolchain()

Aggregated hq and dq values from Single Tree to Inventory Level by User Defined Grouping

Description

Workhorse function used to complete heights at inventory level

Usage

dq_hq_perclass(inv_trees_ext, ...)

Arguments

Value

A tibble containing the aggregated information for dq and hq

Generate a fe_ccircle_spatial Object From an Output Row of make_inventory_list

Description

Standard users do not need to call this function directly. Its typical usage is to apply it to each row of the output of make_inventory_list and to obtain a list of fe_ccircle_spatial objects this way. Data standard is Bavarian State Forest (BaySF) so far.

Usage

fe_ccircle_fromlist(
  x,
  trees_column_name,
  circles_column_name,
  center_coord_name,
  small_trees_name,
  height_method = c("NFI", "Bavaria")
)

Arguments

Value

an object of fe_ccircle_spatial

Internal CRS registry

Description

A named vector mapping short CRS keys used internally in FeNEU to EPSG codes. The registry defines the coordinate reference systems supported by inventory import and conversion functions.

Usage

fe_crs_registry

Details

Supported CRS keys:

lonlat

WGS84 geographic coordinates (EPSG:4326)

etrs89

ETRS89 geographic coordinates (EPSG:4258)

utm32

ETRS89 / UTM zone 32N (EPSG:25832)

utm33

ETRS89 / UTM zone 33N (EPSG:25833)

gk2

DHDN / Gauss-Krueger zone 2 (EPSG:31466)

gk3

DHDN / Gauss-Krueger zone 3 (EPSG:31467)

gk4

DHDN / Gauss-Krueger zone 4 (EPSG:31468)

gk5

DHDN / Gauss-Krueger zone 5 (EPSG:31469)

Standard Construction of an fe_inventory Object

Description

Standard Construction of an fe_inventory Object

Usage

fe_inventory(
  inventory_list,
  object_type = c("fe_stand", "fe_stand_spatial", "fe_ccircle_spatial")
)

Arguments

Value

If the information provided allows to construct a valid fe_inventory object, this object will be returned. The function will terminate with an error otherwise

Examples

  # fe_inventory() is the constructor at the end of the import pipeline. It
  # is normally reached through the public entry point read_and_convert_data(),
  # which builds the intermediate inventory list and calls fe_inventory()
  # internally.
  in_path <- system.file("extdata", "data_ex3_sample_pre", package = "FeNEU")
  read_and_convert_data(in_path, inventory_type = "sample_concentric",
                        coord_sys = "gk4")

Normalise plot center coordinates and attach CRS metadata

Description

Internal helper to standardise plot center coordinates and associate them with a coordinate reference system (CRS). The function resolves the CRS from a short key, applies Gauss-Krueger zone-prefix correction if required, and stores CRS information as attributes.

Usage

fe_normalise_coordinates(
  coordinate,
  coord_sys = coord_sys,
  epsg = NULL,
  x_col = "gauss_rw",
  y_col = "gauss_hw",
  coord_sys_declared = TRUE,
  check_envelope = TRUE
)

Arguments

Details

Supported CRS keys (Germany-focused):

lonlat

WGS84 geographic coordinates (EPSG:4326)

utm32

ETRS89 / UTM zone 32N (EPSG:25832)

utm33

ETRS89 / UTM zone 33N (EPSG:25833)

gk2

DHDN / Gauss-Krueger zone 2 (EPSG:31466)

gk3

DHDN / Gauss-Krueger zone 3 (EPSG:31467)

gk4

DHDN / Gauss-Krueger zone 4 (EPSG:31468)

gk5

DHDN / Gauss-Krueger zone 5 (EPSG:31469)

epsg

User-supplied EPSG code

For Gauss-Krueger systems, the function automatically checks whether the Rechtswert appears to be missing the zone prefix and adds it if necessary.

Value

The input data frame with unchanged structure, but with CRS metadata attached as attributes:

fe_crs

An sf::crs object

fe_coord_sys

Resolved CRS key

fe_coord_cols

Coordinate column names

Generate a fe_ccircle_spatial Object From an Output Row of make_inventory_list

Description

Standard users do not need to call this function directly. Its typical usage is to apply it to each row of the output of make_inventory_list and to obtain a list of fe_ccircle_spatial objects this way. Data standard is Bavarian State Forest (BaySF) so far.

Usage

fe_stand_fromlist(x, trees_column_name, height_method = c("NFI", "Bavaria"))

Arguments

Value

an object of fe_stand

Write Estimated Heights at Inventory Level Back Into the Original fe_inventory Object

Description

This procedure can be time consuming with large inventories, therefore parallel processing is used (see parameter free_cores).

Usage

fill_heights_back(
  inv_dat,
  pulled_est_height,
  small_trees = FALSE,
  .progress = TRUE,
  free_cores = 4
)

Arguments

Value

The input fe_inventory object with updated heights

Examples

# Estimate heights - only the pulled tree tibble is affected so far
suppressWarnings(
# Warnings come from an intentional species code casts - no problem here
  inventory_est_heights <- data_ex3_sample_fe_inventory |>
    pull_trees() |>
    height_complete_inventory(method = "NFI")
)

# Now write the heights back into the original object or, as in this case,
# an otherwise identical copy of it
peg_fe_inventory_updated <- fill_heights_back(
  data_ex3_sample_fe_inventory, inventory_est_heights
)

Generate a Circle-Definition File for a Concentric Sample Inventory

Description

Writes an fe_ikl-keyed circle-definition file (default Probekreisdefinition.txt) for the concentric sample import chain (import_sample_concentric_format1_raw_to_pre, import_sample_concentric_format2_raw_to_pre). The concentric importers require a circle definition; when a ready-made one is not at hand, this helper produces a uniform definition – the same set of concentric circles for every plot – written as a single fe_ikl = "ALL" group. (For multiple circle classes, write the file yourself with one integer fe_ikl per class and link each inventory point to its class via its own fe_ikl column.)

Usage

generate_circle_definition(
  output_dir,
  dbh_cm_from,
  radiuses_m,
  filename = "Probekreisdefinition"
)

Arguments

Details

There is deliberately no default geometry: the caller must supply dbh_cm_from and radiuses_m, because the evaluation results depend directly on the circle sizes. These parameter names match those of the concentric raw importers.

Value

The path of the written file (invisibly).

See Also

import_sample_concentric_format1_raw_to_pre, import_sample_concentric_format2_raw_to_pre

Examples

dir <- tempdir()
generate_circle_definition(
  dir,
  dbh_cm_from = c(0, 12, 30),
  radiuses_m  = c(2.82, 5.64, 12.62)
)

Survey Year of an Inventory Object

Description

Returns the unique survey year (time_yr) of an inventory object. At present a method is provided for fe_inventory, where uniformity of time_yr across all plots is guaranteed by the fe_inventory constructor; the method does a defensive check regardless.

Usage

get_inv_year(x, ...)

## S3 method for class 'fe_inventory'
get_inv_year(x, ...)

Arguments

Value

A single numeric value: the survey year.

Examples

  get_inv_year(data_ex3_sample_fe_inventory)

Calculate ha-wise Increments per Plot, Species Group, and Age Class

Description

The increments added to the output of plot_inc_gnfi_2012 here relate to virtual species (group) area shares. The calculation is only done for the main stand, because otherwise the species area shares will not make too much sense.

Usage

ha_inc_main_stand_age_class(x, data_filter = !.data$removal)

Arguments

Value

A data frame that is the input x with additional columns representing the species groups' area shares, absolute areas and the related increments per ha

Harmonize First Inventory for Repeated Survey Increment Calculation

Description

For matched plot pairs from two subsequent inventories, this function ensures that the slope values in the first inventory's circle definitions match those of the second inventory. This is important because differing slope assessments lead to different n_rep_ha values for the same tree in the same concentric circle, which can distort increment calculations and cause false circle-transition detections.

Usage

harmonize_inv_for_repsurv(inv_1st, inv_2nd, plot_matches)

Arguments

Details

The function modifies the circle_definition$slope of matched plots in inv_1st to the value found in the corresponding plot of inv_2nd. Missing (NA) slopes are treated as 0 (flat terrain). Plots where neither circle definition contains a slope column are skipped, as are plots with empty circle definitions (notrees plots). After the slope correction, n_rep_ha is recalculated for affected trees using n_rep_ha, and the modified plot objects are revalidated with validate_fe_ccircle_spatial.

After harmonization, the user should re-derive the tree data from the returned inventory object (e.g. via pull_trees |> height_complete_inventory |> trees_add_essentials).

Value

A modified copy of inv_1st where the slope values in matched plots have been set to the corresponding values from inv_2nd and n_rep_ha has been recalculated accordingly. Unmatched plots are returned unchanged.

See Also

Other increment: increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Other repeated inventory: inv_increment_repsurv_ccirc(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), reclassify_pseudo_ingrowth_ccirc()

Other inventory matches: match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc()

Examples

  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  plot_matches <- match_2_inventories(
    inv_a, inv_b, match_type = "plot_id", "baysf"
  )

  inv_a_harmonized <- harmonize_inv_for_repsurv(inv_a, inv_b, plot_matches)

Complete Heights for Non-Measured Trees in an Inventory

Description

Typically in an inventory, height measurements are done only for a part of the sampled trees. This function provides reasonable estimates for the missing heights.

Usage

height_complete_inventory(
  pulled_inventory,
  d_q_interval = 5,
  method = c("NFI", "Bavaria"),
  diagnostic = FALSE
)

Arguments

Details

The function first identifies quadratic mean diameter (dq) classes grouped by species group (i.e. fe_species_tum_wwk_short), and stand layer level for each plot. These classes are then applied to the whole inventory (i.e. omitting the grouping by plot), to calculate a dq value for each dq class, species group, and stand layer. From the height-measured trees a corresponding hq (quadratic mean height) is calculated. In case there are no height measured trees in a group, so that there is no data-based estimate of hq possible the function h_q_from_d_q is used as a fallback. In this case a warning is issued.
Both, hq and dq are the entry points for the subsequent individual tree height estimates which are based on the individual trees' dbh. Note that for the height estimation method "Bavaria" also an age must be given for each tree (usually the stand or stand layer age).
The estimation methods "NFI", and "Bavaria" use the standard height curve systems h_standard_gnfi3, and h_standard_bv, respectively.

Value

A tibble in the same format as the input pulled_inventory, but with the additional columns h_est_m, i.e. height estimates for every tree, species_group, d_q_cm, and h_q_m.

Examples

 # Pull tree data from an fe_inventory object
 pulled_inventory <- data_ex3_sample_fe_inventory |>
   pull_trees()

 # Use the NFI method. The h_q fallback warning is expected here where a
 # species x layer group has no measured height.
 suppressWarnings(
   height_complete_inventory(pulled_inventory, method = "NFI")
 )

 # ... and the Bavaria method on the same data
 suppressWarnings(
   height_complete_inventory(pulled_inventory, method = "Bavaria")
 )

Import BaySF-style named flat files (experimental preview of Format 3)

Description

Reads a folder that already contains BaySF-style named flat files (BHD.txt, Inventurpunkte.txt, SCH.txt) and re-shapes them into the standard BaySF intermediate output files (fdinvbhd.txt, fdinvba.txt, fdinvkrs.txt, fcbestku.txt, fdvikrs.txt). Unlike import_sample_concentric_format1_raw_to_pre() / import_sample_concentric_format2_raw_to_pre(), which convert field-collected raw data, this reader expects files that are already close to the BaySF target format.

Usage

import_data_BaySF_inraw(
  input_path,
  bhds_from = bhds_from,
  radiuses = radiuses,
  year = year
)

Arguments

Details

This is an early, experimental reader for a third, “BaySF-named” raw input format. It is not part of the public import API, carries no correctness or stability guarantee, and its interface may change. It will probably converge into the future import_sample_concentric_format_3_raw_to_pre.

Import BaySF-style deadwood inventory data

Description

Usage

import_deadwood_data_baysf(input_path)

Arguments

Details

Wrapper that reads BaySF-style deadwood inventory data from the text file fdinvtot.txt and converts the raw column names to the internal FeNEU / ForestElementsR naming convention used for deadwood processing. Deadwood import is not part of the first release and may change.

Value

A tibble with standardized deadwood variables (one row per deadwood object).

Convert raw sample inventory data (format 1) to preprocessed BaySF style data

Description

Reads format 1 raw sample inventory data collected with the concentric-circle method and writes the five standard BaySF-style intermediate files (fdinvbhd.txt, fdinvba.txt, fdinvkrs.txt, fcbestku.txt, fdvikrs.txt) into output_dir.

Usage

import_sample_concentric_format1_raw_to_pre(
  input_path,
  output_dir,
  treelist_filename = "Baumschicht.txt",
  inv_punkt_filename = "Inv_punkt.txt",
  small_trees_filename = NULL,
  circle_def_filename = NULL,
  species_guess = FALSE,
  dbh_cm_from = NULL,
  radiuses_m = NULL,
  coord_sys = NULL,
  inventory_year = NULL,
  encoding = "auto"
)

Arguments

Details

Column names in the source files are case-insensitive (converted to lower case internally). Both English canonical names and their German equivalents are accepted; the German alias is silently renamed to the English canonical before validation.

In its raw encoding, Format 1 records measurements in familiar units (DBH in cm, height in m), the tree position as a single azimuth angle (degrees) plus a distance (m), the stand layer directly as BaySF layer codes, and both living and dead trees. Format 2 encodes the same information differently (DBH in mm, a gon-or-degree back azimuth with a unit flag, its own layer code, living trees only); see import_sample_concentric_format2_raw_to_pre.

Stand age. Age in forest inventories always refers to the stand or stand layer, never to the individual tree, even though it is recorded redundantly in every tree row. It is optional: in structure-rich, uneven-aged stands – increasingly important in practice – a meaningful stand age often cannot be given. When the age is missing or incomplete, the analyses that group by age class are unavailable: base tables and structure tables by age class, and the age-class breakdown of increment from a repeated inventory – all of these can be run by mean-diameter (dq) class instead. Increment from yield tables and from the BWI3 (gnfi3) functions requires the age and is not possible without it. A warning is issued on import whenever the age is absent or has gaps, so an accidental omission can be noticed and corrected; users whose forest structure genuinely precludes a stand age can ignore it.

No height completion is performed here. Measured tree heights are carried through as given (missing heights stay NA); the converter only records which heights were measured (internal hmb flag) and normalises their unit where the raw format requires it. Estimating the missing heights is a deliberate, separate downstream step – pull_trees() |> height_complete_inventory() |> fill_heights_back() – so that measured and estimated heights are never silently mixed.

Value

A named list (the common raw-to-pre report): ok (logical), errors (character), warnings (character), paths (the written files, or NULL if !ok), species_mapping and needs_review. On success it writes fdinvbhd.txt, fdinvba.txt, fdinvkrs.txt, fcbestku.txt, and fdvikrs.txt into output_dir.

When species_guess = TRUE, species_mapping is a tibble with one row per raw species abbreviation (raw, n_trees, canonical, species_id, name_ger, tier). A tier of "confirmed" means an exact or case-insensitive match; "review" means the code was resolved only by substring / fuzzy / mojibake matching and is worth a manual check. needs_review is TRUE whenever any row is "review" (with a matching warning); both are NULL/FALSE when species_guess = FALSE.

Format 1 and Format 2

FeNEU currently supports two raw data formats for sample inventories with concentric circles. The two grew up in parallel with FeNEU itself and have no fundamental differences in content – they simply reflect different user preferences for how the data are exported. We call them “Format 1” and “Format 2”. This function reads Format 1; Format 2 is read by import_sample_concentric_format2_raw_to_pre. Both produce the same BaySF-style preprocessed files, so everything downstream is identical.

Examples

# Use example raw input data shipped with the package
# and write them to a temporary folder.

td <- tempdir()

# Write example tables under the recommended Format-1 file names
readr::write_delim(
  data_ex1_sample_raw_trees,
  file = file.path(td, "Baumschicht.txt"),
  delim = "\t"
)

readr::write_delim(
  data_ex1_sample_raw_points,
  file = file.path(td, "Inv_punkt.txt"),
  delim = "\t"
)

readr::write_delim(
  data_ex1_sample_raw_smalltrees,
  file = file.path(td, "Verjuengung.txt"),
  delim = "\t"
)

# Definition of concentric sample circles
dbh_cm_from <- c(0, 12, 30, 48)
radiuses_m  <- c(2.82, 5.64, 11.28, 17.84)

# Create BaySF-style intermediate files in a separate temporary folder
# (function is called for its side effects). output_dir is mandatory --
# the converter never picks a target folder itself.
out_dir <- file.path(tempdir(), "pre_ex1")
import_sample_concentric_format1_raw_to_pre(
  input_path = td,
  output_dir = out_dir,
  treelist_filename = "Baumschicht",
  inv_punkt_filename = "Inv_punkt",
  small_trees_filename = "Verjuengung",
  species_guess = TRUE,
  dbh_cm_from = dbh_cm_from,
  radiuses_m = radiuses_m,
  coord_sys = "gk4"
)

# Check that one of the output files was created
file.exists(file.path(out_dir, "fdinvbhd.txt"))

Convert raw sample inventory data (format 2) to preprocessed BaySF style data

Description

Reads format 2 raw sample inventory data collected with the concentric circle method and writes the standard preprocessed BaySF-style intermediate files (fdinvbhd.txt, fdinvba.txt, fdinvkrs.txt, fcbestku.txt, fdvikrs.txt) into output_dir.

Usage

import_sample_concentric_format2_raw_to_pre(
  input_path,
  output_dir,
  treelist_filename = "02_probekreis.txt",
  inv_punkt_filename = "01_root_entity.txt",
  circle_def_filename = NULL,
  species_guess = FALSE,
  dbh_cm_from = NULL,
  radiuses_m = NULL,
  coord_sys = NULL,
  inventory_year = NULL,
  encoding = "auto"
)

Arguments

Details

Format 2 defines nine source tables in total. This converter currently supports only the narrow core – two tables: the main tree list (02) and the inventory-point / coordinate table (01). Importers for the remaining tables are under construction: the tree-property data (03), regeneration incl. height classes (04-06, 08), and dead wood (07, 09) are not read yet. In particular, Format 2 has its own dedicated small-tree / regeneration format, for which a reader will be added in the future; until then no regeneration / small-tree records are produced, so this converter never yields the bhd == 0 tally rows that the BaySF-style pre-reader would otherwise split off into small trees.

In its raw encoding, Format 2 records DBH in mm and heights in dm, the tree position as a back azimuth given in gon or degrees (disambiguated by a unit flag) plus a distance in cm, its own stand-layer code (remapped to BaySF codes, see above), and living trees only. Format 1 encodes the same information differently (cm and m, a single degree azimuth, BaySF layer codes directly, living and dead trees); see import_sample_concentric_format1_raw_to_pre.

Stand age. Age in forest inventories always refers to the stand or stand layer, never to the individual tree, even though it is recorded redundantly in every tree row. It is optional: in structure-rich, uneven-aged stands – increasingly important in practice – a meaningful stand age often cannot be given. When the age is missing or incomplete, the analyses that group by age class are unavailable: base tables and structure tables by age class, and the age-class breakdown of increment from a repeated inventory – all of these can be run by mean-diameter (dq) class instead. Increment from yield tables and from the BWI3 (gnfi3) functions requires the age and is not possible without it. A warning is issued on import whenever the age is absent or has gaps, so an accidental omission can be noticed and corrected; users whose forest structure genuinely precludes a stand age can ignore it.

No height completion is performed here. Measured tree heights are carried through as given (missing heights stay NA); the converter only records which heights were measured (internal hmb flag) and normalises their unit where the raw format requires it (Format 2 stores heights in dm). Estimating the missing heights is a deliberate, separate downstream step – pull_trees() |> height_complete_inventory() |> fill_heights_back() – so that measured and estimated heights are never silently mixed.

Value

A named list (the common raw-to-pre report): ok (logical), errors (character), warnings (character), and paths (the written files, or NULL if !ok). On success it writes fdinvbhd.txt, fdinvba.txt, fdinvkrs.txt, fcbestku.txt, and fdvikrs.txt into output_dir.

Format 1 and Format 2

FeNEU currently supports two raw data formats for sample inventories with concentric circles. The two grew up in parallel with FeNEU itself and have no fundamental differences in content – they simply reflect different user preferences for how the data are exported. We call them “Format 1” and “Format 2”. This function reads Format 2; Format 1 is read by import_sample_concentric_format1_raw_to_pre. Both produce the same BaySF-style preprocessed files, so everything downstream is identical.

Stand-layer coding (bestku)

Format 2 codes the stand layer in the tree-list column bestku differently from the BaySF-style pre format and from Format 1. The converter therefore remaps the Format-2 codes onto the BaySF layer codes that the rest of the pipeline (the fcbestku table and the internal layer_key) expects:

Note in particular that the same number means different things in the two codings (e.g. Format-2 bestku = 4 is advance regeneration, whereas BaySF/Format-1 code 4 is residual stand). The main stand (code 1) is identical in both. Format 2's two sub-canopy layers (Zwischenschicht, Unterschicht) are both mapped to the single BaySF Unterstand, and Format 2's combined Ueberhaelter/Nachhiebsrest maps to Ueberhaelter.

Examples

# Use example raw input data shipped with the package
# and write them to a temporary folder under the default
# file names, so the converter can be called with its defaults.

td <- tempdir()

readr::write_delim(
  data_ex2_sample_raw_trees,
  file = file.path(td, "02_probekreis.txt"),
  delim = "\t"
)

readr::write_delim(
  data_ex2_sample_raw_points,
  file = file.path(td, "01_root_entity.txt"),
  delim = "\t"
)

# Definition of concentric sample circles
dbh_cm_from <- c(0, 12, 30)
radiuses_m  <- c(2., 6.31, 12.62)

# Create BaySF-style intermediate files in a separate temporary folder
# (function is called for its side effects; the file names default to the
# format's standard names "02_probekreis.txt" / "01_root_entity.txt").
# output_dir is mandatory -- the converter never picks a target itself.
# The example points carry their own srs (EPSG:4326), so no coord_sys is
# needed; inventory_year is passed because the native date_created is the
# ambiguous DD-MM-YY.
out_dir <- file.path(tempdir(), "pre_ex2")
import_sample_concentric_format2_raw_to_pre(
  input_path = td,
  output_dir = out_dir,
  dbh_cm_from = dbh_cm_from,
  radiuses_m = radiuses_m,
  inventory_year = 2025
)

# Check that one of the output files was created
file.exists(file.path(out_dir, "fdinvbhd.txt"))

Concentric Sample Inventory: Preprocessed Files to fe_inventory

Description

The pre-to-fe_inventory step of the concentric sample import chain. Reads a folder of preprocessed BaySF-style files (fdinvbhd.txt, fdinvba.txt, fdinvkrs.txt, fcbestku.txt, fdvikrs.txt) – produced by import_sample_concentric_format1_raw_to_pre / import_sample_concentric_format2_raw_to_pre, or supplied directly in that shape – and builds an fe_inventory of fe_ccircle_spatial plots.

Usage

import_sample_concentric_pre_to_fe_inventory(
  input_path,
  style = "baysf",
  coord_sys = NULL,
  check_envelope = TRUE,
  encoding = "auto"
)

Arguments

Details

Counterpart to import_standwise_relascope_pre_to_fe_inventory.

Building the inventory objects can take a while for large forest units (thousands of plots). Progress is reported through the progressr framework, one step per plot. By default nothing is shown; wrap the call to see a progress bar, and the same code drives a native Shiny progress bar inside shiny::withProgress() / progressr::withProgressShiny():

progressr::handlers("cli")
progressr::with_progress(
  inv <- import_sample_concentric_pre_to_fe_inventory(input_path)
)

No height completion is performed here either: the returned inventory carries the measured heights as they are (missing ones stay NA). Estimating them is a deliberate, separate downstream step – pull_trees() |> height_complete_inventory() |> fill_heights_back().

Value

An fe_inventory of fe_ccircle_spatial plots.

A note on the BaySF-style column names

The plot-centre coordinate columns are named gauss_rw/gauss_hw (Gauss-Krueger Rechtswert / Hochwert) for historical reasons, but modern BaySF exports store UTM32 (ETRS89 / UTM zone 32N) values in them – the “gauss” name is a legacy label, not a statement about the CRS (native files even carry a GAUSS_KZ zone field that no longer reflects the actual system). FeNEU therefore never infers the CRS from the column name: pre files it writes itself record the real CRS in a coord_sys column (self-describing, so no argument is needed here), while a genuine BaySF export has no such column and you must pass coord_sys explicitly – for current data that is almost always "utm32".

See Also

import_sample_concentric_format1_raw_to_pre, read_and_convert_data

Examples

# The bundled example pre carries a coord_sys column (utm32), so it is
# self-describing and needs no coord_sys argument.
inv_path <- system.file("extdata", "data_ex3_sample_pre",
                        package = "FeNEU")
inv <- import_sample_concentric_pre_to_fe_inventory(inv_path)
inv

Import Per-Stand Metadata Companion to Format 1 Standwise Inventory Data

Description

Reads a per-stand metadata file (default name Inventuraufnahmen.txt) coming with Format 1 standwise inventory data (Silvarith-style) and returns one tibble row per stand with canonical lower-case ASCII column names. This is the metadata companion used by import_standwise_relascope_format1_stand_register_bundle and produces a tibble suitable as the stand_data argument of stand_register_pdf.

Usage

import_standwise_relascope_format1_metadata(
  input_path,
  filename = "Inventuraufnahmen",
  encoding = "auto"
)

Arguments

Details

The source file's headers are very long and can contain special characters (Ø, slashes, parentheses, German umlauts), so columns are matched by position rather than by name — the file must have exactly 13 columns in the order shown below.

Canonical columns (in order):

bestand

Stand identifier (character, matches the WZP bestand column).

bestandesform

Stand-form classification (e.g. "Kie-Lä-Bu").

alter_mittel

Mean stand age in years.

nutzungsart

Management type code (e.g. "VJT", "LB").

bemerkung

Free-text remark (may be empty).

bestflaeche

Stand area in ha.

bestockungsgrad

Stocking degree (BG, dimensionless).

vorrat_efm_ha

Standing volume in efm D.o.R. per ha.

aufnahmeart

Survey type: 1 = VK, 2 = WZP, 4 = fest. PK, 5 = konz. PK.

zaehlbreite

Angle-count factor or max. circle area, as a string (e.g. "ZB 4,0").

n_stichproben

Number of sample plots in the stand.

stp_pro_ha

Plot density (STP / ha).

stdfehler_pct

Sampling error of standing volume in percent (numeric, parsed from strings like "24,4%").

Value

A tibble with one row per stand and the 13 canonical columns described above.

See Also

import_standwise_relascope_format1_stand_register_bundle, stand_register_pdf

Import a Stand-Wise Angle-Count Inventory: Silvarith-style Raw to Preprocessed

Description

The raw-to-pre step of the stand-wise relascope (“Winkelzählprobe” / angle-count) import chain. Reads a Silvarith-style raw tree file (EingabedatenGesamt.txt: German locale – decimal comma, umlaut headers, DD.MM.YYYY dates), validates it (collecting every problem rather than stopping at the first), and – if valid – writes the preprocessed WZP_Daten.txt (the canonical ASCII / decimal-point form) that import_standwise_relascope_pre_to_fe_inventory reads.

Usage

import_standwise_relascope_format1_raw_to_pre(
  input_path,
  output_dir,
  treelist_filename = "EingabedatenGesamt.txt",
  encoding = "auto"
)

Arguments

Details

This is the direct counterpart to import_sample_concentric_format1_raw_to_pre for concentric sample inventories: a single top-level converter that performs its own validation (“plausi”) internally and returns a collected report. There is no separately exported plausi function.

“Silvarith-style” describes the shape of the data. Silvarith is a stand-wise angle-count software; this importer targets its export layout without claiming exact or official compatibility. A user who already holds a WZP_Daten.txt – Silvarith also produces one directly, or it was made earlier by this function – skips this step and goes straight to import_standwise_relascope_pre_to_fe_inventory.

Required columns (after tolower() of the header):

stpnr

Plot number within the stand (integer).

lfdnrstp

Sequential record number within the plot; renamed to lfd_nr.

bestand

Stand identifier (character).

best.-fläche

Stand area in ha (decimal comma); renamed to bestflaeche.

zf

Angle-count factor; renamed to zaehlfaktor.

ba

Species code in BaySF coding; renamed to baumart.

alter

Age in years (integer).

schicht

Silvarith layer code in {0, 1, 2, 3}: 0 = main stand (Hauptschicht), 1 = harvest remnants (Nachhiebsreste), 2 = veterans (Ueberhaelter) – 1 and 2 both fall into the remnant/veteran layer – 3 = understorey (Unter-/Zwischenschicht). Mapped to fe_stand layer_key in import_standwise_relascope_pre_to_fe_inventory; Silvarith has no code for advance regeneration.

anz.

Tree count for this record; renamed to anzahl.

bhd

DBH in cm (decimal comma).

höhe

Height in m (decimal comma); renamed to hoehe.

stichtag

Survey date in DD.MM.YYYY format.

Collected checks: bhd non-negative; schicht in {0, 1, 2, 3}; stichtag parseable as %d.%m.%Y; hoehe > 50 m raises a (non-blocking) warning.

No height completion is performed here, and missing heights are not rejected: measured tree heights are carried through as given (missing ones stay NA). Estimating the missing heights is a deliberate, separate downstream step – pull_trees() |> height_complete_inventory() |> fill_heights_back() – so that measured and estimated heights are never silently mixed. (Angle-count surveys usually measure a height for every tallied tree, so missing heights are uncommon here, but they are tolerated.)

Value

A named list (the common raw-to-pre report):

ok

Logical. TRUE if the file passed validation and was written.

errors

Character vector of validation problems; empty if ok.

warnings

Character vector of non-blocking notices; may be non-empty even when ok.

paths

Character vector of written files, or NULL if !ok.

See Also

import_standwise_relascope_pre_to_fe_inventory, import_sample_concentric_format1_raw_to_pre

Examples

# The bundled example uses the canonical Silvarith export name
# "EingabedatenGesamt.txt" (the default of `treelist_filename`).
sil_dir <- system.file("extdata", "data_ex6_standwise_raw", package = "FeNEU")
out_dir <- tempdir()
result  <- import_standwise_relascope_format1_raw_to_pre(
  sil_dir, output_dir = out_dir
)
result$ok
result$paths

Import a Standwise Format 1 Data Bundle (Trees + Stand Metadata) Required For a Stand Register (Revierbuch)

Description

Convenience orchestrator that reads both, a raw standwise Format 1 input file, and its metadata companion (both Silvarith-style) for one forest management unit from a single folder and returns the two artefacts needed for a stand_register_pdf call:

• fe_inv — an fe_inventory of fe_stand objects, built from the Silvarith-style trees export via the two-stage relascope import chain (import_standwise_relascope_format1_raw_to_pre + import_standwise_relascope_pre_to_fe_inventory).

• stand_data — per-stand metadata read from Inventuraufnahmen.txt via import_standwise_relascope_format1_metadata.

Usage

import_standwise_relascope_format1_stand_register_bundle(
  input_path,
  treelist_filename = "EingabedatenGesamt",
  inventuraufnahmen_filename = "Inventuraufnahmen",
  encoding = "auto"
)

Arguments

Details

Cross-checks that every stand referenced in the inventory has a corresponding row in stand_data and emits a warning if any are missing (the inventory data is still returned in that case).

Value

A named list with elements fe_inv (an fe_inventory) and stand_data (a tibble).

See Also

import_standwise_relascope_format1_metadata, import_standwise_relascope_format1_raw_to_pre, stand_register_pdf

Stand-Wise Relascope Inventory: Preprocessed WZP_Daten.txt to fe_inventory

Description

The pre-to-fe_inventory step of the stand-wise relascope (“Winkelzählprobe” / angle-count) import chain. Reads the preprocessed WZP_Daten.txt – produced by import_standwise_relascope_format1_raw_to_pre, or a Silvarith-style WZP_Daten.txt supplied directly – and builds an fe_inventory of fe_stand plots.

Usage

import_standwise_relascope_pre_to_fe_inventory(
  input_path,
  style = "silvarith",
  encoding = "auto"
)

Arguments

Details

Counterpart to import_sample_concentric_pre_to_fe_inventory.

Building the inventory objects can take a while for large forest units (thousands of plots). Progress is reported through the progressr framework, one step per plot. By default nothing is shown; wrap the call to see a progress bar, and the same code drives a native Shiny progress bar inside shiny::withProgress() / progressr::withProgressShiny():

progressr::handlers("cli")
progressr::with_progress(
  inv <- import_standwise_relascope_pre_to_fe_inventory(input_path)
)

No height completion is performed here either, and missing heights are not rejected: the returned inventory carries the measured heights as they are (missing ones stay NA). Estimating them is a deliberate, separate downstream step – pull_trees() |> height_complete_inventory() |> fill_heights_back().

Value

An fe_inventory of fe_stand plots.

See Also

import_standwise_relascope_format1_raw_to_pre, read_and_convert_data

Examples

# Build a preprocessed WZP_Daten.txt from the bundled Silvarith-style example,
# then read it into an fe_inventory.
sil_dir <- system.file("extdata", "data_ex6_standwise_raw", package = "FeNEU")
out_dir <- tempdir()
import_standwise_relascope_format1_raw_to_pre(sil_dir, output_dir = out_dir)
inv <- import_standwise_relascope_pre_to_fe_inventory(out_dir)
inv

Reference Tree Increment Data for Automated Tests (sub_10, rep_classic)

Description

Reference Tree Increment Data for Automated Tests (sub_10, rep_classic)

Details

Provided for automated testing. Contains the tree_increments tibble produced by inv_increment_repsurv_ccirc with method "rep_classic", applied to data_ex3_previous_sample_fe_inventory (first survey) and data_ex3_sample_fe_inventory (second survey), with match_type = "plot_id" and plot_id_style = "baysf".

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_end, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Reference Tree Increment Data for Automated Tests (sub_10, rep_end)

Description

Reference Tree Increment Data for Automated Tests (sub_10, rep_end)

Details

Provided for automated testing. Contains the tree_increments tibble produced by inv_increment_repsurv_ccirc with method "rep_end". See inc_sub10_rep_classic for details on the input data.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_mean, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Reference Tree Increment Data for Automated Tests (sub_10, rep_mean)

Description

Reference Tree Increment Data for Automated Tests (sub_10, rep_mean)

Details

Provided for automated testing. Contains the tree_increments tibble produced by inv_increment_repsurv_ccirc with method "rep_mean". See inc_sub10_rep_classic for details on the input data.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_trans, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Reference Tree Increment Data for Automated Tests (sub_10, rep_trans)

Description

Reference Tree Increment Data for Automated Tests (sub_10, rep_trans)

Details

Provided for automated testing. Contains the tree_increments tibble produced by inv_increment_repsurv_ccirc with method "rep_trans". See inc_sub10_rep_classic for details on the input data.

See Also

Other example data: data_ex1_sample_raw, data_ex2_sample_raw, data_ex3_increment_interim, data_ex3_previous_sample_fe_inventory, data_ex3_sample_fe_inventory, data_ex3_trees_essentials, data_ex4_previous_sample_fe_inventory, data_ex4_sample_fe_inventory, data_ex5_previous_sample_fe_inventory, data_ex5_sample_fe_inventory, data_ex6_standwise_fe_inventory, data_ex7_standwise_fe_inventory, data_examples_overview, inc_sub10_rep_classic, inc_sub10_rep_end, inc_sub10_rep_mean, processed_heights_bav_sub10, processed_heights_nfi_sub10, processed_pulled_sub10

Inventory-Level Increment Base Table by Species Group and Age or Diameter Class

Description

Aggregates tree-level increments to the inventory level in the same four-element layout as the static base_table_age_class / base_table_d_q_class family, but for the annual volume increment (iv_hub_m3_ha_yr) instead of standing volume. It is the increment counterpart of the static base tables and the per-subunit breakdown analogue of inv_inc_big_overview_matches_only.

Usage

increment_base_table(
  tree_inc_extd,
  by_class = c("age", "dq"),
  tree_filter = TRUE
)

Arguments

Details

The function operates on the per-tree increment frame produced by inv_increment_repeated_survey (repeated survey) or inv_increment_gnfi3 (single inventory). Both carry the same per-tree contract, so the same base table is produced regardless of the increment's origin. Internally the trees are first aggregated to plot level with inv_inc_tree_2_plot, then area-weighted to the inventory level via the shared primitive se_area_weighted_grouped.

This is the “plain” aggregation: each plot contributes its single representation area (area_rep_ha); there is no split into virtual monospecific areas (that is the job of a separate _main_stand variant). The per-hectare values therefore relate to one hectare of total forest, and the per-ha denominator is the full area across all plots in the input. Because totals are linear in the per-plot values, the species rows of detail sum (in iv_m3_yr_total) to the matching all_species row, and total sums to all_total – the central sum-consistency invariant (confidence intervals are not additive and are computed independently per level).

Value

A list of four tibbles, mirroring the static base table family:

detail

One row per species group and class.

total

One row per species group, across all classes.

all_species

One row per class, across all species groups (the body of the “Summe” block).

all_total

One row, the grand total.

Each carries n_plot_class (the number of inventory points falling into the group), the annual increment as both an absolute total (iv_m3_yr_total) and per hectare of operation area (iv_m3_ha_yr) with their 95% confidence half-widths (ci95_*), and the counts n_iv_filled / n_iv_total (gnfi3-estimated vs. total tree increments in the group). The plain table carries no per-species area_ha (that is the main-stand variant's job). The list additionally carries a collective element (a list with kind, label, definition) describing the tree collective the table represents: "all_layers" for the default tree_filter, otherwise a "custom" collective reporting the filter. It is carried through to the output and PDF steps so the collective can be labelled without re-deriving it. A meta element carries the header meta attached by inv_inc_tree_extend (survey years, period, area, point count, Berechnungs-/Ergänzungsmethode), or NULL for a single-inventory source.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inv_b <- data_ex3_sample_fe_inventory

  # Prepare a single inventory's tree data (warnings/messages are ok here)
  inv_b_trees <- data_ex3_sample_trees_essentials

  # Single-inventory increment, then the inventory base table
  inc <- inv_increment_gnfi3(inv_b, inv_b_trees)
  bt  <- increment_base_table(inc, by_class = "age")
  bt$detail
  bt$all_total

Inventory-Level Main-Stand Increment Base Table With Virtual Species Areas

Description

Main-stand counterpart of increment_base_table: it restricts the aggregation to the main stand (layer_key == 1, standing trees) and expresses the per-hectare increment relative to the cohort's virtual monospecific area rather than to one hectare of total forest. This mirrors the static base_table_age_class_main_stand / base_table_d_q_class_main_stand family. As there, species areas are only formed for the main stand, because area shares of species in mixed multi-layer stands are methodologically dubious (the same stance the Third German National Forest Inventory took).

Usage

increment_base_table_main_stand(tree_inc_extd, by_class = c("age", "dq"))

Arguments

Details

The virtual areas are built exactly as on the static side: a per-plot correction factor normalises the plot's main-stand standing area to one hectare, and each cohort receives its standing-area share of the plot's representation area. Unlike the static side, the main stand here includes trees removed between the two inventories: their increment counts, and their (inv-1) standing area counts towards the ideal species area, so numerator and denominator span the same collective.

Because every tree that contributes increment also carries a positive standing area (removed trees at inv-1, surviving/ingrowth trees at inv-2), every group that appears has a positive ideal area – so the “species extinct but residual increment” edge case (division by a zero area) cannot arise. It also keeps strong species-share shifts (e.g. after a storm) from producing implausibly large per-ideal-hectare increments, because the removed area enters the denominator as well.

Value

A list of four tibbles (detail, total, all_species, all_total) like increment_base_table (with iv_m3_ha_yr and its CI over the whole operation area), additionally holding area_ha (the ideal monospecific species area) and iv_m3_ha_yr_virt (the increment per that ideal area, without a CI). Unlike the static main-stand base tables it deliberately carries no per-species area-share column (per_species): in the increment context the ideal area is that of a period collective (including removed trees), so a percentage share would be more misleading than informative. Like increment_base_table, the list also carries a collective element (here fixed to the "main_stand" collective, “Hauptbestand”) and a meta element with the header meta attached by inv_inc_tree_extend (NULL for a single-inventory source).

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inv_b <- data_ex3_sample_fe_inventory
  inv_b_trees <- data_ex3_sample_trees_essentials

  inc <- inv_increment_gnfi3(inv_b, inv_b_trees)
  bt  <- increment_base_table_main_stand(inc, by_class = "age")
  bt$detail
  bt$total

Main-Stand Yield-Table Increment Base Table by Species Group and Age or Diameter Class

Description

Yield-table (“Ertragstafel”) counterpart of increment_base_table_main_stand. It breaks the yield-table increment estimate down by species group and age or quadratic-mean-diameter class, for the main stand only, and returns the same four-element layout as the other increment base tables so it flows through output_increment_base_table and output_increment_base_table_pdf unchanged.

Usage

increment_ytables_base_table(
  inv_dat,
  ytable_selection,
  by_class = c("age", "dq"),
  plot_area_weight = TRUE,
  fe_inv = NULL
)

Arguments

Details

Yield tables are age-indexed and their increment is expressed per hectare of a (virtual) monospecific stand, so this table exists only for the main stand and always relates to ideal species areas – there is no “all layers” variant. Each species-group cohort on a plot receives its yield-table increment (see inv_increment_ytables), which is then aggregated to the inventory level. For by_class = "dq" the cohorts are grouped by their quadratic mean diameter class (one per plot x species group, as in back_table_dclass); the underlying per-cohort increment is still the age-indexed yield-table value.

The confidence-interval columns are absent by design: only the repeated- inventory method carries an empirical CI.

Value

A list of four tibbles (detail, total, all_species, all_total) plus a collective element (fixed to “Hauptbestand”), a meta element (marking the source as "ytable" so the PDF is titled “Ertragstafelschätzung”), and a ytables_used element (the yield tables actually used, carried through so the PDF can list them). Each table carries n_plot_class, iv_m3_yr_total, iv_m3_ha_yr (over the operation area), area_ha (ideal species area), and iv_m3_ha_yr_virt (increment per ideal area). The per-species levels (detail, total) additionally carry site_index (mean Ertragsklasse); it is omitted from the cross-species all_species / all_total block, where averaging a site index would be meaningless.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inc <- inv_increment_ytables(
    data_ex3_sample_fe_inventory, data_ex3_sample_trees_essentials,
    ytables_bavrn_state_var_1_feneu
  )

  # Both axes rest on the same estimate
  increment_ytables_base_table(inc, by_class = "age")$all_total
  increment_ytables_base_table(inc, by_class = "dq")$all_total

Inventory-Wide Increment Overview for a Repeated Survey, Combining Matched and Second-Only Plots

Description

Top-level wrapper that runs both inv_inc_big_overview_matches_only (for the plots that appear in both surveys) and inv_inc_big_overview_2nd_only (for the plots that only appear in the second survey, with a short-window backward gnfi3 estimate) and combines their results into one whole-enterprise view. Designed as the data source for user-facing summary tables of the whole forest enterprise.

Usage

inv_inc_big_overview(
  tree_inc_rep_gapfill,
  inv_1st_trees,
  inv_2nd_trees,
  inv_2nd,
  style = c("generic", "baysf"),
  inc_summaric,
  dt_2nd_only = -5
)

Arguments

Details

Output layout (the central design decision): three sub-overview slots that all keep the same internal shape ($overall + $by_species_group), plus the inv_period and method info passed through so downstream renderers can label survey years and the increment method without re-deriving them.

matches_only

Verbatim output of inv_inc_big_overview_matches_only.

second_only

Verbatim output of inv_inc_big_overview_2nd_only.

combined

Per-row addition of matches_only and second_only. One row per matched fill_option (combined_standard, combined_min_estimates, combined_all_estimates, combined_inc_summaric), each summing the matched fill_option result with the single gnfi3_backward second_only contribution. iv_m3_yr_total and area_total_ha are additive; iv_m3_ha_yr is the resulting ratio. Sum-consistency: each combined row's totals equal the corresponding matches_only row plus the second_only row.

inv_period

The same inv_period list element that is already carried by inv_increment_repsurv_ccirc and inv_inc_fill_gaps_gnfi3, with the two survey years and the period length.

method

The increment method used in the upstream inv_increment_repsurv_ccirc call (one of "rep_classic", "rep_mean", "rep_end", "rep_trans"); carried through so user-facing renderers can label the table accordingly.

CI95 in $combined: the ci95_* columns are kept for structural compatibility but are NA throughout. The second_only contribution carries no empirical CI by contract (see inv_inc_big_overview_2nd_only); an area-weighted pooling of variances with one variance unknown would require assumptions that we are not willing to make here. Users who need a CI on the combined value can fall back to the matches_only CI as a lower bound, and document the choice.

iv_by_groups in $combined is deliberately omitted. The matched side breaks down by id_able_tree × tree_status (categories that the second_only side does not share), so a mixed breakdown would have a heterogeneous schema. Users that need that detail should look at $matches_only$overall$iv_by_groups separately.

Value

A list with the three top-level slots described above.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  suppressWarnings(suppressMessages({
    inv_a_trees <- data_ex3_previous_sample_trees_essentials
    inv_b_trees <- data_ex3_sample_trees_essentials

    # Matching and gap filling are shipped ready-made for this pair
    inc_rep <- data_ex3_increment_matched
    inc_fl  <- data_ex3_increment_fills
    inc_sum <- inv_inc_summaric(
      inc_rep$tree_increments, inc_fl$fills_forward,
      inv_a_trees, inv_b_trees
    )
  }))

  bo <- inv_inc_big_overview(
    inc_fl, inv_a_trees, inv_b_trees, inv_b,
    style = "generic", inc_summaric = inc_sum
  )
  bo$combined$overall$iv_total

Inventory-Wide Increment Overview for Plots Only Present in the Second Inventory

Description

Counterpart to inv_inc_big_overview_matches_only for those plots that only appear in the second survey (typical case: sample extensions and newly established plots between two inventories). Their increment cannot be observed directly; it is estimated per tree by applying the third-German-NFI growth functions backwards over a short period (dt, default 5 years) and aggregating across plots with the same area-weighted machinery as in inv_inc_big_overview_matches_only.

Usage

inv_inc_big_overview_2nd_only(inc_repinv_fl, inv_2nd_trees, inv_2nd, dt = -5)

Arguments

Details

Why a short period and not the full inter-survey distance: on plots without a previous observation we do not know the mortality and removal history. A backward projection over ~10 years would attribute much of the standing volume to "still living" trees and miss the unknown fraction that would actually have died or been harvested in that span. Over a shorter window (~5 years) that bias stays small and the resulting per-year growth rate is a defensible estimate for the representative area of the second-only plots.

The output structure mirrors inv_inc_big_overview_matches_only so that the two can later be combined into one whole-enterprise table by the caller. There is, however, no fill_option dimension here: only one estimator is in play (backward gnfi3 over dt years). A single label "gnfi3_backward" is used in the fill_option column so that a row bind with the matched-plots output stays unambiguous.

Current scope and limitations (v1):

• Only living trees of the second inventory enter the estimate (filter !removal). Removal trees on second-only plots are ignored; their contribution to the period increment would need a separate mortality model and is left out for now.

• The estimate is therefore a "living-tree backward" growth quantity, not a full balance increment. Be careful when combining the per-ha results with the matched-plot inc_summaric reference value, which does include mortality.

• The ci95_* columns are present for structural compatibility with inv_inc_big_overview_matches_only but contain NA throughout. All per-plot increments here come from a model (backward gnfi3 over a short window), not from empirical re-measurement; the only source of plot-to-plot scatter is then what the model itself produces on top of the actual tree sample. A confidence interval computed from that scatter would suggest a precision the underlying numbers do not have. Downstream code that merges this output with the matched-plots overview must therefore treat the 2nd-only CI columns as missing-on-purpose.

Value

A list with the same top-level structure as inv_inc_big_overview_matches_only: $overall (containing iv_by_groups, iv_total, v_total, n_plots) and $by_species_group (containing iv_by_groups, iv_total, v_total). All m3/ha values relate to the total area across all second-only plots, even when grouped by species; plots without trees of a given species_group contribute their area but a zero numerator, so sums of per-species values match the corresponding overall values.

If there are no second-only plots, an empty-shaped list is returned with zero rows in the tables and area_total_ha = 0 in n_plots; this lets downstream combination code merge the two overviews without special-casing.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  suppressWarnings(suppressMessages({
    # Matching and gap filling are shipped ready-made for this pair
    inc_rep <- data_ex3_increment_matched
    inc_fl  <- data_ex3_increment_fills
  }))

  bo_2nd <- inv_inc_big_overview_2nd_only(inc_fl, inv_b_trees, inv_b)
  bo_2nd$overall$iv_total
  bo_2nd$by_species_group$iv_total

Inventory-Wide Increment Overview for the Matched Plots of a Repeated Survey

Description

Produces the area-weighted increment overview from those plots that appear in both inventories — i.e. the subset for which repeated tree-level measurements are available. The companion function inv_inc_big_overview_2nd_only covers the plots that only exist in the second survey (new establishments, sample extensions); the top-level inv_inc_big_overview_matches_only combines both.

Usage

inv_inc_big_overview_matches_only(
  tree_inc_rep_gapfill,
  inv_1st_trees,
  inv_2nd_trees,
  inv_2nd,
  style = c("generic", "baysf"),
  inc_summaric
)

Arguments

Value

A list with three top-level elements:

overall

A sub-list with

iv_by_groups

Increments aggregated by fill_option, tree identification status, and tree status category

iv_total

Total increments per fill_option, plus an additional row "inc_summaric" with the summaric (yield-history) increment as the most reliable reference value

v_total

Total standing volume at the second inventory

n_plots

Number of plots and total represented area

by_species_group

A sub-list with the same structure as overall (minus n_plots, which would be redundant), but every tibble is additionally grouped by species_group. The total area (area_total_ha) stays at the area across all plots, so that plots without trees of a given species group still contribute their area to the denominator. Consequently, sums of per-species values (iv_m3_yr_total, iv_m3_ha_yr, v_hub_m3_ha) across species groups match the corresponding overall values, and the same applies row by row to the appended "inc_summaric" entries.

method

The increment method used in the upstream inv_increment_repsurv_ccirc call (carried through inv_inc_fill_gaps_gnfi3).

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # Matching and gap filling for this pair are shipped ready-made, see
  # ?data_ex3_increment_interim for how they were built
  inc_repinv    <- data_ex3_increment_matched
  inc_repinv_fl <- data_ex3_increment_fills

  # Compute the summaric increment per plot (required for big_overview).
  # Note: summaric reads matched_trees and fills_forward directly — it
  # does NOT go through the consolidate / extend per-tree pipeline,
  # so its balance always sees the full measured population.
  inc_sum <- inv_inc_summaric(
    inc_repinv$tree_increments, inc_repinv_fl$fills_forward,
    inv_a_trees, inv_b_trees
  )

  # Finally generate the matched-plots overview, use both styles
  inv_inc_big_overview_matches_only(
    inc_repinv_fl, inv_a_trees, inv_b_trees, inv_b,
    style = "generic", inc_summaric = inc_sum
  )
  inv_inc_big_overview_matches_only(
    inc_repinv_fl, inv_a_trees, inv_b_trees, inv_b,
    style = "baysf", inc_summaric = inc_sum
  )

Backward-Estimate Increments for Implausible Re-Measured Trees

Description

Called from within inv_inc_fill_gaps_gnfi3. Handles trees that were present in both inventories but flagged as implausible during tree matching (due to excessive volume shrinkage or species mismatch). These trees received a zero increment from the repeated measurement and need a model-based backward estimate. The second inventory's values are taken as ground truth and the increment is estimated backwards for the whole inventory period. The single tree increments are upscaled to an area of 1 ha.

Usage

inv_inc_fill_backward_implausible(tree_inc_rep, inv_2nd_trees)

Arguments

Value

The data frame tree_inc_rep$tree_increments filtered for implausible re-measured trees. It contains the two additional columns iv_hub_m3_ha_per_gnfi3, and iv_hub_m3_ha_yr_gnfi3 which represent the periodic and the mean annual backward estimates of their volume increment.

Backward-Estimate Increments for Trees That Were Measured in Both Inventories (Optional)

Description

Called from within inv_inc_fill_gaps_gnfi3. Covered are all trees that were present and matching in both inventories as long as they have no removal flag for the second inventory. In principle, there are no increment gaps to fill for these trees. However, it might be useful to compare estimates and real increments under certain circumstances. Note that the tree level increments are upscaled to an area of 1 ha. Hereby, we use the real representation numbers of each tree at the first and the second survey, i.e. we do not check whether the growth estimate crossed a representation threshold. Negative increments are possible and not wrong.

Usage

inv_inc_fill_backward_reptrees(tree_inc_rep, inv_2nd_trees, include_reptrees)

Arguments

Value

A data frame with the same structure as the output of the other fill-gap functions. However only if the parameter include_reptrees is set on TRUE, the backwards estimates will actually be calculated (which can take considerable time). Otherwise, the columns reserved for the estimates will be filled with NA values.

Backward-Estimate Increments for Trees that were Present in the Second of Two Subsequent Inventories

Description

Called from within inv_inc_fill_gaps_gnfi3. Takes into account only trees that have coordinates, but were only present in the second inventory. A backward estimate of the volume increment is done for the whole inventory period. The idea behind this approach: When crossing the diameter threshold of their circle between both inventories, these trees became eligible for survey, but they were actually growing for the whole inventory period. The single tree increments are upscaled to an area of 1 ha.

Usage

inv_inc_fill_gaps_backward(tree_inc_rep, inv_2nd_trees)

Arguments

Value

The data frame tree_inc_rep$tree_increments filtered for trees that are only existing in the second inventory. It contains the two additional columns iv_hub_m3_ha_per_gnfi3, and iv_hub_m3_ha_yr_gnfi3 which represent the periodic and the mean annualbackward estimates of their volume increment.

Backward-Estimate Increments for Trees That Cannot Be Matched Across Inventories

Description

Called from within inv_inc_fill_gaps_gnfi3. Takes into account only trees from the second inventory that cannot be matched across inventories due to the implemented survey system. Typically, such trees are below a certain dbh threshold and therefore not surveyed in a way that would make them uniquely identifyable. These trees obtain a backward estimate of their volume increment. The single tree increments are upscaled to an area of 1 ha.

Usage

inv_inc_fill_gaps_backward_nomatch(tree_inc_rep, inv_2nd_trees)

Arguments

Value

A data frame with the same structure as tree_inc_rep$tree_increments, however containg only trees that are not present in this data frame but present in the second inventory. These are trees that cannot be matched in subsequent inventories due to the survey system implemented. Therefore, increments from repeated inventories are not available for these trees. Consequently, the columns iv_hub_m3_ha_per_rep and iv_hub_m3_ha_yr_rep contain NA only. However, The columns iv_hub_m3_ha_per_gnfi3 and iv_hub_m3_ha_yr_gnfi3 contain backwards estimates of their volume increment.

Forward-Estimate Increments for Trees that were Present in the First of Two Subsequent Inventories

Description

Called from within inv_inc_fill_gaps_gnfi3. Takes into account only trees that have coordinates, but were only present in the first inventory, or present in the second inventory but with a removal flag. A forward estimate of the volume increment is done for half the inventory period, as such trees are assumed to have died or have been harvested at the middle of the period. The mean annual increment relates to the full inventory period as it has to represent the trees' contribution to the mean annual increment on the stand level. The single tree increments are upscaled to an area of 1 ha.

Usage

inv_inc_fill_gaps_forward(tree_inc_rep, inv_1st_trees)

Arguments

Value

The data frame tree_inc_rep$tree_increments filtered for trees that are only existing in the first inventory. It contains the two additional columns iv_hub_m3_ha_per_gnfi3, and iv_hub_m3_ha_yr_gnfi3 which represent the periodic and the mean annual forward estimates of their volume increment.

Close Tree Increment Gaps with Estimates from National Forest Inventory Functions

Description

When calculating tree level increments from two subsequent inventories, there are typically trees that were present in one of the inventories only. For different types of such trees, we apply here the single tree growth functions from the third German National Forest Inventory (Riedel et al. 2017) as implemented in the Package ForestElementsR, namely the functions d_age_gnfi3 and h_age_gnfi3.

Usage

inv_inc_fill_gaps_gnfi3(
  tree_inc_rep,
  inv_1st_trees,
  inv_2nd_trees,
  include_reptrees = TRUE
)

Arguments

Details

The increment estimates performed here are only applied to inventory plots that match in both inventories. This is guaranteed by requiring tree_inc_rep as input object. This is the output of inv_increment_repsurv_ccirc which ensures plot matching.

Value

A list comprising five data frames that have exactly the same structure, i.e. the same columns as tree_inc_rep$tree_increments, however with two additional columns,iv_hub_m3_per_gnfi3, and iv_hub_m3_yr_gnfi3). The data frame fills_forward relates to trees that were present in the first, but missing in the second inventory. Their increment is projected forward up to the mid of the period between both inventories. The second data frame fills_backward comprises trees that were present in the second, but not present in the first inventory. Their increment is estimated backwards for the whole period. The third data frame fills_backward_nomatch comprises trees present in the second inventory, which were, however, not recorded in a way that makes them identifyable in the first inventory (typically, such trees are under a certain dbh threshold). For such trees backward increment estimates are made for the whole period. The fourth data frame fills_backward_implausible comprises trees that were present in both inventories but flagged as implausible during tree matching (due to excessive volume shrinkage or species mismatch). These trees received a zero increment from the repeated measurement; their increment is estimated backwards from the second inventory's values for the whole period. The fifth data frame fills_backward_reptrees relates to plausible trees that were present in both inventories. While directly calculated increments are available for these trees, backward estimates are calculated if (include_reptrees) is TRUE. This might only be required under special circumstances, therefore, the default setting is FALSE for saving time. In the latter case, the columns reserved for the increment estimates are set to NA. In addition the list contains the elements inv_period (carried through from inv_increment_repsurv_ccirc), plot_matches (the plot match overview, also from inv_increment_repsurv_ccirc; downstream consumers such as inv_inc_big_overview_2nd_only use the in_b_only entry there to identify plots that only appear in the second inventory), and method (the increment method used in the upstream inv_increment_repsurv_ccirc call – one of "rep_classic", "rep_mean", "rep_end", "rep_trans").

References

Riedel T, Hennig P, Kroiher F, Polley H, Schmitz F, F. S (2017). Die dritte Bundeswaldinventur (BWI 2012). Inventur- und Auswertungsmethoden. Thuenen Institut fuer Waldoekosysteme.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # The matching this builds on is shipped ready-made for the pair, see
  # ?data_ex3_increment_interim
  inc_repinv <- data_ex3_increment_matched

  # Finally, fill the gaps. include_reptrees = FALSE estimates only where
  # there is a gap; the default TRUE also estimates for trees measured
  # twice, which is what fill_option = "all_estimates" later feeds on.
  inv_inc_fill_gaps_gnfi3(
    inc_repinv, inv_a_trees, inv_b_trees, include_reptrees = TRUE
  )

Compute the Summaric Increment per Plot, Overall and by Species Group

Description

Computes a pure balance increment per plot that does not require any tree matching assumptions. The formula is: inc_summaric = (V_end - V_start + V_removed) / period, where V_end is the total standing volume at the second inventory (excluding removed trees), V_start is the total standing volume at the first inventory, and V_removed is the forward-estimated volume of trees that were removed between inventories. The forward estimation relies on gnfi3-based estimates from the "standard" fill option, which is why the input must come from inv_inc_tree_consolidate with fill_option = "standard", extended by inv_inc_tree_extend.

Usage

inv_inc_summaric(matched_trees, fills_forward, inv_1st_trees, inv_2nd_trees)

Arguments

Details

The classical German forestry term for this quantity is "ertragsgeschichtlicher Zuwachs" (literally: yield-history increment). There is no established English equivalent; we use the term "summaric increment" here to express that this increment is derived purely from summary-level volume balances between two inventories, without relying on individual tree identity across surveys.

Methodological role. The ertragsgeschichtliche increment is the Goldstandard for the Betriebsebenen-Zuwachs — the best estimate of the enterprise-wide annual increment that two inventories can yield. Unlike the four single-tree methods (rep_classic, rep_mean, rep_end, rep_trans) it is a pure mass balance over the measured tree population; it does not depend on assumptions about which inventory's representation number to use for trees that change circles, and it does not need a per-tree pairing across inventories. For that reason it stands architecturally apart from the per-tree pipeline (inv_inc_tree_consolidate and inv_inc_tree_extend): summaric pulls its inputs (matched_trees, fills_forward, and the inv-trees lookups for species groups) directly, so its balance always sees the full measured population including the unmatchable inner-circle cohort — independent of any fill_option choice on the per-tree side.

Computational structure on each plot:

• v_hub_m3_ha_1st: sum of n_rep_ha_1st * v_hub_m3_1st over all inv-1 measurements present in matched_trees, including the rows flagged is_unmatchable_1st = TRUE (e.g. inner-circle trees recorded without polar coordinates).

• v_hub_m3_ha_2nd: sum of n_rep_ha_2nd * v_hub_m3_2nd over all living inv-2 measurements (no removal flag), including unmatchable inv-2 rows and the inv-2 records of pseudo-ingrowth- reclassified trees (the latter contribute only their inv-2 volume after the local undo described below).

• v_hub_m3_ha_aus: sum of n_rep_ha_1st * v_hub_m3_1st plus the half-period gnfi3 forward estimate, over the verified-ausscheider subset (tree_exists_1st is TRUE and either tree_exists_2nd is FALSE or the tree carries a removal flag at inv 2). The forward estimate is pulled from fills_forward. Unmatchable rows have NA on the counterpart side and are filtered out by NA-semantics so they never inflate v_aus.

Pseudo-ingrowth-reclassified trees have their reclassification locally undone inside summaric so that their inv-1 reconstruction (gnfi3 backward) does not enter the balance. They contribute only via their measured inv-2 volume — exactly the methodological treatment we want for the unmatchable inner-circle cohort.

Value

A list with two tibbles:

overall

One row per plot, columns plot_id, v_hub_m3_ha_1st, v_hub_m3_ha_2nd, v_hub_m3_ha_aus, inc_summaric_m3_ha_yr.

by_species_group

One row per (plot, species_group) combination, same volume / increment columns as overall plus species_group. Combinations where a species group is absent on a plot are not represented; consumers that need a complete grid (e.g. for area-weighted aggregation across all plots) must fill in zeros.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  # Pull and prepare tree data
  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # Matching and gap filling for this pair are shipped ready-made, see
  # ?data_ex3_increment_interim for how they were built
  inc_repinv    <- data_ex3_increment_matched
  inc_repinv_fl <- data_ex3_increment_fills

  # Summaric goes directly off matched_trees + fills_forward —
  # no consolidate / extend in between.
  inv_inc_summaric(
    inc_repinv$tree_increments,
    inc_repinv_fl$fills_forward,
    inv_a_trees, inv_b_trees
  )

Aggregate Single Tree Increments to ha-Values per Species Group, Age- or Diameter Class and Layer on Plot Level

Description

The ha-related values calculated here are to be understood as the contributions of each tree cohort (as defined by species group, (age- or diameter-) class, and layer) to the whole ha-wise increment of the plot. Importantly, they do not relate to virtual area shares of the cohorts. In an increment evaluation workflow, the intended use of this function is to be applied to the output of inv_inc_tree_extend

Usage

inv_inc_tree_2_plot(tree_inc_extd, by_class = c("age", "dq"))

Arguments

Value

A data frame with increment sums grouped by plot_id, species_group, d_q_class or age_class, layer_key, removal

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # Matching and gap filling for this pair are shipped ready-made, see
  # ?data_ex3_increment_interim for how they were built
  inc_repinv    <- data_ex3_increment_matched
  inc_repinv_fl <- data_ex3_increment_fills

  # Consolidate and extend tree increments
  inc_repinv_ce <- inv_inc_tree_consolidate(inc_repinv_fl) |>
    inv_inc_tree_extend(inv_a_trees, inv_b_trees, inv_b)

  # Finally, aggregate on plot level
  inv_inc_tree_2_plot(inc_repinv_ce, "age")
  inv_inc_tree_2_plot(inc_repinv_ce, "dq")

Consolidating a Mix of Real and Estimated Tree-Level Increments for Further Processing

Description

In an increment evaluation workflow, the intended use of this function is to be applied to the output of inv_inc_fill_gaps_gnfi3. In parallel to the increment values that were directly calculated, the latter has estimated the increment with the tree growth functions from the Third German National Forest Inventory (Riedel et al. 2017) for different cohorts of trees (in different ways, see inv_inc_fill_gaps_gnfi3). Here, the user decides which increments to use for which cohort in subsequent evaluations.

Usage

inv_inc_tree_consolidate(
  tree_inc_rep_gapfill,
  fill_option = c("standard", "min_estimates", "all_estimates")
)

Arguments

Details

The fill_option "standard" takes the inventory increment for all trees that can be potentially identified across inventories and are present at least in the second survey (i.e. re-measured or ingrown), as long as they do not have a removal flag at the second survey. For such trees that are, however, present in the first survey but are absent or have a removal flag at the second survey, an NFI based forward increment estimate for half the period between the surveys is used. Trees that cannot be identified across inventories and are present in the second survey, obtain a backwards increment estimate for the whole period. The option "min_estimates" uses NFI estimates only for trees that cannot be identified across surveys. Therefore, trees that only exist in the first survey obtain a zero increment. The third option "all_estimates" uses NFI based estimates for all trees.

Value

A data frame with every line representing a tree, actually all output components from inv_inc_fill_gaps_gnfi3 combined into one data frame. Importantly, there are three additional columns: iv_hub_m3_per and iv_hub_m3_yr are the periodic and annual increment values to continue calculating with (coming either from the inventory or from the estimate), and iv_filled is logical; if TRUE, the increment is estimated with the German NFI growth functions. If FALSE the increment is directly calculated from the survey data.

References

Riedel T, Hennig P, Kroiher F, Polley H, Schmitz F, F. S (2017). Die dritte Bundeswaldinventur (BWI 2012). Inventur- und Auswertungsmethoden. Thuenen Institut fuer Waldoekosysteme.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # Matching and gap filling for this pair are shipped ready-made, see
  # ?data_ex3_increment_interim for how they were built
  inc_repinv    <- data_ex3_increment_matched
  inc_repinv_fl <- data_ex3_increment_fills

  # Finally, consolidate the tree increments, try all fill options
  inv_inc_tree_consolidate(inc_repinv_fl, fill_option = "standard")

  inv_inc_tree_consolidate(inc_repinv_fl, fill_option = "min_estimates")

  inv_inc_tree_consolidate(inc_repinv_fl, fill_option = "all_estimates")

  # The option 'all_estimates' must throw an error if the gap filling was
  # not done for the trees which have dbh values in both surveys
  inc_repinv_fl <- inv_inc_fill_gaps_gnfi3(
    inc_repinv, inv_a_trees, inv_b_trees, include_reptrees = FALSE
  )
  try(
    inv_inc_tree_consolidate(inc_repinv_fl, fill_option = "all_estimates")
  )

Extend Tree-Level Increments With Detailed Tree Information, Especially Age and Mean Diameter Classes for Further Aggregation

Description

In an increment evaluation workflow, the intended use of this function is to be applied to the output of inv_inc_tree_consolidate

Usage

inv_inc_tree_extend(
  tree_inc_cons,
  inv_1st_trees,
  inv_2nd_trees,
  inv_2nd,
  d_q_interval = 10
)

Arguments

Value

A data frame where each row represents a tree, with extended information about increment and other tree level variables. The two columns time_yr_prev and time_yr_2nd are uniform across all rows and describe the survey years of the inventory pair (1st and 2nd survey, respectively); their difference is the inter-survey period. time_yr is the time of the tree's actual observation in the join partner inventory and equals time_yr_prev for trees that exist only in the first survey. The result also carries an "inc_meta" attribute (survey years, period, area, point count, Berechnungs-/Ergänzungsmethode) that the increment base tables promote into their header meta block.

Coverage – read this before aggregating

The result covers only the plots measured in both inventories. Plots that exist just in the second survey are not part of the repeated-survey matching and therefore absent here. Feeding this frame straight into increment_base_table or increment_base_table_main_stand understates every per-hectare figure, because those tables divide by the full operation area (from the "inc_meta" attribute) while the second-only plots contribute no increment – their area sits in the denominator with nothing in the numerator. Pass the result through inv_inc_tree_extend_combined first, or, simpler, use inv_increment_repeated_survey, which runs the whole chain including that step.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # Matching and gap filling for this pair are shipped ready-made, see
  # ?data_ex3_increment_interim for how they were built
  inc_repinv    <- data_ex3_increment_matched
  inc_repinv_fl <- data_ex3_increment_fills

  # Consolidate tree increments
  inc_repinv_cons <- inv_inc_tree_consolidate(inc_repinv_fl)

  # Extend with tree information required for further aggregation
  inv_inc_tree_extend(inc_repinv_cons, inv_a_trees, inv_b_trees, inv_b)

Fold Second-Only Plots Into the Repeated-Survey Tree-Level Increments

Description

Extends the per-tree increment frame of a repeated survey – the output of inv_inc_tree_extend, which covers only the plots measured in both inventories – with the plots that exist only in the second survey (new establishments, sample extensions). These second-only plots receive a short-window backward gnfi3 estimate via inv_inc_tree_extend_single (default dt = -5, the same convention as inv_inc_big_overview_2nd_only), and the two per-tree frames are row-bound into one.

Usage

inv_inc_tree_extend_combined(
  tree_inc_extd,
  inc_repinv_fl,
  inv_2nd_trees,
  dt = -5,
  d_q_interval = 10
)

Arguments

Details

The point of this function is the shared per-tree contract: both inv_inc_tree_extend and inv_inc_tree_extend_single emit the same columns consumed by inv_inc_tree_2_plot, so the combined frame runs through increment_base_table and increment_base_table_main_stand unchanged. The resulting base tables then cover the whole enterprise (matched plus second-only plots) instead of only the matched subset, so their per-hectare increment relates to the full operation area – consistent with the enterprise-level inv_inc_big_overview (where combined = matches_only + second_only).

Only living trees (!removal) of the second-only plots enter the estimate, mirroring inv_inc_big_overview_2nd_only: a plot without a predecessor survey has no between-inventory removals to capture, so a removal flag there marks a tree that is not part of the period's standing increment. The matched frame is left exactly as it is (it keeps its removed trees, whose increment is part of the period's production – the “Weg B” convention).

The header meta carried by tree_inc_extd already describes the whole enterprise (its area and point count come from the full second inventory passed to inv_inc_tree_extend), so it is simply re-attached to the combined frame (row-binding drops attributes).

Value

A per-tree increment data frame with the same contract as inv_inc_tree_extend, now spanning matched and second-only plots, carrying the (whole-enterprise) "inc_meta" attribute of tree_inc_extd. If there are no second-only plots (or none with living trees), tree_inc_extd is returned unchanged.

See Also

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_increment_gnfi3(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  # Identify two subsequent inventories
  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  suppressWarnings(suppressMessages({
    # Matching and gap filling are shipped ready-made for this pair
    inc_rep <- data_ex3_increment_matched
    inc_fl  <- data_ex3_increment_fills
    inc_extd <- inv_inc_tree_consolidate(inc_fl) |>
      inv_inc_tree_extend(inv_a_trees, inv_b_trees, inv_b)
  }))

  # Fold in the second-only plots -> whole-enterprise per-tree frame
  inc_extd_all <- inv_inc_tree_extend_combined(
    inc_extd, inc_fl, inv_b_trees
  )

  # Base tables now cover matched + second-only plots (run unchanged)
  increment_base_table(inc_extd_all, by_class = "age")$all_total

Extend Single-Inventory gnfi3 Tree Increments With Detailed Tree Information for Further Aggregation

Description

Single-inventory counterpart to inv_inc_tree_extend. Where the latter consolidates a repeated survey (with its match-based and gnfi3-filled increments) into the per-tree contract consumed by inv_inc_tree_2_plot, this function produces the very same contract for an inventory that was not repeated. Every tree increment is estimated with the Third German National Forest Inventory growth functions (Riedel et al. 2017) via tree_inc_gnfi_2012, so the resulting iv_filled column is uniformly TRUE.

Usage

inv_inc_tree_extend_single(
  inv_trees,
  dt = 5,
  d_q_interval = 10,
  inv = NULL,
  .caller = "inv_inc_tree_extend_single"
)

Arguments

Details

The point of this function is the shared seam: once the single-inventory source carries the same columns as the repeated-survey source, the downstream aggregation (inv_inc_tree_2_plot and everything built on top of it) is written and maintained only once, regardless of where the increment came from. The estimation method (gnfi3) is reflected in the per-tree _gnfi3 columns that ride along; the per-ha increment that the contract uses (iv_hub_m3_ha_yr) is the per-tree value scaled by n_rep_ha, clamped at zero (negative differences are improbable but possible near age 0).

The estimation direction lives in the sign of dt (see tree_inc_gnfi_2012). The default dt = 5 looks five years forward: for a single inventory the planning perspective is inherently forward-looking, so the increment of the coming years is the quantity of interest. The backward convention dt = -5 used by inv_inc_big_overview_2nd_only addresses a different situation – there the gnfi3 estimate stands in for a repeated survey, whose view is naturally backward (in the assumption that the recent past increment is a good proxy for the coming years). Either way a short window keeps the bias from the unknown future or past mortality and removal history small.

Value

A data frame where each row represents a tree, carrying the per-tree increment contract consumed by inv_inc_tree_2_plot: plot_id, species_group, age_class, d_q_class, layer_key, removal, standing_area_m2, n_rep_ha, area_rep_ha, the periodic and annual per-ha increments iv_hub_m3_ha_per / iv_hub_m3_ha_yr, and iv_filled (always TRUE here). The per-tree _gnfi3 estimation columns from tree_inc_gnfi_2012 are retained.

References

Riedel T, Hennig P, Kroiher F, Polley H, Schmitz F, F. S (2017). Die dritte Bundeswaldinventur (BWI 2012). Inventur- und Auswertungsmethoden. Thuenen Institut fuer Waldoekosysteme.

Estimate the Volume Increment of a Single Inventory With the BWI 3 Growth Functions

Description

Covers the whole chain from a prepared tree list to a ready-to-aggregate increment result, using the single-tree growth functions of the third German National Forest Inventory (Riedel et al. 2017). It is the single-inventory counterpart of inv_increment_repeated_survey: both return the same kind of object, so everything downstream – the increment base tables, the overview, and their PDF reports – is served in exactly the same way.

Usage

inv_increment_gnfi3(
  inv,
  inv_trees,
  dt = 5,
  d_q_interval = 10,
  keep_steps = FALSE
)

Arguments

Details

The increment is estimated per tree and for the whole population, not only for the collective that happens to be reported afterwards. Any collective can therefore be aggregated from the result: the main stand, all layers, or a selection of your own via the tree_filter argument of the base-table functions.

Because the estimate ages each tree by dt years, the age of every tree is required. If ages are missing, the function stops rather than silently evaluating the part of the population that happens to carry one.

Value

An object of class fe_increment_gnfi3, which inherits from fe_increment. A list with the elements

trees

the per-tree increments, covering all layers,

overview

the aggregation to inventory level, overall and by species group,

meta

the figures the reports print in their header,

steps

the intermediate results, or NULL (see keep_steps).

References

Riedel T, Hennig P, Kroiher F, Polley H, Schmitz F, F. S (2017). Die dritte Bundeswaldinventur (BWI 2012). Inventur- und Auswertungsmethoden. Thuenen Institut fuer Waldoekosysteme.

See Also

inv_increment_repeated_survey for the repeated-survey counterpart, increment_base_table and increment_base_table_main_stand for the class tables, output_increment_overview_gnfi3 for the species-group overview.

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_repeated_survey(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inc <- inv_increment_gnfi3(
    inv       = data_ex3_sample_fe_inventory,
    inv_trees = data_ex3_sample_trees_essentials
  )

  inc

  # Increment of the whole inventory, m3 per hectare and year
  inc$overview$overall$iv_total$iv_m3_ha_yr

  # Broken down by species group and age class
  increment_base_table(inc, by_class = "age")$all_total

Estimate the Volume Increment With the 3rd German National Forest Inventory Tree Growth Functions by Species and Age Class for a Whole Forest Inventory

Description

Uses the single tree growth functions developed for the third German National Forest Inventory (Riedel et al. 2017) as implemented in the package ForestElementsR, namely the functions d_age_gnfi3, and d_age_gnfi3

Usage

inv_increment_gnfi_2012(inv_dat, dt = 5, plot_area_weight = TRUE)

Arguments

Value

A data frame with ha-wise annual volume increments and virtual areas per species group and age class, for the main stand only and per virtual monospecific hectare

References

Riedel T, Hennig P, Kroiher F, Polley H, Schmitz F, F. S (2017). Die dritte Bundeswaldinventur (BWI 2012). Inventur- und Auswertungsmethoden. Thuenen Institut fuer Waldoekosysteme.

Increment From a Repeated Inventory – the Whole Chain in One Call

Description

Calculates the volume increment of a pair of subsequent inventories and returns everything the output functions need. This is the standard entry point for the repeated-survey increment (“Verfahren 1”): it runs the six-step chain inv_increment_repsurv_ccirc -> inv_inc_fill_gaps_gnfi3 -> inv_inc_tree_consolidate -> inv_inc_tree_extend -> inv_inc_tree_extend_combined -> inv_inc_big_overview in the right order, with the tree lists handed on where they are needed, so that callers do not have to reproduce it.

Usage

inv_increment_repeated_survey(
  inv_1st,
  inv_2nd,
  inv_1st_trees,
  inv_2nd_trees,
  method = c("rep_classic", "rep_mean", "rep_end", "rep_trans"),
  fill_option = c("standard", "min_estimates", "all_estimates"),
  match_type = c("plot_id", "center_coord"),
  plot_id_style = c("baysf", "generic"),
  tree_id_style = c("baysf", "generic"),
  inner_circle_non_matchable = FALSE,
  shrinkage_rate_per_decade = 0.1,
  species_check = c("species_group", "species", "warn_only"),
  clamp_plausible_shrinkage = TRUE,
  coord_tolerance = 10,
  include_reptrees = TRUE,
  include_second_only = TRUE,
  d_q_interval = 10,
  dt_second_only = -5,
  style = c("baysf", "generic"),
  progress_bar = TRUE,
  keep_steps = FALSE
)

Arguments

Details

The individual step functions stay exported and are the expert-level interface: use them when a single stage has to be inspected, varied or replaced. For everything else this function is the intended route, and it is the one whose result is guaranteed to be internally consistent.

Value

An object of class fe_increment_repsurv (which inherits from fe_increment), a list with

trees

The per-tree increment data frame covering the whole enterprise, carrying the "inc_meta" attribute. This is the input for increment_base_table and increment_base_table_main_stand.

overview

The enterprise-level aggregate, output of inv_inc_big_overview, input for output_increment_overall.

summaric

The summaric (ertragsgeschichtlicher) increment, output of inv_inc_summaric – the gold standard at enterprise level.

meta

The header meta (survey years, period, area, point count, calculation method, fill option).

steps

The intermediate results of the chain (tree_level, filled, consolidated, extended_matched) for inspection, or NULL – see keep_steps.

Which inventories are admissible

This is a sample inventory method and applies only to sample inventories in concentric circles (Stichprobeninventur, taxonomy axis sample x concentric). Both fe_inventory objects must consist entirely of fe_ccircle_spatial plots (its _notrees child included) – the tree matching relies on the plot geometry and the tree positions those objects carry. Stand-wise inventories (standwise x relascope, plain fe_stand plots) carry no tree positions and therefore have no repeated-survey increment; they are rejected with an error by inv_increment_repsurv_ccirc_check_input, which runs first. The two surveys must further be a genuine pair: the same enterprise, the first one earlier than the second, at least one year apart.

Whole-enterprise coverage

The per-tree result covers the whole enterprise, not just the plots measured twice. Plots that exist only in the second survey (new establishments, sample extensions) cannot have a repeated-survey increment by construction, so they receive a backward gnfi3 estimate via inv_inc_tree_extend_combined. This matters for more than completeness: the increment base tables express their per-hectare increment over the full operation area, so leaving these plots out would put their area into the denominator while their increment is missing from the numerator, and every per-hectare figure would come out too low. With them folded in, the base tables reproduce the enterprise level (inv_inc_big_overview's combined rows) exactly. Set include_second_only = FALSE only to reproduce the matched-plots-only view, and be aware of the bias just described.

Progress reporting

The chain reports its seven phases through the progressr framework. With the default progress_bar = TRUE the function displays a console bar itself, so an interactive user needs no ceremony. With progress_bar = FALSE it only signals progress and the caller decides what to do with it – notably a Shiny app, which wraps the call in progressr::withProgressShiny() and gets its own progress bar without FeNEU knowing anything about Shiny. Always pass progress_bar = FALSE when supplying a handler yourself, otherwise two handlers compete. The phase labels are translated (options(fe_lang = "de")).

The progress bars of the inner steps are switched off deliberately (inv_increment_repsurv_ccirc is called with progress_bar = FALSE): the tree matching would otherwise draw its own per-plot bar over the phase bar of this function. Progress is reported at this level only.

See Also

increment_base_table, increment_base_table_main_stand, output_increment_overall, output_increment_base_table_pdf

Other increment: harmonize_inv_for_repsurv(), increment_base_table(), increment_base_table_main_stand(), increment_ytables_base_table(), inv_inc_big_overview(), inv_inc_big_overview_2nd_only(), inv_inc_big_overview_matches_only(), inv_inc_fill_gaps_gnfi3(), inv_inc_summaric(), inv_inc_tree_2_plot(), inv_inc_tree_consolidate(), inv_inc_tree_extend(), inv_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repsurv_ccirc(), inv_increment_ytables(), is_fe_increment_repsurv(), match_2_inventories(), match_2_inventories_by_center_coord(), match_2_inventories_by_plot_id(), match_plot_statistics(), match_trees_on_inventory_repsurv_ccirc(), match_trees_on_plot_repsurv_ccirc(), output_increment_base_table(), output_increment_base_table_pdf(), output_increment_overall(), output_increment_overall_pdf(), output_increment_overview_gnfi3(), output_increment_overview_gnfi3_pdf(), output_increment_overview_ytables_pdf(), reclassify_pseudo_ingrowth_ccirc(), tree_inc_repsurv()

Examples

  inv_a <- data_ex3_previous_sample_fe_inventory
  inv_b <- data_ex3_sample_fe_inventory

  # The prepared tree lists ship with the package; how they were built with
  # the canonical chain is shown in ?data_ex3_trees_essentials
  inv_a_trees <- data_ex3_previous_sample_trees_essentials
  inv_b_trees <- data_ex3_sample_trees_essentials

  # The whole chain in one call
  suppressWarnings(suppressMessages({
    inc <- inv_increment_repeated_survey(
      inv_a, inv_b, inv_a_trees, inv_b_trees,
      method = "rep_classic", fill_option = "standard",
      progress_bar = FALSE
    )
  }))

  # Enterprise level, and the base tables built on the same object
  inc$overview$combined$overall$iv_total
  increment_base_table(inc, by_class = "age")$all_total

Calculate Tree-Wise Increments From Two Subsequent Inventories Based on Concentric Circle Plots With Spatial Information

Description

Main function to be used when calculating tree-level increments based on repeated inventories with concentric circle sample plots (fe_ccircle_spatial).

Usage

inv_increment_repsurv_ccirc(
  inv_1st,
  inv_2nd,
  inv_1st_trees,
  inv_2nd_trees,
  match_type = c("plot_id", "center_coord"),
  plot_id_style = c("baysf", "generic"),
  tree_id_style = c("baysf", "generic"),
  method = c("rep_classic", "rep_mean", "rep_end", "rep_trans"),
  inner_circle_non_matchable = FALSE,
  shrinkage_rate_per_decade = 0.1,
  species_check = c("species_group", "species", "warn_only"),
  clamp_plausible_shrinkage = TRUE,
  coord_tolerance = 10,
  progress_bar = TRUE
)

Arguments