correct_alive: Correct Trees Life Status in a Forest Inventory
In EcoFoG/ForestData: Post-inventory processing of Forest Census datasets

Description Usage Arguments Details Value Examples

correct_alive spots unseen trees, adds corresponding lines and corrects their status.

correct_alive(
  data,
  id_col = ifelse(is.null(getOption("id_col")), "idTree", getOption("id_col")),
  time_col = ifelse(is.null(getOption("time_col")), "CensusYear",
    getOption("time_col")),
  status_col = ifelse(is.null(getOption("status_col")), "CodeAlive",
    getOption("status_col")),
  plot_col = ifelse(is.null(getOption("plot_col")), "Plot", getOption("plot_col")),
  byplot = TRUE,
  dead_confirmation_censuses = 2,
  use_size = FALSE,
  invariant_columns = c("Forest", "Family", "Genus", "Species", "binomial_name")
)

`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.
`id_col`	character, name of the column containing trees unique IDs.
`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.
`plot_col`	character, name of the column containing plot indices or names.
`byplot`	logical, indicating whether the function has to process the data by plot (TRUE)or for the whole dataset (FALSE).
`dead_confirmation_censuses`	integer, defaults to 2: number of consecutive censuses for which a tree is unseen that are needed to consider the tree as dead. NB: for the trees unseen during the dead_confirmation_censuses -1 last inventories, the status cannot be corrected, thus mortality rates should not be calculated for these censuses.
`use_size`	character, defaults to FALSE. Optional argument specifying whether to use measurement column (circumference or diameter) to create a vital status field in case it does not already exist. See Details.
`invariant_columns`	character vector, containing the name of the columns for which value remain constant for a given tree (for example species name or coordinates). When a row is added by the function correct_alive, values for invariant columns are taken from the value for other censuses. Defaults to null

Argument death_confirmation_censuses death_confirmation_censuses is an argument that comes from the Paracou forest plots' censusing protocol, in which tree death is stated with certainty only if unsighting happens for at least the two last censuses. This is because the temporal resolution -the frequency with which the plots are censused- is high enough to use this cross-verification rule in case of unsighting. This means that mortality rates cannot be calculated with certainty for the last census, and that is why this argument is also in compute_mortality and compute_rates functions. Please set this argument according to your protocol's resolution and exigencies.

use_size defaults to FALSE, and activates a specific internal function that creates a $status field in the dataset. If you use this option, make SURE that only LIVE trees are measured (with non-NA size) in your dataset's protocol. In several protocols, e.g. the Paracou Disturbance Experiment, dead trees are measured for the census when death is recorded. In this case, this option must not be activated, and the status field has to be created manually. If your data ALREADY contains a field indicating whether the tree is dead -0 or FALSE-, or alive -1 or TRUE-, please let use_size to its default value.

a data.frame containing the corrected data, with trees' corrected life statuses. 1 = alive, 0 = dead. NAs indicate that the tree was unseen and cannot be considered dead yet. The output does not necessarily have the same number of lines as the input. Lines are added when the trees were unseen then seen alive again, with all columns being set NA except trees' id, plot, census year, corrected status, and the columns specified in invariant_columns argument. Useless lines, with NA status before first sight alive, or after death statement, are suppressed.

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

#Take a look to its structure
str(example_census)

#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_status_corr <- suppressWarnings(correct_alive(example_census,
invariant_columns = c("Genus",
"Species",
"Family",
"Forest",
"binomial_name")))

#Correct it (full call)
example_status_corr <- suppressWarnings(correct_alive(example_census,
id_col = "idTree",
time_col = "CensusYear",
status_col = "CodeAlive",
plot_col = "Plot",
byplot = TRUE,
dead_confirmation_censuses = 2,
use_size = FALSE,
invariant_columns = c("Genus",
"Species",
"Family",
"Forest",
"binomial_name")))


str(example_status_corr)