lazarus: Replace traced values in an inventory table.
In dschoenig/IDENTcc: Catch and correct errors in IDENT datasets

Description Usage Arguments Details Value Examples

lazarus() performs a backwards replacement of values starting from a transition pattern.

1 2	lazarus(data, variable, sort_var, transition, backtrace_val, replace_val, append = TRUE)

`data`	Data frame containing measurements for an IDENT site (wide format). It must contain the index columns `Block`, `Plot`, and `Pos`.
`variable`	Variable (i.e. column) in the data set in which values are to be replaced.
`sort_var`	The data set is automatically partitioned according to `Block`, `Plot`, and `Pos` (i.e. position of the individual). For each position, the sequence of values is then sorted (in ascending order) by the variable (i.e. column the data set) specified with `sort_var`. In most cases, this column should be of type `numeric` or `integer`. If it is a factor, it will be sorted according to its `levels`. If it is of type `character`, it will be sorted alphabetically, which means that a value of `10` would be placed after `1` and before `2`.
`transition`	A vector of length 2, specifying the first and second value of a transition. These transitions will mark the start from which values equal to `backtrace_val` are traced backwards.
`backtrace_val`	Values that are to be traced, starting at a `transition`.
`replace_val`	New value that will replace `backtrace_val`. Replacement will only take place if the entry belongs to a traced chain that starts at a `transition`.
`append`	If `TRUE`, the resulting data frame is joined with the input `data`, that is all columns will be returned. Otherwise, only index columns, the original `variable` column, and the new columns, `variable_replace` and `variable_new`, are returned.

This function acts on a standard inventory table for an IDENT site. For a specified variable, it traces chains of values equal to backtrace_val, starting at entries that are the beginning of a transition pattern. The entries in the chains are then replaced with replace_val. The standard output contains the original data set and to two additional columns:

*variable*_replace indicates whether an entry was replaced.
*variable*_new holds the new sequence of values after performing replacements.

The performance of the function should remain stable for several hundred thousand rows.

A data frame with index columns, *variable*, *variable*_new holding the new values, and *variable*_replace indicating whether a value in the row has been replaced (1) or not (0).

# Backwards replace a chain of subsequent "Dead" values that occur before a
# transition from "Dead" to "Alive".
data(mortality)
lazarus(mortality,
        variable = "StateDesc",
        sort_var = "YearInv",
        transition = c("Dead", "Alive"),
        backtrace_val = "Dead", replace_val = "Alive",
        append = TRUE)