Climate response

Correlation of a tree-ring chronology with monthly and seasonal climate (SEASCORR; Meko, Touchan & Anchukaitis 2011), bootstrapped monthly correlation and response functions (climate_response; Fritts et al. 1971, treeclim), the stability of a correlation through time by a moving-window analysis with Monte-Carlo significance (moving_corr), superposed epoch analysis of event responses (sea), and reconstruction of climate from a tree-ring network by orthogonal spatial / principal-components regression (OSR; Cook, Briffa & Jones 1994). See the Climate–growth response, Correlation and response functions, Moving correlation and Superposed epoch analysis guides for worked examples, and Reconstruction validation for how pcreg validates a reconstruction and what each statistic in result.stats means.

seascorr

Seasonal correlation of a tree-ring chronology with monthly climate.

A faithful port of SEASCORR (Meko, Touchan & Anchukaitis 2011). The chronology is correlated (simple Pearson) with a primary climate variable and (partial, controlling for the primary) with a secondary variable, across season-lengths x 14 ending months. Significance is assessed by exact spectral simulation of the chronology.

Parameters:

Name	Type	Description	Default
crn	Series or DataFrame	Year-indexed chronology (standard or residual). If a DataFrame, pass column= to choose the index series.	required
primary	DataFrame or Series	One monthly climate variable each, in any of three shapes: wide (year index/column + 12 month columns), tidy (year, month, value), or a monthly datetime/period-indexed series.	required
secondary	DataFrame or Series	One monthly climate variable each, in any of three shapes: wide (year index/column + 12 month columns), tidy (year, month, value), or a monthly datetime/period-indexed series.	required
end_month	int	Last month of the growth year (1=Jan ... 12=Dec).	9
season_lengths	sequence of int	Season lengths in months; the first must be 1.	(1, 3, 6, 12)
primary_agg	(sum, mean)	How each variable is aggregated over a season (sum for totals such as precipitation, mean for temperature).	"sum"
secondary_agg	(sum, mean)	How each variable is aggregated over a season (sum for totals such as precipitation, mean for temperature).	"sum"
nsim	int	Number of exact simulations; must be >= 1000.	1000
period	None, (first, last), or ((e0, e1), (l0, l1))	Analysis window. A single pair sets the window; a pair of pairs sets an early and a late window and triggers the stability test.	None
seed	int or None	Seed for the surrogate random generator (reproducible significance).	None
column	str or None	Chronology column to use when crn is a multi-column DataFrame.	None
plot	bool	Draw the seasonal bar chart (Figure 3 of the paper).	True

Returns:

Type	Description
SeascorrResult

SeascorrResult

Result of :func:seascorr.

Attributes:

Name	Type	Description
table	DataFrame	One row per season: season_length, end_month, label, r_primary, p_primary, r_partial, p_partial, r_clim (primary-vs-secondary), and the two-sided significance flags sig_05 / sig_01 for each correlation.
period	tuple(int, int)	First and last year of the analysis window.
nsim	int	Number of exact simulations used.
end_month, season_lengths	analysis settings.
highest	DataFrame	Strongest primary-variable season per season-length.
acf	ndarray	Lag 1-5 autocorrelation of the chronology over the window.
stability	DataFrame or None	Two-period difference-of-correlation test, when two windows were given.

climate_response

Bootstrapped correlation or response function of a chronology vs monthly climate.

Relates a tree-ring chronology to the individual months of one or more monthly climate variables over a window running from start_month to end_month (see the sign convention below). Two methods:

• "correlation" -- the Pearson correlation of the chronology with each month separately (DENDROCLIM2002-style correlation function).
• "response" -- a regression of the chronology on the principal components of the whole monthly-climate matrix, back-transformed to one coefficient per month (Fritts 1971; Guiot 1991). The PCA removes the collinearity between neighbouring months before attributing signal; PCs are retained by the PVP criterion (cumulative product of eigenvalues > 1).

