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`
`ar_max`	`int`	maximum AR order considered when prewhiten is True. To reproduce dplR's chron() exactly, pass ar_max=floor(10*log10(n)) and first_aic_min=False. (`max_lag=` is accepted as a deprecated alias.)	`10`
`aic`	`boolean`	when prewhiten is True, select the AR order by AIC up to ar_max; if False, fit a fixed AR of order ar_max.	`True`
`ar_method`	`(yw, burg, ols)`	AR estimator for prewhitening (case-insensitive). "yw" (Yule-Walker) matches R's ar() default; "burg" is ARSTAN's estimator; "ols" matches R's ar(method="ols").	`"yw"`
`first_aic_min`	`boolean`	AR order-selection rule when aic is True. True takes the first local AIC minimum (ARSTAN's rule, dplPy's package default); False takes the global AIC minimum, which is what R's ar() and dplR's chron() do.	`True`
`backcast`	`boolean`	when prewhiten is True, fill each series' first `p` residuals with ARSTAN-style backcast initials so no years are lost. False (default) leaves them NaN, as R's ar() residuals and dplR's chron() do.	`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 `stabilize_chron()`.	`None`
`stabilize_kwargs`	`dict`	extra keyword arguments forwarded to `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 (dplR's chron.ci default).	`100`
`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 (the full year index of `rwi_data`), with columns std (standard chronology), res (residual chronology, only when prewhiten is True), and samp_depth. A year with no series present has NaN chronology values and samp_depth 0, as in dplR. 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

Prewhitening. Each series is whitened with autoreg._prewhiten(), the package-wide prewhitening (Yule-Walker, ar_max=10, first local AIC minimum). This differs from R's ar()/dplR, which take the global AIC minimum up to floor(10*log10(n)); pass first_aic_min=False and ar_max accordingly to reproduce dplR.

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 stabilize_chron()). For the re-reddened ARSTAN chronology, use 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.github.io/dplPy/reference/chronology/#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 window_length. Port of dplR's chron.stabilized().

Parameters:

Name	Type	Description	Default
`rwi_data`	`DataFrame`	detrended ring-width indices.	required
`window_length`	`int`	window length over which rbar values are calculated. (`win_length=` is accepted as a deprecated alias.)	`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 (case-insensitive): 'running_rbar' : running-window-rbar effective-signal adjustment (Frank et al. 2006 "RUNNINGr"); the default. Uses window_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_period.	`'running_rbar'`
`spline_period`	`(int, float or None)`	stiffness for method='spline'. An int > 1 is a fixed spline wavelength in years; a float in (0, 1) is a fraction of the chronology length; None uses the 67% spline (`floor(0.67*n)` years, as stabilize_chron and dplR's detrend default; earlier releases used 0.5n). Ignored by the rbar methods. (`spline_nyrs=` is accepted as a deprecated alias.)	`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`. Years with no series present have `samp_depth` 0 and NaN `vsc`.

Notes

This function scales the departures and adds the grand mean back, as dplR does; stabilize_chron() instead restandardizes to the input chronology's full-period mean and SD, so the two differ slightly in level and scale.

Examples:

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

References

.. [1] https://rdrr.io/cran/dplR/man/chron.stabilized.html .. [2] https://opendendro.github.io/dplPy/reference/chronology/#chron_stabilized

stabilize_chron¶

Variance-stabilize an already-built chronology.

Scales the departures of a chronology you already built with chron() or chron_ars() (standard, residual, or ARSTAN) to remove time-varying variance. Unlike 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 (case-insensitive): `"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"`
`window_length`	`(int, float)`	running-rbar window length (default 50; must be shorter than the chronology) and minimum overlap ratio (as in chron_stabilized). (`win_length=` is accepted as a deprecated alias.)	`50`
`min_seg_ratio`	`(int, float)`	running-rbar window length (default 50; must be shorter than the chronology) and minimum overlap ratio (as in chron_stabilized). (`win_length=` is accepted as a deprecated alias.)	`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. Off by default: a chronology centered at zero (difference detrending, or a residual chronology) has legitimate negative departures, and clamping them floors the series at 0. Set True only for a positive ratio/index chronology where a negative value is not meaningful.	`False`
`return_info`	`bool`	also return the 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 a dict instead, with the DataFrame under `"vsc"` plus `"method"`, `"rbar"`, `"n_eff"` and `"samp_depth"` (the latter three for the rbar family).

Notes

