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

Arguments

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

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.

Details

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.

Examples

#Load the provided example dataset data("example_census") #Take a look to its structure str(example_census)
#> 'data.frame': 25533 obs. of 12 variables: #> $ Forest : chr "Paracou:P6" "Paracou:P6" "Paracou:P6" "Paracou:P6" ... #> $ Plot : int 1 1 1 1 1 1 1 1 1 1 ... #> $ idTree : int 100621 100621 100621 100621 100621 100621 100621 100621 100621 100621 ... #> $ Family : chr "Euphorbiaceae" "Euphorbiaceae" "Euphorbiaceae" "Euphorbiaceae" ... #> $ Genus : chr "Sandwithia" "Sandwithia" "Sandwithia" "Sandwithia" ... #> $ Species : chr "guyanensis" "guyanensis" "guyanensis" "guyanensis" ... #> $ CensusYear : int 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 ... #> $ CodeAlive : logi TRUE TRUE TRUE TRUE TRUE TRUE ... #> $ CodeMeas : int 0 0 0 0 0 0 0 0 0 0 ... #> $ Circ : num 40 40 40 40.5 40.5 41.5 40.5 40.5 40.5 41 ... #> $ binomial_name: chr "Sandwithia_guyanensis" "Sandwithia_guyanensis" "Sandwithia_guyanensis" "Sandwithia_guyanensis" ... #> $ POM : num 1.3 1.3 1.3 1.3 1.3 1.3 1.3 1.3 1.3 1.3 ...
#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")))
#> | | | 0% | |=================================== | 50% | |======================================================================| 100%
#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")))
#> | | | 0% | |=================================== | 50% | |======================================================================| 100%
str(example_status_corr)
#> 'data.frame': 25634 obs. of 13 variables: #> $ Forest : chr "Paracou:P6" "Paracou:P6" "Paracou:P6" "Paracou:P6" ... #> $ Plot : int 1 1 1 1 1 1 1 1 1 1 ... #> $ idTree : int 100621 100621 100621 100621 100621 100621 100621 100621 100621 100621 ... #> $ Family : chr "Euphorbiaceae" "Euphorbiaceae" "Euphorbiaceae" "Euphorbiaceae" ... #> $ Genus : chr "Sandwithia" "Sandwithia" "Sandwithia" "Sandwithia" ... #> $ Species : chr "guyanensis" "guyanensis" "guyanensis" "guyanensis" ... #> $ CensusYear : int 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 ... #> $ CodeAlive : logi TRUE TRUE TRUE TRUE TRUE TRUE ... #> $ CodeMeas : int 0 0 0 0 0 0 0 0 0 0 ... #> $ Circ : num 40 40 40 40.5 40.5 41.5 40.5 40.5 40.5 41 ... #> $ binomial_name: chr "Sandwithia_guyanensis" "Sandwithia_guyanensis" "Sandwithia_guyanensis" "Sandwithia_guyanensis" ... #> $ POM : num 1.3 1.3 1.3 1.3 1.3 1.3 1.3 1.3 1.3 1.3 ... #> $ status_corr : num 1 1 1 1 1 1 1 1 1 1 ...