Package 'FeNEU'

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()

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()

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()

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)

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
)

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")
}

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

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

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

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

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

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

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

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()

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")

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
)

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)
)

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)

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)

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")
 )

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"))

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"))

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

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

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

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

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

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

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

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

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

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

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

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

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
  )

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
  )

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
  )

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")

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")
  )

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)

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

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

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

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

Details

Even though the volume increments are calculated on tree level here, they are upscaled to 1 ha. This is important, because otherwise the increment represented by trees that change their representation number per ha between both inventories cannot be calculated correctly. Trees present in the first survey only always get zero increment; such values can be replaced by model-based estimates in a subsequent step. The function allows to choose between four methods of increment calculation (parameter method):

• rep_classic: The volume increment, $iv$, of trees that are present in both inventories is calculated as $iv=n[2]\cdot v[2]-n[1] \cdot v[1]$, with $n$ and $v$ being the representation number per hectare and the volume of the tree at the first and the second survey, respectively. The volume increment of the ingrowth trees is $iv=n[2]*v[2]$, i.e. such trees contribute to the increment with their full volume. This method is equivalent to the classic stand level increment calculation (German "Ertragsgeschichtlicher Zuwachs"), however, some trees (and plots) may also have negative increments. This might look strange, but is fully valid from a statistical angle of view.

• rep_mean: The volume increment, $iv$, of trees that are present in both inventories is calculated as $iv=(n[2]+n[1])/2\cdot (v[2]-v[1])$, and the volume increment of ingrowth trees is calculated as $iv=n[2]*(v[2]-v_t)$, where $v_t$ is the tree's volume when it crossed the sampling threshold. This method is not compatible to the classic stand level increment calculation. Guarantees $iv>=0$ when clamp_plausible_shrinkage = TRUE.

• rep_end: The volume increment, $iv$, of trees that are present in both inventories is calculated as $iv=n[2]\cdot (v[2]-v[1])$, and the volume increment of ingrowth trees is calculated as $iv=n[2]*(v[2]-v_t)$, where $v_t$ is the tree's volume when it crossed the sampling threshold. This method is not compatible to the classic stand level increment calculation. Guarantees $iv>=0$ when clamp_plausible_shrinkage = TRUE.

• rep_trans: The volume increment, $iv$, of trees that are present in both inventories, and did not cross a sampling threshold, is calculated as $iv=n\cdot (v[2]-v[1])$, with $n=n[1]=n[2]$. For trees that crossed a sampling threshold, the calculation is $iv=n[2]\cdot (v[2]-v_t) + n[1]\cdot (v_t-v[1])$. The volume increment of ingrowth trees is calculated as $iv=n[2]*(v[2]-v_t)$, where $v_t$ is the tree's volume when it crossed the sampling threshold. This method is not compatible to the classic stand level increment calculation and always guarantees $iv>=0$ (negative volume differences are clamped to zero regardless of clamp_plausible_shrinkage).

Value

A list with six elements: i) tree_increments is a data frame that identifies all trees that were appropriate for increment calculation with their plot and tree id in both inventories, and contains their annual and periodic volume increment (in m³/ha under bark after harvest). Note that in case of decreasing representation numbers between both surveys, increments can be also become negative which is statistically correct. ii) plot_matches informs about the outcome of the required plot matching across both inventories. It is the output of match_2_inventories which is called internally. iii) match_plot_stats which gives an overview of the plot matching results in terms of plot numbers and representation areas (i.e. the output of an internal call to match_plot_statistics). iv) match_tree_stats provides similar overview statistics on tree level. v) inv_period is the output of inv_period, computed once here so downstream functions can access the survey years and the inter-survey period without having to carry the fe_inventory objects further. vi) method is the increment method that was used in this call (one of "rep_classic", "rep_mean", "rep_end", "rep_trans"); carried through so downstream consumers can label outputs accordingly.

Position in the workflow

This is the first of six steps that lead from a pair of inventories to the increment tables and their PDFs. Unless a single stage has to be inspected or varied, call inv_increment_repeated_survey instead: it runs the whole chain in one call, hands the tree lists on where they are needed, and – importantly – includes the plots that exist only in the second survey, which a hand-built chain easily forgets (see the coverage warning in inv_inc_tree_extend).

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_inc_tree_extend_combined(), inv_increment_gnfi3(), inv_increment_repeated_survey(), 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: harmonize_inv_for_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(), reclassify_pseudo_ingrowth_ccirc()

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

  # The two match types. "center_coord" pairs plots by their centres within
  # a tolerance, "plot_id" by their identifiers.
  inv_increment_repsurv_ccirc(
    inv_a, inv_b, inv_a_trees, inv_b_trees,
    match_type = "center_coord", coord_tolerance = 10,
    method = "rep_classic"
  )

  # The four methods differ only in how the increment of a single tree is
  # formed; "rep_classic" above and "rep_trans" here are the two that matter
  # in practice, "rep_mean" and "rep_end" are set the same way. See the
  # increment vignette for the formulae.
  inv_increment_repsurv_ccirc(
    inv_a, inv_b, inv_a_trees, inv_b_trees,
    match_type = "plot_id", plot_id_style = "baysf",
    method = "rep_trans"
  )

Description

Covers the whole chain from a prepared tree list to a ready-to-aggregate increment result. It is the yield-table counterpart of inv_increment_repeated_survey and inv_increment_gnfi3: all three return an object of class fe_increment, carry their report header in meta, and are consumed the same way.

Usage

inv_increment_ytables(
  inv,
  inv_trees,
  ytable_selection,
  plot_area_weight = TRUE
)

Arguments

Details

The symmetry stops where the method does. A yield-table increment is not estimated per tree but for a cohort: one species in the main stand of one inventory plot, on the ideal (virtual monospecific) area it occupies there. The estimate needs the cohort's age and its mean height, which give the site index; age and site index give the per-hectare increment of the yield table, which is then corrected by the stocking level (the cohort's basal area over the basal area the table expects). Consequently this bundle holds no per-tree increments, the method is confined to the main stand, and the class tables cannot be filtered to arbitrary collectives the way the per-tree strands can.

A cohort has one age and one quadratic mean diameter, so the class an evaluation is grouped by – age class or diameter class – is a label on the result, not part of the estimate. Both labels are carried, and increment_ytables_base_table groups by whichever is asked for without estimating anything again.

Value

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

cohorts

one row per inventory plot and species: age, quadratic mean diameter and height, ideal area, site index, stocking level and the annual increment. This is the estimate itself,

overview

the species-group overview of the whole inventory,

meta

the figures the reports print in their header,

ytables_used

the yield tables actually used, per species group,

collective

the collective descriptor, always the main stand.

See Also

increment_ytables_base_table for the class tables, output_increment_overview_ytables_pdf for the overview report, inv_increment_gnfi3 for the per-tree single-inventory counterpart.

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_repeated_survey(), inv_increment_repsurv_ccirc(), 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(
    inv       = data_ex3_sample_fe_inventory,
    inv_trees = data_ex3_sample_trees_essentials,
    ytable_selection = ytables_bavrn_state_var_1_feneu
  )

  inc

  inc$overview

Description

Convenience helper that extracts the survey years of two fe_inventory objects and returns them together with the resulting inter-survey period, after the same validation that inv_increment_repsurv_ccirc applies. Used by functions that combine two inventories so that downstream consumers (e.g. inv_inc_summaric) can access the period without having to carry the fe_inventory objects further.

Usage

inv_period(inv_1st, inv_2nd)

Arguments