Both families restandardize to the input chronology's full-period mean and SD, so the stabilized chronology stays on the scale you already had. dplR's chron.stabilized (ported as chron_stabilized()) instead scales the departures by sqrt(n_eff * rbar) and adds the grand mean back, which puts the chronology on the variance of an infinitely replicated chronology (Osborn, Briffa & Jones 1997). The two flatten the same variance trend and differ only by a uniform level and scale (on ca533: slope 1.11, offset -0.12, residual below 0.002), which matters for anything read off absolute index values but not for correlation-based uses. 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 an AR(p) model of the pooled order, 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. Columns with no measured values are dropped with a warning.	required
`biweight`	`boolean`	aggregate series with Tukey's biweight robust mean if True, else the arithmetic mean.	`True`
`ar_max`	`int`	maximum AR lag considered when selecting the pooled AR order. (`max_lag=` is accepted as a deprecated alias.)	`10`
`first_aic_min`	`boolean`	select the order at the first local AIC minimum (ARSTAN's and dplR's rule) if True, else the global AIC minimum. With True, a pooled AIC that never turns back up within `ar_max` raises ValueError.	`True`
`verbose`	`boolean`	print the pooled ACF, AR coefficients, AIC, and selected order.	`True`
`prewhiten_method`	`str`	estimator for the per-series (and residual-chronology) AR(p) whitening, case-insensitive: `"ar.yw"` (Yule-Walker; numerically exact match to dplR), `"burg"` (Burg maximum entropy, ARSTAN's estimator) 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 residual chronology, reproducing Ed Cook's ARSTAN and the current dplR development version; `"dplr"` re-reddens each prewhitened series then averages, reproducing released dplR <= 1.8.0.	`"arstan"`
`backcast`	`boolean`	backcast the initial values of each AR whitening and re-reddening step (ARSTAN's `bckcst`) so no leading years are lost. False sets the first `p` residuals of every series to NaN, as dplR's `chron.ars` does, and re-reddens from zero initials. Applies to the `"ar.yw"` and `"burg"` paths; `"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 `stabilize_chron()`.	`None`
`stabilize_kwargs`	`dict`	extra keyword arguments forwarded to `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). ARSTAN whitens every series to the pooled order p, averages them, whitens that mean once more (the residual chronology, albino1), and then puts the pooled persistence back into the residual chronology (commie1): ars = redden(res, phi_pooled). That is ars_method="arstan" (default), and also what the dplR development version computes. Released dplR <= 1.8.0 instead re-reddened each prewhitened series and averaged those; ars_method="dplr" reproduces it. Re-reddening and averaging do not commute when sample depth changes through time, so the two differ; the std and res columns, the pooled AR order, and the prewhitening are identical either way.

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 from the start of each series (ARSTAN's bckcst), so the residual and ARSTAN chronologies are full length (no leading NaN); the first p years of each series are model-based, so treat them as slightly less certain. With backcast=False the first p residuals of every series are NaN, as in dplR's chron.ars. Because series start in different years, that changes the chronology res (and ars) in every year where some series is within its first p years -- not only the first p years of the chronology. dplR's postAR took its re-reddening initials from the end of the record; dplPy follows ARSTAN here too, so ars differs from dplR in roughly the first 10 years of each series' contribution.

Variance stabilization (stabilize). std_vsc uses the rbar of the standard RWI matrix; res_vsc the rbar of the residual matrix; ars_vsc is the stabilized residual chronology re-reddened ("arstan") or the reddened chronology stabilized with the residual rbar ("dplr"). Each column restandardizes to its own full period (see 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. .. [3] https://opendendro.github.io/dplPy/reference/chronology/#chron_ars

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
`ar_max`	`int`	maximum AR order considered when selecting the model. (`max_lag=` is accepted as a deprecated alias.)	`10`
`aic`	`bool`	select the AR order by AIC up to ar_max; if False, fit a fixed AR of order ar_max.	`True`
`method`	`(yw, burg, ols)`	AR estimator. "yw" (Yule-Walker) is dplPy's package default and matches R's ar() default and dplR; "burg" is the estimator ARSTAN and COFECHA use; "ols" matches R's ar(method="ols").	`"yw"`
`first_aic_min`	`bool`	when aic is True, True takes the first local AIC minimum (ARSTAN's rule, dplPy's package default), False the global minimum. NOTE this default differs from R's ar() / dplR, which take the global minimum.	`True`

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.github.io/dplPy/reference/chronology/#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
`ar_max`	`int`	maximum AR order considered when selecting the model. (`max_lag=` is accepted as a deprecated alias.)	`10`
`aic`	`bool`	select the AR order by AIC up to ar_max; if False, fit a fixed AR of order ar_max.	`True`
`method`	`(yw, burg, ols)`	AR estimator. "yw" (Yule-Walker) is dplPy's package default and matches R's ar() default and dplR; "burg" is the maximum-entropy estimator ARSTAN and COFECHA use; "ols" matches R's ar(method="ols").	`"yw"`
`first_aic_min`	`bool`	when aic is True, True takes the first local AIC minimum (ARSTAN's rule, dplPy's package default), False the global minimum. NOTE this default differs from R's ar() / dplR, which take the global minimum.	`True`

Returns:

Name	Type	Description
`res`	`pandas dataframe or series`	the prewhitened data (residuals plus mean), matching the input type. The first `p` values of each series (the AR warm-up) are dropped, so a Series comes back `p` shorter and a DataFrame has NaN there. Columns with no measured values are dropped with a warning.

Examples:

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

References

.. [1] https://opendendro.github.io/dplPy/reference/chronology/#ar_func