Utilities

Gap infilling, pith-offset conversion, LiPD interchange, plotting, and CLI helpers.

fill_internal

Fill interior gaps (interior NaN) in a ring-width dataset.

Only interior NaN -- those between a series' first and last real ring -- are filled; leading and trailing NaN are left untouched. A real 0 (a locally absent ring) is data and is never treated as a gap. Series with one or no real value are returned unchanged.

Parameters:

Name	Type	Description	Default
data	pandas dataframe	ring widths (or indices), years as the index and series as columns.	required
fill	(Mean, Spline, Linear, ARSTAN)	how to fill each interior gap: "Mean" : the series' mean (flat fill). [dplR fill.internal.NA] "Linear" : straight-line interpolation between the flanking values. "Spline" : cubic-spline interpolation through the present values. a number : that constant value. "ARSTAN" : Ed Cook's ARSTAN fillin -- impute each missing ring from the common (mean) chronology signal, moment-matched to the individual series and modulated by its growth curve (see Notes and _fill_arstan). The four simple options are a port of dplR's fill.internal.NA(); "Mean", "Linear" and "Spline" interpolate within each series only.	"Mean"
**kwargs		for fill="ARSTAN", forwarded to _fill_arstan (e.g. growth_nyrs, long_gap, flank).	{}

Returns:

Name	Type	Description
out	pandas dataframe, same shape/index/columns as `data`, with interior	gaps filled.

Notes

The simple methods know nothing about the other series -- they just bridge each hole -- so use them when you need an NaN-free series for a downstream step, not as if the filled values were measured. "ARSTAN" instead borrows the shared year-to-year signal from all series, which is the point of Cook's method.

po_to_wc

Convert pith offset to (partial) wood completeness (dplR's po.to.wc()).

The number of missing heartwood rings is the pith offset minus one.

Parameters:

Name	Type	Description	Default
po	DataFrame	pith-offset table with a series column (series IDs) and a pith_offset column (integer years from the start of the core to the pith, minimum 1).	required

Returns:

Type	Description
DataFrame	one column, n_missing_heartwood (integer), indexed by series.

References

.. [1] https://rdrr.io/cran/dplR/man/po.to.wc.html

wc_to_po

Convert wood completeness to pith offset (dplR's wc.to.po()).

The pith offset is the number of missing heartwood rings plus the number of unmeasured inner rings plus one, for every series whose pith presence is known (complete/incomplete) or whose missing-heartwood count is given; other series get a missing pith offset.

Parameters:

Name	Type	Description	Default
wc	DataFrame	wood-completeness table indexed by series, with any of the optional columns pith_presence ("complete"/"incomplete"), n_missing_heartwood (int) and n_unmeasured_inner (int).	required

Returns:

Type	Description
DataFrame	a pith-offset table with series and pith_offset columns (nullable integer), suitable as input to RCS.

References

.. [1] https://rdrr.io/cran/dplR/man/wc.to.po.html

to_lipd

Write dplPy chronologies to a LiPD .lpd file.

Parameters:

Name	Type	Description	Default
chron	DataFrame	Chronology output from dpl.chron() or dpl.chron_ars() -- year indexed, with one or more chronology columns and, if present, 'samp_depth' (written as the count / sampleCount companion).	required
filename	str	Output path. .lpd is appended if missing.	required
rwl	DataFrame	Raw ring widths the chronology was built from. Written as a further measurement table, and -- if metadata is None -- used to auto-fill site metadata from its dplpy_metadata attrs.	None
metadata	SiteMetadata or dict	Site metadata for the geo block; defaults to what rwl carries.	None
dsname	str	LiPD dataset name; defaults to the filename stem (a purely-numeric name is avoided -- pylipd cannot resolve one).	None
column	str	The primary chronology column (written with isPrimary=True).	'std'
chronologies	None | 'all' | list of str	Which chronology columns to write. None writes just column; 'all' writes every non samp_depth column (e.g. std/res/ars from chron_ars); a list writes those columns. The primary is written first.	None
stats	DataFrame	Per-year running statistics (e.g. dpl.chron_stabilized(..., running_rbar =True)); a running-rbar column is written as RBAR on the primary chronology table and EPS is derived from it and sample depth (or taken from an EPS column if present).	None
publication	dict	Citation for the record: any of authors/author (str or list), doi, title, journal, year, url, citation.	None
provenance	str	Free-text description of how the chronology was built (detrending, AR, robust mean, ...). Stored on each chronology variable's description/notes and PaST long name.	None
archive_type	str	LiPD archiveType. Defaults to 'Wood'.	None

Returns:

Type	Description
str	The path written.

Notes

Requires the optional pylipd dependency: pip install "dplpy[lipd]".

from_lipd

Read a LiPD .lpd file into dplPy-native objects.

Returns a dict with:

• 'rwl' : the raw ring widths as a year-indexed DataFrame (series as columns), ready for dpl.detrend / dpl.chron, or None.
• 'chronology' : the primary (headline) chronology as a year-indexed DataFrame (trsgi plus any count/RBAR/EPS), or None.
• 'chronologies' : a dict of all chronologies found (keyed by a label such as 'standard'/'residual'/'arstan'), from measurement tables and/or model summaries.
• 'metadata' : a dpl.metadata()-shape dict from the geo block.
• 'dsname' : the LiPD dataset name.

Requires the optional pylipd dependency: pip install "dplpy[lipd]".

lipd_metadata

Read just the site metadata from a LiPD .lpd file, as a dpl.metadata()-shape dict. Requires the optional pylipd dependency.

plot

Plot a ring-width dataset as a line, spaghetti, or segment plot.

Parameters:

Name	Type	Description	Default
inp	str | DataFrame	a file path to a .csv or .rwl file, or a dataframe from dpl.readers().	required
type	str	'seg' (coverage segments, one bar per series), 'spag' (spaghetti: each series offset vertically, black by default -- pass color= a colormap name to shade by first year), or 'line' (all series overplotted against year).	'seg'
ax	matplotlib Axes	draw into this Axes instead of creating a new figure. When omitted, a figure is created and auto-sized to the data.	None
show	bool	call plt.show() after drawing. Set False to keep the figure for saving or further editing (the returned figure is still fully drawn).	True
**kwargs		passed through to the underlying plotter (e.g. zfac and color for the spaghetti plot -- color takes a colormap name like 'viridis'/'turbo' or a single colour like 'black').	{}

Returns:

Type	Description
(fig, ax) : tuple of matplotlib Figure and Axes	the figure and axes drawn on, so callers can save or restyle them. (Earlier versions returned None; the figure is now returned for reuse.)

Examples:

>>> dpl.plot(data)
>>> dpl.plot(data, type="spag")
>>> fig, ax = dpl.plot(data, type="seg", show=False); fig.savefig("seg.png")

References

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

help

readme