Significance is bootstrapped. boot="exact" (the default) holds the climate fixed and simulates the chronology 1000x with the same spectrum (Meko's exact method, as in seascorr), testing each coefficient against that null by a Weibull non-exceedance probability. boot="std" resamples years with replacement (the classic DENDROCLIM2002 bootstrap) and reports a percentile confidence interval, calling a coefficient significant when the interval excludes zero. boot="stationary" is the same but uses the stationary (geometric-block) bootstrap of Politis & Romano (1994), which preserves the series' autocorrelation; the block length is chosen automatically by the Politis & White (2004) rule (as in treeclim), and is reported in result.settings["block_length"]. boot="none" returns point estimates only.

Month sign convention (as used by seascorr's end_month and by treeclim): positive months are the current growth year (1=Jan .. 12=Dec) and negative months the previous year (-1=Jan .. -12=Dec), so start_month=-6, end_month=9 is the window from previous June to current September, and start_month=-9 would be previous September. Months -13..-24 reach into the year before previous.

Parameters:

Name	Type	Description	Default
crn	Series or DataFrame	Year-indexed chronology. If a DataFrame, pass column= to choose the index series (same rules as seascorr).	required
climate	DataFrame, Series, or dict/list of them	One or more monthly climate variables, each in any shape seascorr accepts (wide year x 12 months, tidy year/month/value, or a monthly datetime-indexed series). A dict keys the variables by name; a bare frame is named from var_names or "climate".	required
start_month	int	The month window (signed convention above). Defaults -6 (previous June) to 9 (current September).	-6
end_month	int	The month window (signed convention above). Defaults -6 (previous June) to 9 (current September).	-6
method	(response, correlation)		"response"
boot	(exact, std, stationary, none)		"exact"
ci	float	Test level; one of 0.1, 0.05, 0.01. The confidence interval (for the resampling bootstraps) is set accordingly.	0.05
nboot	int	Number of bootstrap replicates / simulations (>= 1000).	1000
period	None or (first, last)	Restrict the analysis to these growth years; default is the longest common gap-free window.	None
seed	int or None	Seed for the bootstrap random generator (reproducible significance).	None
column	str or None	Chronology column when crn is a multi-column DataFrame.	None
var_names	str, sequence, or None	Names for the climate variable(s) when not supplied as a dict.	None
plot	bool	Draw the coefficient figure.	True

Returns:

Type	Description
ClimateResponseResult

Notes

PC retention currently uses the PVP criterion only; Fritts' original percent-variance / stepwise selection is a planned option (dplPy does a lot that traces back to Fritts, and this is worth revisiting).

ClimateResponseResult

Result of :func:climate_response.

Attributes:

Name	Type	Description
table	DataFrame	One row per (variable, month) predictor, in chronological month order: id, variable, month_id, year, month, coef, ci_lower, ci_upper, significant, p. ci_lower/ci_upper are NaN for the exact bootstrap (which yields a significance test, not a confidence interval); p is NaN for the resampling bootstrap (whose test is the confidence interval). For boot="none" both are NaN.
method	{response, correlation}
boot	{exact, std, stationary, none}
period	tuple(int, int)	First and last growth year of the analysis window.
settings	dict	start_month, end_month, ci, nboot, variables, and block_length (the stationary-bootstrap block length, or None for other methods).

summary

summary()

A compact text summary: the significant predictors, strongest first.

pcreg

Orthogonal spatial regression / PC-regression climate reconstruction.

A faithful port of Ed Cook's OSR FORTRAN (Cook, Briffa & Jones 1994). The predictors are screened against the target over the calibration window, reduced to principal components, and the target is regressed on the PCs that pass a t-test; the fit is back-transformed to per-predictor weights, a reconstruction is produced over the full predictor period, and (if a validation window is given) it is validated against the withheld data.

Parameters:

Name	Type	Description	Default
predictors	DataFrame or Series	Year-indexed tree-ring predictors (e.g. the output of :func:read_crn). Sample-depth companion columns are dropped automatically.	required
target	Series or 1-column DataFrame	Year-indexed climate target to reconstruct. Pre-seasonalize it yourself (e.g. a March-May PDSI mean) before calling.	required
calibration	(first, last)	Calibration window, inclusive.	required
validation	(first, last) or None	Validation window, inclusive. When None, only the calibration fit and the reconstruction are returned (no validation statistics).	None
screen_alpha	float	Screening significance level. Use 1.0 with screen_tails=2 to force every predictor into the PCA ("normal response function").	0.1
screen_tails	(1, 2)	One- or two-tailed screening test.	1
screen_sign	('+', '-', None)	Required correlation sign for a one-tailed test.	'+'
min_coverage	int or None	Minimum overlapping years to admit a predictor. Defaults to the full calibration length (every predictor must cover the whole window), which is what the fixture uses.	None
pc_criterion	(pvp, kaiser, first_m, cum_pct, all)	PC truncation rule (Cook's eigenvalue-cutoff options 3, 1, 0, 2, 4).	'pvp'
n_pc	int	Number of PCs for pc_criterion='first_m'.	12
ev_cutoff	float	Rescaled-eigenvalue cutoff for pc_criterion='kaiser'.	1.0
cum_pct	float	Cumulative-variance percent for pc_criterion='cum_pct'.	90.0
order_method	tstat	PC entry/stop rule. Phase 1 implements the t-statistic rule.	'tstat'
t_cutoff	float	|t| threshold for order_method='tstat'.	1.0
prewhiten	bool	Prewhiten predictors and target with a best-fit AR model before screening (reuses :func:dplpy.autoreg.ar_func). The AR order is chosen by AIC up to ar_max.	False
ar_max	int	Maximum AR order when prewhiten=True.	10
ar_method	(burg, yw, ols)	AR estimator. 'burg' (maximum entropy) matches Cook's memcof.	'burg'
lag	None, 11-char mask string, or sequence of int	Lead/lag the predictors before screening (Cook's lagit). Each predictor is expanded into one column per offset: offset d uses the predictor at year Y + d to predict year Y (d < 0 = a lag on earlier ring years, d > 0 = a lead). Give the offsets directly (e.g. (0, 1) or (-1, 0, 1)) or as an 11-char mask over positions -5..+5 (e.g. "00000110000" = offsets 0 and +1). The same mask is applied to every predictor.	None
cv	None or int	Cross-validate by refitting the whole pipeline on held-out folds of the calibration period. cv=1 is leave-one-out; cv=k leaves out contiguous k-year blocks. Results land in stats under the cv_ keys (cv_r, cv_RE, cv_CE; cv_RE and cv_CE coincide over the calibration window). None skips cross-validation.	None
first_differences	bool	Also report validation statistics on the 1st-differenced series (the FORTRAN's second validation pass), under _diff keys in stats.	True
plot	bool	Draw the reconstruction/validation figure.	False

Returns:

Type	Description
PcregResult

Notes

A single target, PC-regression core with optional AR prewhitening, lead/lag predictor masks, 1^st-difference validation, and leave-k-out cross-validation. Deferred to a later phase (and documented in dev/pcreg_DECISIONS.md): canonical regression, robust / biweight correlations, and the Southern-Hemisphere auto-shift.

PcregResult

Result of :func:pcreg.

Attributes:

Name	Type	Description
reconstruction	Series	Year-indexed reconstruction of the target over the full predictor period, in the target's own units (variance rescaled to the calibration mean and SD).
calibration, validation	tuple(int, int) or None	The calibration and validation windows (first, last).
predictors_screened	list	Column labels retained by the screening step, in column order.
screen_info	DataFrame	Per-predictor r, t and p from screening.
n_pc	int	Number of principal components retained.
pcs_selected	list of int	1-based PC numbers entered in the regression, in entry order.
cal_r2	float	Calibration R-squared.
stats	dict	Validation statistics on the undifferenced data, the same set on the 1st-differenced data under _diff keys, and -- when cv was requested -- the cross-validated skill under cv_ keys. The panel mirrors Cook's verify: RE, CE; Pearson r (r_p); spearman and kendall rank correlations (_p); the robust biweight midcorrelation (robust_p); the sign_pos/sign_neg sign test (sign_p); the product-means test pm_diff (pm_t, pm_p); and the equality-of-means test eqmeans_diff (eqmeans_t, eqmeans_p). Significance comes from SciPy's exact distributions; the correlation p-values are one-sided (positive skill expected) and the sign test is an exact binomial. robust is the modern biweight midcorrelation (equivalent to astropy's), which replaces Cook's older sum/difference robcor.
cv_reconstruction	Series or None	The pooled held-out cross-validation prediction per calibration year (target units), or None when cv was not requested.
dropped_coverage	list	Predictor columns excluded before screening for insufficient calibration coverage (with lead/lag, because the lagged window runs past their data). Reported as a warning at fit time; kept here for inspection.
weights	Series	Back-transformed weight per screened predictor.
eigenvalues	ndarray	Original eigenvalues of the screened-predictor correlation matrix (descending).
settings	dict	The resolved analysis settings.

sea

Superposed epoch analysis with the Rao et al. (2019) double bootstrap.

Composite a climate series in windows around a set of event years, normalized to each window's pre-event mean, to estimate the average response to the events. The double bootstrap adds a response-uncertainty envelope (how much the composite depends on which events are included) and a Monte-Carlo null for significance.

Parameters:

Name	Type	Description	Default
series	Series or (values, years)	the climate series, with its years (a Series indexed by year, or a pair of 1-D arrays).	required
events	array - like	the event (key) years. Events whose window would run past either end of the series are dropped with a warning.	required
pre	int	window half-widths: years before and after each event. The window is W = pre + post + 1 wide and the pre-event mean over the pre years before year 0 is the normalization baseline.	5
post	int	window half-widths: years before and after each event. The window is W = pre + post + 1 wide and the pre-event mean over the pre years before year 0 is the normalization baseline.	5
double_bootstrap	bool	if True, run Rao's outer bootstrap over unique event subsets to produce the response envelope; if False, an ordinary SEA (the composite and a null only).	True
n_sample	int	events per subset (the outer bootstrap). None uses about half the events, which maximizes the number of distinct subsets. Ignored unless double_bootstrap.	None
n_subsets	int	number of unique event subsets. If more than the number of possible subsets C(n_events, n_sample), the double bootstrap is switched off with a warning (an ordinary SEA is returned).	1000
n_boot	int	number of Monte-Carlo iterations for the null distribution.	1000
boot_method	(block, random)	the null. "block" reshuffles the real event windows in autocorrelation-preserving blocks (tests whether the response is locked to year 0); "random" draws pseudo-event years from the series (tests the amplitude against random years).	"block"
seed	int or None	seed for reproducibility (the MATLAB sets none, so its output varies run to run; dplPy makes it reproducible).	None
plot	bool	if True, draw the result (shaded envelope, median, null thresholds).	False

Returns:

Type	Description
SeaResult	see the class for attributes. composite is always the ordinary all-event mean; envelope is the 5/50/95 response envelope when the double bootstrap ran; null holds the ⅕/10/90/95/99 significance thresholds per lag.

References

Rao, M.P. et al. (2019). Dendrochronologia 55, 119-124. Adams, J.B., Mann, M.E., Ammann, C.M. (2003). Nature 426, 274-278 (block bootstrap).

SeaResult

Result of a superposed epoch analysis (see dpl.sea).

Attributes:

Name	Type	Description
lags	ndarray	window-relative years, -pre .. post.
composite	ndarray	the ordinary all-event superposed-epoch composite (always computed).
envelope	ndarray or None	the double-bootstrap response envelope, a 3 x W array of the 5th/50th/95th percentiles across event-subset composites, or None if not run.
null	DataFrame	the null-distribution thresholds, indexed by percentile (⅕/10/90/95/99), columns the lags.
windows	ndarray	the normalized event-window matrix (events x W).
events	ndarray	the event years actually used (after excising those too near the ends).
r1, block_length	(float, int)	lag-1 autocorrelation and block length (block null only).
settings	dict	the call parameters.

moving_corr

Moving (windowed) correlation of a tree-ring chronology with a seasonal climate variable, with global significance tests for the stability of the relationship.

The chronology is correlated with one seasonal climate series in a sliding window stepped by offset years, and the resulting trace is judged by Monte-Carlo tests that account for the dependence overlapping windows induce (Slutsky-Yule) and for having searched the whole record (multiplicity). See the guide for how to read the output; in short, a wobbling trace is not by itself evidence that the climate signal is unstable.

Parameters:

Name	Type	Description	Default
crn	Series or DataFrame	Year-indexed chronology (standard or residual). If a DataFrame with several columns, pass column= to choose the index series.	required
climate	DataFrame or Series	One monthly climate variable, in any shape seascorr accepts: wide (year index/column + 12 month columns), tidy (year, month, value), or a monthly datetime/period-indexed series.	required
end_month	int	Ending month of the season (1=Jan .. 12=Dec), as in seascorr.	9
season_length	int	Season length in months ending at end_month (1 = that month alone, 3 = the three months ending at it, etc.). Used for the single-trace mode.	1
season_lengths	sequence of int or None	If given (e.g. (1, 3, 6, 12)), switches to grid mode: a moving correlation for every season of these lengths across the 14 ending months up to end_month (the seascorr grid), returning a :class:MovingCorrGridResult with the three grid views and field significance. season_length is ignored in this mode.	None
agg	(mean, sum)	How to aggregate the months of the season: "mean" for temperature-like variables, "sum" for precipitation totals.	"mean"
window	int	Window width in years. Must be >= 10 and shorter than the aligned period.	30
offset	int	Step between successive windows, in years. 1 gives a fully overlapping, smooth trace; window gives adjacent, non-overlapping (independent) windows; values between trade smoothness for independence. The null is computed at the same offset, so the test stays fair at any overlap.	1
position	(center, end, start)	Which year of each window to plot/index the correlation at.	"center"
method	(pearson, spearman)	Correlation type (computed identically for the observed trace and the null).	"pearson"
noise	(red, white)	Surrogate null model. "red" (default) matches both series' lag-1 persistence -- the appropriate null for persistent climate/tree-ring series; "white" is the classical Gershunov null.	"red"
tests	sequence of {"std", "peak", "range"}	Which global tests to run. std (Gershunov) asks whether the trace is more/less variable than the null; peak whether the single strongest window is real; range whether the high-to-low swing is real.	('std', 'peak', 'range')
peak_condition	(observed, zero)	For the peak test: "observed" tests elevation above the background correlation; "zero" tests existence of any relationship.	"observed"
ci	(fisher, bootstrap, none)	Per-window uncertainty band. "fisher" (default) is an analytic Fisher-z interval at an autocorrelation-adjusted effective sample size; "bootstrap" is a moving-block bootstrap; "none" omits the band.	"fisher"
ci_level	float	Confidence level for the per-window band (e.g. 0.95).	0.95
n_boot	int	Bootstrap resamples per window when ci="bootstrap".	1000
iters	int	Monte-Carlo surrogate draws for the significance tests.	1000
seed	int or None	Seed for the random generator (reproducible significance and bootstrap).	None
period	None or (first, last)	Restrict the analysis to these years before aligning and windowing.	None
column	str or None	Chronology column to use when crn is a multi-column DataFrame.	None
plot	bool	Draw the trace-with-uncertainty figure.	False

Returns:

Type	Description
MovingCorrResult

MovingCorrResult

Result of :func:moving_corr.

Attributes:

Name	Type	Description
trace	DataFrame	One row per window, indexed by the window's position year (per position): columns start, end, r, and -- when a band was computed -- ci_lower / ci_upper.
tests	dict	The requested global tests, keyed "std" / "peak" / "range", each a result object with observed, p_value (and p_value_lower for the two-tailed std test), quantiles and threshold(level).
overall_corr	float	Full-period correlation between the aligned chronology and climate series.
r1_chronology, r1_climate	float	Lag-1 autocorrelation of each aligned series (drives the red-noise null and the effective-N band).
period	tuple(int, int)	First and last year of the aligned analysis window.
label	str	The season label (e.g. "Jun-Aug") of the climate variable.
settings	dict	The call parameters actually used.

threshold

threshold(level=0.95)

The peak-test upper significance line at level (the flat, multiplicity-aware threshold to read the trace against). Requires the peak test to have been run.

threshold_lower

threshold_lower(level=0.95)

The peak-test lower (trough) significance line at level: the multiplicity-aware threshold for significant negative excursions. Requires the peak test to have been run.

MovingCorrGridResult

Result of :func:moving_corr in grid mode (a moving seascorr).

Attributes:

Name	Type	Description
grid	DataFrame	One row per season cell: season_length, end_month, prior, label, overall_r (full-period correlation), stability_p (the Gershunov std-test p for the trace), and fdr_sig (survives FDR).
cube	(ndarray, shape(n_cells, n_windows))	The moving-correlation trace of every cell.
anomaly	ndarray	cube minus each cell's overall_r -- the departure from baseline.
pos_years	ndarray	Window-position years (per position), shared by all cells.
field	dict	Field significance: lc_p (Livezey-Chen grid-level p), lc_K_obs and lc_K_null (observed and null counts of locally-significant cells), n_fdr / fdr_crit / fdr_k (the FDR set).
overall, stability_p, thr95, r1_climate	ndarray (per cell)
r1_chronology	float
period	tuple(int, int)
settings	dict