CFS_qa: Quality assessment: radius alignment

Description

Performs comprehensive quality assurance analysis for tree-ring crossdating using pairwise cross-correlation functions and iterative chronologies refinement with automatic memory-efficient batch processing.

Usage

CFS_qa(
  dt.input,
  qa.label_data = "",
  qa.label_trt = "",
  qa.max_lag = 10,
  qa.max_iter = 100,
  qa.min_nseries = 100,
  qa.blcrit = 0.1,
  qa.mem_target = 0.6
)

Value

An object of class cfs_qa containing:

dt.ccf: data.table with CCF results and QA codes (qa_code) for each series
dt.chron: data.table with chronologies statistics
dt.stats: data.table with summary statistics per radius
dt.plots: List of data.tables formatted for plotting (raw and treated series, CCF plots)
qa.parms: List of parameters used in the analysis

Arguments

dt.input

A data.table containing tree-ring measurements with required columns:

species: Character. Species identifier (must be single species)

SampleID

Character/Integer. Unique sample identifier

Year

Integer. Year of measurement

RawRing

Numeric. Raw ring-width measurement

RW_trt

Numeric. Treated/detrended ring-width series

qa.label_data

Character. Label identifier for the dataset (required)

qa.label_trt

Character. Label identifier for the treatment method (required)

qa.max_lag

Integer. Maximum lag for cross-correlation analysis (default: 10)

qa.max_iter

Integer. Maximum iterations for chronologies refinement (default: 100)

qa.min_nseries

Integer. Minimum number of series required (default: 100)

qa.blcrit

Numeric. Borderline threshold criterion for quasi-pass classification (default: 0.1)

qa.mem_target

Numeric. Proportion of free memory to use for batch processing (0-1, default: 0.6). Higher values use more memory but may be faster.

Details

The function performs a two-step quality assurance process:

Step 1: Pairwise Cross-Correlation

Computes CCF for all pairs of treated series
Uses auto-batching to manage memory efficiently
Identifies initial qualified samples with max CCF at lag 0

Step 2: Iterative chronologies Refinement

Computes chronologies from qualified samples
Evaluates each sample by running CCF with the chronologies
Iteratively refines the qualified samples until convergence

QA Code Classification:

pass: Maximum correlation at lag 0
borderline: Second highest correlation at lag 0 (within threshold)
pm1: Maximum correlation at lag +/- 1 (slight misalignment)
highpeak: Maximum at non-zero lag, >2x second highest
fail: All other cases

Auto-batching: The function automatically determines optimal batch size based on:

Available system memory
Number of CPU cores
Estimated memory per CCF operation
Safety margins to prevent out-of-memory errors

Examples

Run this code

# \donttest{
# loading processed data
dt.samples_trt <- readRDS(system.file("extdata", "dt.samples_trt.rds", package = "growthTrendR"))
# data processing
dt.samples_long <- prepare_samples_clim(dt.samples_trt, calbai = FALSE)
# rename to the reserved column name
data.table::setnames(dt.samples_long,
c("sample_id", "year", "rw_mm"), c("SampleID", "Year" ,"RawRing"))
# assign treated series
# users can decide their own treated series
# for rhub::rhub_check() on macos VECTOR_ELT issues
data.table::setorder(dt.samples_long, SampleID, Year)
dt.samples_long$RW_trt <-
  ave(
  as.numeric(dt.samples_long$RawRing),
  dt.samples_long$SampleID,
  FUN = function(x)
  if (length(x) > 1L) c(NA_real_, diff(x)) else NA_real_
  )
# quality check on radius alignment based on the treated series
dt.qa <-CFS_qa(dt.input = dt.samples_long, qa.label_data = "demo-samples",
qa.label_trt = "difference", qa.min_nseries = 5)
# }