correct_size: Correct Tree Size Measurements
In EcoFoG/ForestData: Post-inventory processing of Forest Census datasets

Description Usage Arguments Details Value Examples

This function provides corrections for tree size measurements in Forest Inventories. POM are to be given as an input, and POM shifts are accounted for by adjusting the after-shifts value translating the points to offest the observed size loss by: after_shift_size_corrected = after_shift_size_original + difference_before_after + expected_growth.

correct_size(
  data,
  size_col = getOption("size_col"),
  time_col = getOption("time_col"),
  status_col = "status_corr",
  species_col = "binomial_name",
  id_col = getOption("id_col"),
  POM_col = getOption("POM_col"),
  measure_type = getOption("measure_type"),
  positive_growth_threshold = 5,
  negative_growth_threshold = -2,
  default_POM = 1.3,
  pioneers = c("Cecropia", "Pourouma"),
  pioneers_treshold = 7.5,
  ignore_POM = FALSE
)

`data`	data.frame, containing forest inventories in the form of a long-format time series - one line corresponds to a measurement for one individual at a given census time.
`size_col`	character, name of the column corresponding to tree size (circumference or diameter) measurements .
`time_col`	character, name of the column containing census years.
`status_col`	character, name of the column corresponding to tree status: 0/FALSE for dead, 1/TRUE for alive.
`species_col`	character, name of th column containing full species names (or other taxonomic identification)
`id_col`	character, name of the column containing trees unique IDs.
`POM_col`	character, name of the column corresponding the Point Of Measurement (POM).
`measure_type`	character, partially matching “Circumference” or “Diameter”, indicating what is the type of the measurements.
`positive_growth_threshold`	positive numeric or integer, threshold over which an annual DIAMETER growth is considered abnormal (in cm). Defaults to 5 cm.
`negative_growth_threshold`	negative numeric or integer, threshold under which an absolute DIAMETER difference is considered abnormal. To be given in centimeters. Defaults to -2 cm. Note that this threshold is applied between two consecutive censuses, regardless of the time between them, as it assumes that a tree diameter cannot decrease more than this value, even over a long period.
`default_POM`	scalar numeric, default POM used in the dataset, in the same unit as the POM. When the value in POM_col is different from default_POM, the corrected size is given at default_POM . It defaults to 1.3 meters-according to current practice of measurement of diameter at breast height (DBH).
`pioneers`	character vector containing full species name (or other taxonomic identification)for which a specific positive growth threshold (used for instance for fast growing species for which the threshold to detect an abnormal growth is high).
`pioneers_treshold`	Positive DIAMETER growth limit to apply to pioneer species (specified in 'pioneers'), similar to . Expressed in centimeters. Defaults to 7.5 cm
`ignore_POM`	Logical, defaults to FALSE. If TRUE, POM shifts are not accounted for to explicitely correct the measurements altered by these events. To use with care and ONLY if POMs were not reported during the cnsuses. Important is to note that using POM data (even when confidence on it is rather low) is often better than selecting this option. The user is responsible for the possible anomalies generated by correcting without POM data and has the responsibility to ensure that the corrections are overall good by checking the growth trajectories for at least a suficient subset of trees, using display_corrected_trees().

Signification of the code_corr values (short): - p_incr: punctual increase corrected by inter- or extrapolation - p_decr: punctual decrease corrected by inter- or extrapolation - def_incr_rp: definitive increase (or positive shift) corrected by realigning the most recent series upon the previous one. - def_decr_rp: definitive decrease (or negative shift) corrected by realigning the most recent series upon the previous one. - def_incr_rl: definitive increase (or positive shift) corrected by realigning the previous series on the most recent - def_decr_rl: definitive decrease (or negative shift) corrected by realigning the previous series on the most recent

This is an adaptation from Camille Piponiot's original correction function. This version is primarily designed to explicitely account for POM shifts. If the POM were registered reliably, using it enables 1- to eliminate anomalies due to POM shifts (typically, abnormal decreases in size without return to "normal values") and 2- to detect cases that would not be detected with the applied thresholds.

The optional argument "ignore_POM" triggers the version of the algorithm designed for cases in which POM shifts have not been registered. This should not be used if the information is available.

This function automates a quite simple yet efficient detection method based on using meaningful thresholds to detect errors, and using linear inter- or extrapolation from neighboring points to correct anomalous values or missing measurements.

For example, the Paracou Disturbance Experiment database is corrected with the following rules:

- An annual diameter growth that exceeds 5cm / year between two censuses is considered abnormal.

