char_pretreatment: Interpolate and pretreat a charcoal time series

In CharAnalysis: Peak Detection and Fire History from Sediment-Charcoal Records

Interpolate and pretreat a charcoal time series

Description

Resamples the raw charcoal data to equal time steps using a proportion-weighted scheme, fills missing-value gaps by linear interpolation, computes charcoal accumulation rates (CHAR), and optionally applies a log transformation.

Usage

char_pretreatment(
  char_data,
  site,
  pretreatment,
  results = NULL,
  plot_data = 1L
)

Arguments

char_data	Numeric matrix (n x 6+): cmTop, cmBot, ageTop, ageBot, charVol, charCount. Rows sorted youngest-first (ascending ageTop).
site	Character string; site name used in diagnostic messages.
pretreatment	Named list with elements: zoneDiv Numeric vector of zone boundaries (cal. yr BP), strictly ascending, at least 2 values. yrInterp Resampling interval (yr). 0 = use median raw resolution (auto). transform Integer: 0 = none; 1 = log10(x+1); 2 = ln(x+1).
results	Named list; only allFigures is referenced. Pass NULL to suppress any plot-related behaviour (no plots are produced in the R implementation in Phase 1).
plot_data	0/1 integer flag. Ignored in R (no diagnostic plots); included for API symmetry with the MATLAB function signature.

Details

Mirrors CharPretreatment.m from the MATLAB v2.0 codebase. The vectorised proportion matrix (four broadcast cases) produces results numerically identical to the MATLAB implementation within floating-point tolerance (~1e-14).

## Proportion matrix For each resampled interval i and each raw sample j, prop_matrix[i,j] is the fraction of the raw sample's age span that falls within the resampled interval. Four mutually exclusive overlap geometries (Cases A-D) are evaluated via matrix broadcasting across the full [N_{rs} \times N_{raw}] grid – no loops required.

| Case | Geometry | Overlap | |——|———————————————–|——————–| | A | Raw straddles the **bottom** edge | rsAgeBot - ageTop | | B | Raw straddles the **top** edge | ageBot - rsAgeTop | | C | Raw lies **entirely within** resampled interval | ageBot - ageTop | | D | Resampled lies **entirely within** raw sample | yrInterp |

## zoneDiv auto-correction If zoneDiv[end] exceeds the bottom age of the last raw sample, the terminal resampled intervals would have no overlapping raw data and accI would be NA. These NAs propagate into charBkg and can hang the GMM in Phase 2. The value is silently corrected to lastAgeBotInData and the user is notified (v2.0 behaviour, preserved here).

Value

Named list with three elements:

charcoal

List of raw and resampled series: cm, count, vol, con, ybp, acc (raw); cmI, countI, volI, conI, accI, ybpI (resampled).

pretreatment

Input list returned with yrInterp updated when it was 0 (auto), and zoneDiv[end] corrected if it exceeded the bottom age of the last raw sample.

gap_in

Integer matrix (nGaps x 2) of gap row-index pairs, or matrix(NA_integer_, 0, 2) when no gaps exist.

See Also

[char_parameters()], [char_validate_params()], [CharAnalysis()]

CharAnalysis documentation built on May 3, 2026, 5:06 p.m.