Chronology

Averaging detrended series into a site chronology, with optional autoregressive modelling and variance stabilization. See the Building chronologies guide.

chron

Build a mean-value chronology from ring-width indices.

Averages the series (detrended RWI) year by year into a standard chronology, optionally prewhitening each series with an AR model first to also produce a residual chronology. Mirrors dplR's chron().

Parameters:

Name	Type	Description	Default
rwi_data	pandas dataframe	detrended ring-width indices (e.g. from dpl.detrend()).	required
biweight	boolean	average with Tukey's biweight robust mean if True, else the arithmetic mean.	True
prewhiten	boolean	prewhiten each series with an AR model to also build a residual chronology.	False
plot	boolean	plot the chronology.	True
max_lag	int	maximum AR order considered when prewhiten is True. To reproduce dplR's chron() exactly, pass max_lag=floor(10*log10(n)).	10
aic	boolean	when prewhiten is True, select the AR order by AIC up to max_lag; if False, fit a fixed AR of order max_lag.	True
ar_method	(yw, ols)	AR estimator for prewhitening. "yw" (Yule-Walker) matches R's ar() default; "ols" matches R's ar(method="ols").	"yw"
first_aic_min	boolean	AR order-selection rule when aic is True. False takes the global AIC minimum (reproduces dplR's chron()); True takes the first local AIC minimum (more parsimonious).	False
stabilize	(None, rbar, spline, both)	if set, also variance-stabilize each chronology and return the stabilized versions in extra *_vsc columns (see Notes). Method families are as in :func:stabilize_chron.	None
stabilize_kwargs	dict	extra keyword arguments forwarded to :func:stabilize_chron when stabilize is set. The chronology, column, source RWI matrix, and sample depth are supplied automatically and may not be overridden here.	None
ci	boolean	also compute a bootstrap confidence interval for the standard chronology, adding lower_ci and upper_ci columns. Each year's available series are resampled R times and the normal-approximation interval of the bootstrap means is taken. Years with fewer than two series get NaN limits (with a warning). The interval is only for the standard chronology.	False
conf	float	confidence level, used when ci is True.	0.95
R	int	number of bootstrap replicates per year, used when ci is True.	1000
seed	int or None	seed for the ci bootstrap, for reproducible intervals.	None

Returns:

Name	Type	Description
data	pandas dataframe	a mean-value chronology indexed by year, with columns std (standard chronology), res (residual chronology, only when prewhiten is True), and samp_depth. With ci=True, lower_ci and upper_ci columns for the standard chronology. When stabilize is set, a stabilized *_vsc column is added next to each base chronology.

Notes

Variance stabilization (stabilize). The standard chronology is stabilized with the rbar of the standard RWI matrix and the residual chronology with the rbar of the residual matrix; both restandardize to the full period (see :func:stabilize_chron). For the re-reddened ARSTAN chronology, use :func:chron_ars with stabilize=.

Examples:

>>> import dplpy as dpl
>>> rwi_data = dpl.detrend(dpl.readers("../tests/data/csv/file.csv"))
>>> dpl.chron(rwi_data)
>>> dpl.chron(rwi_data, prewhiten=True)

References

.. [1] https:/opendendro.org/dplpy-man/#chron

chron_stabilized

Build a variance-stabilized mean-value chronology.

Scales a mean-value chronology by the square root of the effective independent sample size Neff = n(t) / (1 + (n(t)-1) rbar(t)), where n(t) is the sample depth and rbar(t) the mean pairwise interseries correlation, computed over windows of length win_length. Port of dplR's chron.stabilized().

Parameters:

Name	Type	Description	Default
rwi_data	DataFrame	detrended ring-width indices.	required
win_length	int	window length over which rbar values are calculated.	50
min_seg_ratio	float	minimum ratio of non-NA values to window length for a series to count in an Neff calculation (⅓ matches dplR's chron.stabilized()).	1/3
biweight	boolean	average with Tukey's biweight robust mean if True, else the arithmetic mean.	True
running_rbar	boolean	also return the running rbar values in the output (only for method='running_rbar').	False
method	str	the variance-stabilization method: 'running_rbar' : running-window-rbar effective-signal adjustment (Frank et al. 2006 "RUNNINGr"); the default. Uses win_length and min_seg_ratio. 'briffa' (alias 'mean_rbar') : the same adjustment with a single time-constant rbar over all pairwise overlaps longer than 20 years (Osborn et al. 1997; Frank et al. 2006 "MEANr"). Corrects for changing sample size only. 'spline' : ARSTAN's ad-hoc spline stabilization, removing any time trend in the absolute departures with a smoothing spline. Can remove real low-frequency variance -- use with care. Stiffness set by spline_nyrs.	'running_rbar'
spline_nyrs	(int, float or None)	stiffness for method='spline'. An int is a fixed spline wavelength in years; a float in (0, 1) is a fraction of the chronology length; None uses 0.5. Ignored by the rbar methods.	None

Returns:

Name	Type	Description
stabilized_chron	pandas dataframe	a variance-stabilized mean-value chronology indexed by year, with columns vsc, Running rbar (only when running_rbar=True), and samp_depth.

Examples:

>>> import dplpy as dpl
>>> data = dpl.readers("../tests/data/csv/file.csv")
>>> dpl.chron_stabilized(data, win_length=60, min_seg_ratio=0.4)

References

.. [1] https://rdrr.io/cran/dplR/man/chron.stabilized.html

stabilize_chron

Variance-stabilize an already-built chronology.

Scales the departures of a chronology you already built with :func:chron or :func:chron_ars (standard, residual, or ARSTAN) to remove time-varying variance. Unlike :func:chron_stabilized, which takes the RWI matrix and builds its own standard chronology, this takes the finished chronology.

Parameters:

Name	Type	Description	Default
chron	Series or DataFrame	the chronology to stabilize. A Series is used directly; a DataFrame (e.g. chron()/chron_ars() output) uses column and, if present, its samp_depth column.	required
method	(rbar, spline, both)	required, explicit: "rbar" -- Osborn (1997) / Frank (2006) N_eff scaling; corrects variance driven by changing sample size (and, with running rbar, changing interseries correlation). Needs sample depth and rbar. "spline" -- ARSTAN's ad-hoc absolute-departure spline; flattens all time-varying variance whatever the cause, and can remove real low-frequency variance. Needs only the chronology. "both" -- "rbar" then a 67% "spline", in sequence.	"rbar"
column	str	which column to stabilize when chron is a DataFrame.	"std"
rwi	DataFrame	the source ring-width-index matrix (for the "rbar" family); rbar, running rbar, and sample depth are derived from it. For a residual or ARSTAN chronology pass the residual (prewhitened) matrix.	None
rbar	float	precomputed scalar rbar (for rbar_mode="constant" without rwi).	None
running_rbar	array - like	precomputed per-year running rbar (for rbar_mode="running" without rwi).	None
samp_depth	array - like	per-year sample depth. Taken from the DataFrame's samp_depth column or from rwi when not given.	None
rbar_mode	(running, constant)	running rbar (Frank RUNNINGr) or a single time-constant rbar (Osborn/Briffa MEANr).	"running"
win_length	(int, float)	running-rbar window length and minimum overlap ratio (as in chron_stabilized).	50
min_seg_ratio	(int, float)	running-rbar window length and minimum overlap ratio (as in chron_stabilized).	50
spline_period	(int, float or None)	spline stiffness for the "spline"/"both" families. None = the 67% spline (floor(0.67*n) years); an int > 1 is a fixed wavelength in years; a float in (0, 1) is a fraction of length; a negative value is a percent spline.	None
f	float	spline frequency response (50% amplitude cutoff).	0.5
clip_negative	bool	clamp the stabilized chronology at >= 0.	True
return_info	bool	also return a dict of diagnostics (rbar used, N_eff, sample depth).	False

Returns:

Type	Description
DataFrame	indexed by year, with the stabilized chronology in column vsc and, when known, samp_depth. If return_info is True, returns (DataFrame, info_dict).

Notes

Both families restandardize to the input chronology's full-period mean and SD. For the ARSTAN chronology, stabilization must precede re-reddening, so use chron_ars(stabilize=...) rather than calling this on an already re-reddened series.

References

Osborn, Briffa & Jones (1997) Dendrochronologia 15, 89-99. Frank, Esper & Cook (2006) TRACE 4, 56-66.

chron_ars

Build ARSTAN standard, residual, and re-reddened chronologies.

Produces the three ARSTAN chronologies of Cook (1985) from a set of detrended ring-width indices:

• std: the standard chronology, the (robust) mean of the RWI series with no autoregressive modeling.
• res: the residual chronology, each series prewhitened by a pooled AR(p) model, averaged, then prewhitened once more to order p (near-white).
• ars: the ARSTAN chronology, the pooled red-noise persistence reintroduced by re-reddening; ars_method sets how (see Notes).

The pooled AR order p is selected by AIC from an autocovariance accumulated across all series. Analog of dplR's chron.ars.

Parameters:

Name	Type	Description	Default
rwi_data	pandas dataframe	detrended ring-width indices (e.g. from dpl.detrend), years as the index and series as columns.	required
biweight	boolean	aggregate series with Tukey's biweight robust mean if True, else the arithmetic mean.	True
max_lag	int	maximum AR lag considered when selecting the pooled AR order.	10
first_aic_min	boolean	select the order at the first local AIC minimum (dplR's rule) if True, else the global AIC minimum.	True
verbose	boolean	print the pooled ACF, AR coefficients, AIC, and selected order.	True
prewhiten_method	str	"ar.yw" (Yule-Walker; numerically exact match to dplR) or "arima.CSS-ML" (matches dplR within tolerance).	"ar.yw"
ars_method	str	how the re-reddened ARSTAN chronology is built (see Notes): "arstan" re-reddens the mean of the prewhitened series; "dplr" re-reddens each series then averages (reproduces dplR). The two agree only when every series spans the full period.	"arstan"
backcast	boolean	backcast the initial values of each Yule-Walker prewhitening step so no leading years are lost (ARSTAN behavior). False sets the first p residuals to NaN, reproducing dplR's chron.ars. Applies to the "ar.yw" path; "arima.CSS-ML" already returns full-length residuals.	True
stabilize	(None, rbar, spline, both)	if set, also variance-stabilize each chronology and return the stabilized versions in extra *_vsc columns (see Notes). Method families are as in :func:stabilize_chron.	None
stabilize_kwargs	dict	extra keyword arguments forwarded to :func:stabilize_chron when stabilize is set. The chronology, column, source matrix, and sample depth are supplied automatically and may not be overridden here.	None

Returns:

Name	Type	Description
out	pandas dataframe indexed by year with columns 'std', 'res', 'ars', and	'samp_depth'. When stabilize is set, a stabilized std_vsc, res_vsc, and ars_vsc column is added next to each base chronology.

Notes

ARSTAN chronology (ars_method). Re-reddening and averaging do not commute when sample depth changes through time, so the ars column can be built two ways: "arstan" (default) re-reddens the mean of the prewhitened series; "dplr" re-reddens each series and then averages. The std and res columns, the pooled AR order, and the prewhitening are identical either way; only ars changes. Use ars_method="dplr" to reproduce dplR exactly.

Backcasting (backcast). An AR(p) filter has no data for its first p lagged terms. With backcast=True (default) those pre-sample values are estimated by running the model in reverse, so the residual and ARSTAN chronologies are full length (no leading NaN); the first p years are model-based, so treat them as slightly less certain. With backcast=False the first p residuals are NaN, reproducing dplR's chron.ars.

Variance stabilization (stabilize). std_vsc uses the rbar of the standard RWI matrix; res_vsc and the stabilized ARSTAN column use the rbar of the residual matrix. Each column restandardizes to its own full period (see :func:stabilize_chron).

Examples:

>>> import dplpy as dpl
>>> rwi = dpl.detrend(dpl.readers("../tests/data/csv/file.csv"), plot=False)
>>> dpl.chron_ars(rwi)

References

.. [1] https://rdrr.io/cran/dplR/man/chron.ars.html .. [2] Cook, E.R. (1985) A time series analysis approach to tree-ring standardization. PhD dissertation, University of Arizona.

autoreg

Fit the best-fit AR model to a series and return its parameters.

Selects the AR order up to max_lag by AIC and returns the fitted model parameters.

Parameters:

Name	Type	Description	Default
data	Series	an individual series representing tree rings/widths.	required
max_lag	int	maximum AR order considered when selecting the model.	5
aic	bool	select the AR order by AIC up to max_lag; if False, fit a fixed AR of order max_lag.	True
method	(ols, yw, burg)	AR estimator. "ols" matches R's ar(method="ols"); "yw" (Yule-Walker) matches R's ar() default; "burg" is the maximum-entropy estimator.	"ols"
first_aic_min	bool	when aic is True, False takes the global AIC minimum, True the first local AIC minimum (more parsimonious).	False

Returns:

Name	Type	Description
params	array	parameters of the best-fit AR model, as [intercept, phi_1, ..., phi_p].

Examples:

>>> import dplpy as dpl
>>> data = dpl.readers("../tests/data/csv/file.csv")
>>> dpl.autoreg(data["series name"])

References

.. [1] https:/opendendro.org/dplpy-man/#autoreg

ar_func

Prewhiten series with a best-fit AR model.

Fits each series to the best-fit autoregressive model and returns the residuals plus the series mean (the prewhitened series).

Parameters:

Name	Type	Description	Default
data	DataFrame or Series	ring widths from dpl.readers(), or a single series taken from one.	required
max_lag	int	maximum AR order considered when selecting the model.	5
aic	bool	select the AR order by AIC up to max_lag; if False, fit a fixed AR of order max_lag.	True
method	(ols, yw, burg)	AR estimator. "ols" matches R's ar(method="ols"); "yw" (Yule-Walker) matches R's ar() default; "burg" is the maximum-entropy estimator.	"ols"
first_aic_min	bool	when aic is True, False takes the global AIC minimum, True the first local AIC minimum (more parsimonious).	False

Returns:

Name	Type	Description
res	pandas dataframe or series	the prewhitened data (residuals plus mean), matching the input type.

Examples:

>>> import dplpy as dpl
>>> data = dpl.readers("../tests/data/csv/file.csv")
>>> dpl.ar_func(data["series name"])

References

.. [1] https:/opendendro.org/dplpy-man/#ar_func