- This applies to avery species except a handful of well-known pioneer trees that sometimes exhibit explosive growth rushes (e.g. Cecropia obtusa) in the first years following recruitment, and especially for disturbed forest plots.

- For these species, annual growths up to 8cm can be tolerated.

- An absolute diameter decrease of 2cm or more between two censuses is also considered abnormal.

- Anomalies can be separated into two categories: punctual error and permanent shift. The nuance relies on the existance of an event marking a "return to normal size trajectory".

- A punctual error is an abnormal increase or decrease in size, that is offset by a complementary decrease or increase in size. In certain cases, this offsetting decrease of increase may not come immediately after the first outlyer, for some reason (this has been observed in the base but not yet explained). To separate efficiently shifts from punctual errors, the algorithm search for the complementary diameter variation up to 2 censuses after the first anomaly. The values of code_corr corresponding to punctual increase or decrease are respectively p_incr and p_decr

- A shift is defined as an abnormal increase or decrease in diameter that is not compensated by neighboring measurements.

- In most cases, shifts are negative and ared due to changes in Point Of Measurement (POM). In Paracou, for hihly non-cylindric tree stems that cause difficulties to accurately measure diameter or circumference, the size is estimated and the information about this is reported in a "measurement code". Estimations can cause positive as well as negative shifts in the Paracou database.

- The changes in POM for the Paracou can be retrieved at least partially from the "measurement code" field. This seems to be the most accurate way to correct the dataset, even in the presence of unreported or falsely reported POM changes, because it eliminates a great part of detectable and undetectable negative shifts.

- Tree growth trajectories depend more on individual effect than species identity. Moreover, due to the abundances distribution in this super-diverse rainforest, species-specific growth patterns cannot be established in order to be used for the corrections. Thus, the available growth values, for the individuals to correct, are used in order to estimate growth or size expectations.

- Growth is auto-correlated on the temporal dimension in many cases, thus not all the measurement available for such individuals should be used to estimate the corrected values. The 4 nearest values, if available and not abnormal, are supposedly sufficient to estimate a "local mean growth rate".

Once detected, the correction is done according to the category of the anomaly:

- for punctual increases or decreases, new values are computed according to the 4 nearest non-NA and non-outlyer measurements (2 before the anomaly, 2 after),if existing. If values are available before and after the anomaly, the corrected circumference.s or diameter.s are linearly interpolated with a "local mean growth rate" computed from these values. If not, corrected values are extrapolated.

- For shifts, one of the two "series" of measurement have to be re-aligned upon the other. The criteria used to choose which series should be taken as a reference depend on whether the POM are explicitely accounted for in the correction, or not. If POM are not available, most of the shifts to correct are supposed to be due to POM changes, leading to the choice to systematically re-align the more recent series upon the older one in case of negative shift. If POM is available, and is reliable enough to allow eliminating most POM shifts, remaining negative shift have roughly the same chances to correspond to e.g. erroneous estimation on non-cylindric stems. In this case, the series having the highest number of values is supposed to be more reliable than the other, and if both series are of same length, the most recent is picked.

- The codes corresponding to shifts are composed of a first part that describes the shift (def_incr or def_decr for definitive increase or decrease respectively) and a suffix that describes the realignment (_rp or _rl for realigned with previous or last series, respectively)

The same data.frame with two additional columns: size_corr, containing corrected tree size measurements, and code_corr, containing codes that tag both corrections locations and type.

#Load the provided example dataset
data("example_census")

#Take a look to its structure
str(example_status_corr)



#Correct it (short version with column names set with prepare_forestdata)

prepare_forestdata(example_census,
plot_col="Plot",
id_col="idTree",
time_col="CensusYear",
status_col = "CodeAlive",
size_col="Circ",
measure_type = "C",
POM_col = "POM")

example_size_corr <- suppressWarnings(correct_size(example_status_corr,
species_col = "binomial_name",#tag pioneer
pioneers = c("Cecropia","Pourouma"),
pioneers_treshold = 7.5,
ignore_POM = FALSE))

str(example_size_corr)

#Correct it (full call)
example_size_corr <- suppressWarnings(correct_size(example_status_corr,
size_col = "Circ",
time_col = "CensusYear",
status_col = "status_corr",
species_col = "binomial_name",
id_col = "idTree",
POM_col = "POM",
measure_type ="C",
positive_growth_threshold = 5,
negative_growth_threshold = -2,
default_POM = 1.3,
pioneers = c("Cecropia","Pourouma"),
pioneers_treshold = 7.5,
ignore_POM = FALSE))