check.rwl: Check and Validate an rwl Object

In dplR: Dendrochronology Program Library in R

Check and Validate an rwl Object

Description

Checks that an object is a valid rwl and, if not, attempts coercion via as.rwl. Warns about internal NA values found within any series.

Usage

check.rwl(rwl, why = NULL, bai.ok = FALSE)

Arguments

rwl	an rwl object such as that produced by read.rwl. Also accepts a data.frame or matrix with series as columns and years as row names, which will be coerced to rwl with a warning.
why	NULL or a character string, added to the warning given when rwl is an "rwi" object, to say what goes wrong if indices are used as ring widths. NULL gives a general sentence.
bai.ok	logical. If TRUE, a "bai" object of basal area increment (see as.bai) is taken without a warning. detrend uses this.

Details

check.rwl is for functions that want ring widths. If rwl is an "rwi" object of ring-width indices (see as.rwi), a warning names the calling function, says that it wants widths, adds why, and suggests as.rwl if the values really are widths. The object is then relabelled as class "rwl" and checked as below. A "bai" object of basal area increment (see as.bai) is treated the same way, unless bai.ok is TRUE, when it is relabelled without a warning.

If rwl is not already of class "rwl", coercion is attempted using as.rwl. If coercion succeeds, a warning is issued. If coercion fails (e.g., because row names are not consecutive integers, columns are not numeric, or the input is not a data.frame or matrix), the function stops with a single informative message that describes both the class problem and the reason coercion failed.

After class validation, each series is checked for internal NA values, defined as NA values that are sandwiched between non-NA values within a series (as opposed to leading or trailing NAs, which are standard in rwl objects). If any are found, a warning names the affected series and suggests fill.internal.NA.

This function is called at the top of the dplR functions that want ring widths, providing uniform validation across the package. Functions that take widths or indices alike, and those that want indices, use internal checks of their own (see as.rwi).

Value

An object of class c("rwl", "data.frame") with series in columns and years as row names. The series IDs are the column names. The returned object is identical to the input when the input is already a valid rwl.

Author(s)

Andy Bunn

See Also

as.rwl, as.rwi, read.rwl, fill.internal.NA

Examples

library(utils)
data(ca533)

## A proper rwl passes silently and is returned unchanged
ca533.checked <- check.rwl(ca533)
identical(ca533, ca533.checked)

## A plain data.frame is coerced with a warning.
## suppressWarnings() is used here to keep R CMD check clean since the
## warning is expected. Remove it to see the coercion warning.
ca533.df <- ca533
class(ca533.df) <- "data.frame"
ca533.rwl <- suppressWarnings(check.rwl(ca533.df))
#ca533.rwl <- check.rwl(ca533.df)
class(ca533.rwl)

dplR documentation built on Oct. 1, 2026, 9:07 a.m.