Main Functions¶
Using Pyleoclim with a LiPD file¶
Getting started¶
Pyleoclim relies heavily on the concept of timeseries objects introduced in LiPD and implemented in the LiPD utilities.
Briefly, timeseries objects are dictionaries containing the ChronData values and PaleoData values as well as the metadata associated with the record. If one record has three ProxyObservations (e.g., Mg/Ca, d18O, d13C) then it will have three timeseries objects, one for each of the observations.
The LiPD utilities function lipd.extractTs() returns a list of dictionaries for the selected LiPD files, which need to be passed to Pyleoclim along with the path to the directory containing the LiPD files.
- This is done through the functions pyleoclim.openLiPD() and pyleoclim.fetchTs(),
which are lightweight versions of their counterparts in the LiPD utilities:
-
pyleoclim.
openLipd
(usr_path=None)¶ Read Lipd files into a dictionary
Sets the dictionary as global variable so that it doesn’t have to be provided as an argument for every function.
- Args:
usr_path (str): The path to a directory or a single file. (Optional argument)
- Returns:
lipd_dict - a dictionary containing the LiPD library
-
pyleoclim.
fetchTs
(lipds=None)¶ Extract timeseries dictionary
This function is based on the function of the same name in the LiPD utilities. Set the dictionary as a global variable so that it doesn’t have to be provided as an argument for every function.
- Args:
lipds (dict): A dictionary of LiPD files obtained through the readLipd function
- Returns:
ts_list - A list of timeseries object
Mapping¶
-
pyleoclim.
mapAllArchive
(lipds=None, markersize=50, projection='Robinson', proj_default=True, background=True, borders=False, rivers=False, lakes=False, figsize=[10, 4], saveFig=False, dir=None, format='eps')¶ Map all the available records loaded into the workspace by archiveType.
- Map of all the records into the workspace by archiveType.
Uses the default color palette. Enter pyleoclim.plot_default for detail.
- Args:
lipds (dict): A list of LiPD files. (Optional) markersize (int): The size of the markers. Default is 50 projection (string): the map projection. Available projections:
‘Robinson’, ‘PlateCarree’, ‘AlbertsEqualArea’, ‘AzimuthalEquidistant’,’EquidistantConic’,’LambertConformal’, ‘LambertCylindrical’,’Mercator’,’Miller’,’Mollweide’,’Orthographic’ (Default), ‘Sinusoidal’,’Stereographic’,’TransverseMercator’,’UTM’, ‘InterruptedGoodeHomolosine’,’RotatedPole’,’OSGB’,’EuroPP’, ‘Geostationary’,’NearsidePerspective’,’EckertI’,’EckertII’, ‘EckertIII’,’EckertIV’,’EckertV’,’EckertVI’,’EqualEarth’,’Gnomonic’, ‘LambertAzimuthalEqualArea’,’NorthPolarStereo’,’OSNI’,’SouthPolarStereo’
- proj_default (bool): If True, uses the standard projection attributes, including centering.
Enter new attributes in a dictionary to change them. Lists of attributes can be found in the Cartopy documentation:
- background (bool): If True, uses a shaded relief background (only one
available in Cartopy)
borders (bool): Draws the countries border. Defaults is off (False). rivers (bool): Draws major rivers. Default is off (False). lakes (bool): Draws major lakes.
Default is off (False).
figsize (list): the size for the figure saveFig (bool): Default is to not save the figure dir (str): The absolute path of the directory in which to save the
figure. If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
The figure
-
pyleoclim.
mapLipd
(timeseries=None, projection='Orthographic', proj_default=True, background=True, label='default', borders=False, rivers=False, lakes=False, markersize=50, marker='default', figsize=[4, 4], saveFig=False, dir=None, format='eps')¶ Create a Map for a single record
Orthographic projection map of a single record.
- Args:
timeseries: a LiPD timeseries object. Will prompt for one if not given projection (string): the map projection. Available projections:
‘Robinson’, ‘PlateCarree’, ‘AlbertsEqualArea’, ‘AzimuthalEquidistant’,’EquidistantConic’,’LambertConformal’, ‘LambertCylindrical’,’Mercator’,’Miller’,’Mollweide’,’Orthographic’ (Default), ‘Sinusoidal’,’Stereographic’,’TransverseMercator’,’UTM’, ‘InterruptedGoodeHomolosine’,’RotatedPole’,’OSGB’,’EuroPP’, ‘Geostationary’,’NearsidePerspective’,’EckertI’,’EckertII’, ‘EckertIII’,’EckertIV’,’EckertV’,’EckertVI’,’EqualEarth’,’Gnomonic’, ‘LambertAzimuthalEqualArea’,’NorthPolarStereo’,’OSNI’,’SouthPolarStereo’
- proj_default (bool): If True, uses the standard projection attributes, including centering.
Enter new attributes in a dictionary to change them. Lists of attributes can be found in the Cartopy documentation:
- background (bool): If True, uses a shaded relief background (only one
available in Cartopy)
- label (str): label for archive marker. Default is to use the name of the
physical sample. If no archive name is available, default to None. None returns no label.
borders (bool): Draws the countries border. Defaults is off (False). rivers (bool): Draws major rivers. Default is off (False). lakes (bool): Draws major lakes.
Default is off (False).
markersize (int): The size of the marker. marker (str or list): color and type of marker. Default will use the default color palette for archives figsize (list): the size for the figure saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
The figure
-
pyleoclim.
mapNearRecords
(timeseries=None, lipds=None, n=5, radius=None, sameArchive=False, projection='Orthographic', proj_default=True, borders=False, rivers=False, lakes=False, background=True, markersize=200, markersize_adjust=True, marker_r='ko', marker_c='default', cmap='Reds', colorbar=True, location='right', label='Distance in km', figsize=[4, 4], ax=None, saveFig=False, dir=None, format='eps')¶ Map the nearest records from the record of interest
- Args:
timeseries (dict): A timeseries object. If none given, will prompt for one lipds (list): A list of LiPD files. (Optional) n (int): the number of records to match radius (float): The distance (in km) to search for nearby records.
Default is to search the entire globe
- sameArchive (bool): Returns only records with the same archiveType.
Default is not to do so.
- projection (string): the map projection. Available projections:
‘Robinson’, ‘PlateCarree’, ‘AlbertsEqualArea’, ‘AzimuthalEquidistant’,’EquidistantConic’,’LambertConformal’, ‘LambertCylindrical’,’Mercator’,’Miller’,’Mollweide’,’Orthographic’ (Default), ‘Sinusoidal’,’Stereographic’,’TransverseMercator’,’UTM’, ‘InterruptedGoodeHomolosine’,’RotatedPole’,’OSGB’,’EuroPP’, ‘Geostationary’,’NearsidePerspective’,’EckertI’,’EckertII’, ‘EckertIII’,’EckertIV’,’EckertV’,’EckertVI’,’EqualEarth’,’Gnomonic’, ‘LambertAzimuthalEqualArea’,’NorthPolarStereo’,’OSNI’,’SouthPolarStereo’
- proj_default (bool): If True, uses the standard projection attributes, including centering.
Enter new attributes in a dictionary to change them. Lists of attributes can be found in the Cartopy documentation:
- background (bool): If True, uses a shaded relief background (only one
available in Cartopy)
borders (bool): Draws the countries border. Defaults is off (False). rivers (bool): Draws major rivers. Default is off (False). lakes (bool): Draws major lakes.
Default is off (False).
markersize (int): the size of the marker markersize_adjust (bool): If True, will proportionaly adjust the size of
the marker according to distance.
- marker_r (list or str): The color and shape of the marker for the
reference record.
- marker_c (list or str): The color and shape of the marker for the other
records. Default is to use the color palette by archiveType. If set to None then the color of the marker will represent the distance from the reference records.
- cmap (str): The colormap to use to represent the distance from the
reference record if no marker is selected.
colorbar (bool): Create a colorbar. Default is True location (str): Location of the colorbar label (str): Label for the colorbar. figsize (list): the size for the figure ax: Return as axis instead of figure (useful to integrate plot into a subplot) saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
ax - The figure
Plotting¶
-
pyleoclim.
plotTs
(timeseries=None, x_axis=None, markersize=50, marker='default', figsize=[10, 4], saveFig=False, dir=None, format='eps')¶ Plot a single time series.
- Args:
A timeseries: By default, will prompt the user for one. x_axis (str): The representation against which to plot the paleo-data.
Options are “age”, “year”, and “depth”. Default is to let the system choose if only one available or prompt the user.
markersize (int): default is 50. marker (str): a string (or list) containing the color and shape of the
marker. Default is by archiveType. Type pyleo.plot_default to see the default palette.
figsize (list): the size for the figure saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
The figure.
-
pyleoclim.
histTs
(timeseries=None, bins=None, hist=True, kde=True, rug=False, fit=None, hist_kws={'label': 'Histogram'}, kde_kws={'label': 'KDE fit'}, rug_kws={'label': 'Rug'}, fit_kws={'label': 'Fit'}, color='default', vertical=False, norm_hist=True, figsize=[5, 5], saveFig=False, format='eps', dir=None)¶ Plot a univariate distribution of the PaleoData values
This function is based on the seaborn displot function, which is itself a combination of the matplotlib hist function with the seaborn kdeplot() and rugplot() functions. It can also fit scipy.stats distributions and plot the estimated PDF over the data.
- Args:
timeseries: A timeseries. By default, will prompt the user for one. bins (int): Specification of hist bins following matplotlib(hist),
or None to use Freedman-Diaconis rule
hist (bool): Whether to plot a (normed) histogram kde (bool): Whether to plot a gaussian kernel density estimate rug (bool): Whether to draw a rugplot on the support axis fit: Random variable object. An object with fit method, returning
a tuple that can be passed to a pdf method of positional arguments following a grid of values to evaluate the pdf on.
- {hist, kde, rug, fit}_kws: Dictionaries. Keyword arguments for
underlying plotting functions. If modifying the dictionary, make sure the labels “hist”, “kde”, “rug” and “fit” are still passed.
- color (str): matplotlib color. Color to plot everything but the
fitted curve in. Default is to use the default paletter for each archive type.
vertical (bool): if True, oberved values are on y-axis. norm_hist (bool): If True (default), the histrogram height shows
a density rather than a count. This is implied if a KDE or fitted density is plotted
figsize (list): the size for the figure saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns
fig - The figure
Summary Plots¶
Summary plots are a special categories of plots enabled by Pyleoclim. They allow to plot specific information about a timeseries but are not customizable.
-
pyleoclim.
summaryTs
(timeseries=None, x_axis=None, saveFig=False, dir=None, format='eps')¶ Basic summary plot
Plots the following information: the time series, a histogram of the PaleoData_values, location map, spectral density using the wwz method, and metadata about the record.
- Args:
timeseries: a timeseries object. By default, will prompt for one x_axis (str): The representation against which to plot the paleo-data.
Options are “age”, “year”, and “depth”. Default is to let the system choose if only one available or prompt the user.
saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
The figure
Statistics¶
-
pyleoclim.
statsTs
(timeseries=None)¶ Calculate simple statistics of a timeseries
- Args:
timeseries: sytem will prompt for one if not given
- Returns:
the mean, median, min, max, standard deviation and the inter-quartile range (IQR) of a timeseries.
- Examples:
>>> mean, median, min_, max_, std, IQR = pyleo.statsTs(timeseries)
-
pyleoclim.
corrSigTs
(timeseries1=None, timeseries2=None, x_axis=None, autocorrect=True, autocorrect_param=1950, interp_method='interpolation', interp_step=None, start=None, end=None, nsim=1000, method='isospectral', alpha=0.05)¶ Estimates the significance of correlations between non IID timeseries.
- Args:
timeseries1, timeseries2: timeseries object. Default is blank. x-axis (str): The representation against which to express the
paleo-data. Options are “age”, “year”, and “depth”. Default is to let the system choose if only one available or prompt the user.
- interp_method (str): If the timeseries are not on the same axis, which
interpolation method to use. Valid entries are ‘interpolation’ (default) and ‘bin’.
- autocorrect (bool): If applicable, convert age to year automatically.
If set to False, timeseries objects should have converted time axis and updated units label in the dictionary
autocorrect_param (float): Reference for age/year conversion. interp_step (float): the step size. By default, will prompt the user. start (float): Start time/age/depth. Default is the maximum of
the minima of the two timeseries
- end (float): End time/age/depth. Default is the minimum of the
maxima of the two timeseries
nsim (int): the number of simulations. Default is 1000 method (str): method use to estimate the correlation and significance.
- Available methods include:
‘ttest’: T-test where the degrees of freedom are corrected for
the effect of serial correlation
‘isopersistant’: AR(1) modeling of the two timeseries
‘isospectral’ (default): phase randomization of original
inputs.
The T-test is parametric test, hence cheap but usually wrong except in idyllic circumstances. The others are non-parametric, but their computational requirements scales with nsim.
alpha (float): significance level for critical value estimation. Default is 0.05
- Returns:
r (float) - correlation between the two timeseries
sig (bool) - Returns True if significant, False otherwise
p (real) - the p-value
Timeseries¶
Basic manipulations of the timeseries objects.
-
pyleoclim.
binTs
(timeseries=None, x_axis=None, bin_size=None, start=None, end=None)¶ Bin the paleoData values of the timeseries
- Args:
timeseries. By default, will prompt the user for one. x-axis (str): The representation against which to plot the paleo-data.
Options are “age”, “year”, and “depth”. Default is to let the system choose if only one available or prompt the user.
- bin_size (float): the size of the bins to be used. By default,
will prompt for one
start (float): Start time/age/depth. Default is the minimum end (float): End time/age/depth. Default is the maximum
- Returns:
binned_values- the binned output,
bins- the bins (centered on the median, i.e. the 100-200 bin is 150),
n- number of data points in each bin,
error- the standard error on the mean in each bin
-
pyleoclim.
interpTs
(timeseries=None, x_axis=None, interp_step=None, start=None, end=None)¶ Simple linear interpolation
Simple linear interpolation of the data using the numpy.interp method
- Args:
timeseries. Default is blank, will prompt for it x-axis (str): The representation against which to plot the paleo-data.
Options are “age”, “year”, and “depth”. Default is to let the system choose if only one available or prompt the user.
interp_step (float): the step size. By default, will prompt the user. start (float): Start year/age/depth. Default is the minimum end (float): End year/age/depth. Default is the maximum
- Returns:
interp_age - the interpolated age/year/depth according to the end/start and time step,
interp_values - the interpolated values
-
pyleoclim.
standardizeTs
(timeseries=None, scale=1, ddof=0, eps=0.001)¶ Centers and normalizes the paleoData values of a given time series.
Constant or nearly constant time series not rescaled.
- Args:
timeseries (array): A LiPD timeseries object scale (real): a scale factor used to scale a record to a match a given variance ddof (int): degress of freedom correction in the calculation of the standard deviation eps (real): a threshold to determine if the standard deviation is too close to zero
- Returns:
z (array): the standardized time series (z-score), Z = (X - E[X])/std(X)*scale, NaNs allowed
mu (real): the mean of the original time series, E[X]
sig (real): the standard deviation of the original time series, std[X]
- References:
Tapio Schneider’s MATLAB code: http://www.clidyn.ethz.ch/imputation/standardize.m
The zscore function in SciPy: https://github.com/scipy/scipy/blob/master/scipy/stats/stats.py
@author: fzhu
-
pyleoclim.
segmentTs
(timeseries=None, factor=2)¶ Divides a time series into several segments using a gap detection algorithm
Gap detection rule: If the time interval between some two data points is larger than some factor times the mean resolution of the timeseries, then a brak point is applied and the timseries is divided.
- Args:
timeseries: a LiPD timeseries object factor (float): factor to adjust the threshold. threshold = factor*dt_mean.
Default is 2.
- Returns:
seg_y (list) - a list of several segments with potentially different length seg_t (list) - A list of the time values for each y segment. n_segs (int) - the number of segments
Analysis in the frequency domain¶
-
pyleoclim.
wwzTs
(timeseries=None, lim=None, wwz=False, psd=True, wwz_default=True, psd_default=True, fig=True, wwaplot_default=True, psdplot_default=True, saveFig=False, dir=None, format='eps')¶ Weigthed wavelet Z-transform analysis
Wavelet analysis for unevenly spaced data adapted from Foster et al. (1996)
- Args:
timeseries (dict): A LiPD timeseries object (Optional, will prompt for one.) lim (list): Truncate the timeseries between min/max time (e.g., [0,10000]) wwz (bool): If True, will perform wavelet analysis psd (bool): If True, will inform the power spectral density of the timeseries wwz_default: If True, will use the following default parameters:
- wwz_default = {‘tau’:None,
‘freqs’:None, ‘c’:1/(8*np.pi**2), ‘Neff’:3, ‘Neff_coi’:3, ‘nMC’:200, ‘nproc’:8, ‘detrend’:False, ‘params’ : [“default”,4,0,1], ‘gaussianize’: False, ‘standardize’:True, ‘method’:’Kirchner_f2py’, ‘bc_mode’:’reflect’, ‘reflect_type’:’odd’, ‘len_bd’:0}
Modify the values for specific keys to change the default behavior. See Spectral.wwz for details
psd_default: If True, will use the following default parameters:
- psd_default = {‘tau’:None,
‘freqs’: None, ‘c’:1e-3, ‘nproc’:8, ‘nMC’:200, ‘detrend’:False, ‘params’ : [“default”,4,0,1], ‘gaussianize’: False, ‘standardize’:True, ‘Neff’:3, ‘anti_alias’:False, ‘avgs’:2, ‘method’:’Kirchner_f2py’, }
Modify the values for specific keys to change the default behavior. See Spectral.wwz_psd for detail.s
fig (bool): If True, plots the figure wwaplot_default: If True, will use the following default parameters:
- wwaplot_default={‘AR1_q’:AR1_q,
‘coi’:coi, ‘levels’:None, ‘tick_range’:None, ‘yticks’:None, ‘yticks_label’: None, ‘ylim’:None, ‘xticks’:None, ‘xlabels’:None, ‘figsize’:[20,8], ‘clr_map’:’OrRd’, ‘cbar_drawedges’:False, ‘cone_alpha’:0.5, ‘plot_signif’:True, ‘signif_style’:’contour’, ‘plot_cone’:True, ‘title’:None, ‘ax’:None, ‘xlabel’: the chondata label, ‘ylabel’: ‘Period (units from ChronData)’, ‘plot_cbar’:’True’, ‘cbar_orientation’:’vertical’, ‘cbar_pad’:0.05, ‘cbar_frac’:0.15, ‘cbar_labelsize’:None}
Modify the values for specific keys to change the default behavior.
psdplot_default: If True, will use the following default parameters:
- psdplot_default={‘lmstyle’:’-‘,
‘linewidth’:None, ‘color’: sns.xkcd_rgb[“denim blue”], ‘ar1_lmstyle’:’-‘, ‘ar1_linewidth’:1, ‘period_ticks’:None, ‘period_tickslabel’:None, ‘psd_lim’:None, ‘period_lim’:None, ‘alpha’:1, ‘figsize’:[20,8], ‘label’:’PSD’, ‘plot_ar1’:True, ‘psd_ar1_q95’:95% quantile from psd, ‘title’: None, ‘legend’: ‘True’ ‘psd_ar1_color’:sns.xkcd_rgb[“pale red”], ‘ax’:None, ‘vertical’:False, ‘plot_gridlines’:True, ‘period_label’:’Period (units of age)’, ‘psd_label’:’Spectral Density’, ‘zorder’ : None}
Modify the values for specific keys to change the default behavior.
saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
dict_out (dict): A dictionary of outputs.
For wwz:
wwa (array): The weights wavelet amplitude
AR1_q (array): AR1 simulations
coi (array): cone of influence
freqs (array): vector for frequencies
tau (array): the evenly-spaced time points, namely the time
shift for wavelet analysis.
Neffs (array): The matrix of effective number of points in the
time-scale coordinates.
coeff (array): The wavelet transform coefficients
For psd:
psd (array): power spectral density
freqs (array): vector of frequency
psd_ar1_q95 (array): the 95% quantile of the psds of AR1 processes
fig: The figure
- References:
Foster, G. (1996). Wavelets for period analysis of unevenly sampled time series. The Astronomical Journal, 112(4), 1709-1729.
- Examples:
To run both wwz and psd:
>>> dict_out, fig = pyleoclim.wwzTs(wwz=True)
Note: This will return a single figure with wwa and psd
To change a default behavior:
>>> dict_out, fig = pyleoclim.wwzTs(psd_default = {'nMC':1000})
Age modelling¶
-
pyleoclim.
Bchron
(lipd, modelNum=None, objectName=None, rejectAges=None, calCurves=None, reservoirAgeCorr=None, predictPositions='paleo', positionsThickness=None, outlierProbs=None, iterations=1000, burn=2000, thin=8, extractDate=-69, maxExtrap=500, thetaMhSd=0.5, muMhSd=0.1, psiMhSd=0.1, ageScaleVal=1000, positionScaleVal=100, saveLipd=True, plot=True, figsize=[4, 8], flipCoor=False, xlabel=None, ylabel=None, xlim=None, ylim=None, violinColor='#8B008B', medianLineColor='black', medianLineWidth=2.0, CIFillColor='Silver', samplePaths=True, samplePathNumber=10, alpha=0.5, saveFig=False, dir=None, format='eps')¶ Runs Bchron and plot if asked
Fits a non-parametric chronology model to age/position data according to the Compound Poisson-Gamma model defined by Haslett and Parnell (2008). This version used a slightly modified Markov chain Monte-Carlo fitting algorithm which aims to converge quicker and requires fewer iterations. It also a slightly modified procedure for identifying outliers.
The Bchronology functions fits a compounf Poisson-Gamma distribution to the incrememnts between the dated levels. This involves a stochastic linear interpolation step where the age gaps are Gamma distributed, and the position gaps are Exponential. Radiocarbon and non-radiocarbon dates (including outliers) are updated within the fucntion also by MCMC.
This function also allows to save the ensemble, distributions, and probability tables as well as the parameters with which the model was run into the LiPD file.
Finally allows to make a plot.
- Args:
- lipd (dict): A dictionary containing the entry of a LiPD file. Can be
obtained from lipd.readLipd() or pyleoclim.openLipd(). Please note that the Bchron function currently only allows for a single LiPD file (i.e., not the entire directory).
- modelNum (int): The model number in which to place the Bchron output.
If unknown, the function will try to make a guess and/or prompt based on the number of already available models.
- objectName (str): The name of the chron object in which to store the new
model (e.g. “chron0”)
- rejectAges (vector): A vector of 1/0 where 1 include the dates to be rejected.
Default it None.
- calCurves (list): (Optional) A vector of values containing either ‘intcal13’,
‘marine13’, ‘shcal13’, or ‘normal’. If none is provided, will prompt the user. Should be either of length =1 if using the same calibration for each age or the same length as the vector of ages.
- reservoirAgeCorr (array): (Optional) A list (matrix) of two floats that correspond to the
DeltaR and DeltaR uncertainty. If already added to the ages and ages standard deviation, then enter [0,0] to bypass the prompt. Will only be applied if CalCurves is set to ‘marine13’. Otherwise, leave to none.
- predictPositions (array): (Optional) a vector of positions
(e.g. depths) at which predicted age values are required. Defaults to a sequence of length 100 from the top position to the bottom position.
- positionsThickness (array): (Optional) Thickness values for each of the positions.
The thickness values should be the full thickness value of the slice. By default set to zero.
- outlierProbs (array): (Optional) A vector of prior outlier probabilities,
one for each age. Defaults to 0.01
- iterations (int): (Optional) The number of iterations to start the procedure.
Default and minimum should be 10000.
- burn (int): (Optional) The number of starting iterations to discard.
Default is 200
- thin (int): (Optional) The step size for every iteration to keep beyond
the burnin. Default is 8.
- extractDate (float): (Optional) The top age of the core. Used for
extrapolation purposes so that no extrapolated ages go beyond the top age of the core. Defaults to the current year.
- maxExtrap (int): (Optional) The maximum number of extrapolations to
perform before giving up and setting the predicted ages to NA. Useful for when large amounts of extrapolation are required, i.e. some of the predictPositions are a long way from the dated positions. Defaults to 500.
- thetaMhSd (float): (Optional) The Metropolis-Hastings standard
deviation for the age parameters. Defaults to 0.5.
- muMhSd (float): (Optional) The Metropolis-Hastings standard deviation
for the compound Poisson-Gamma Scale. Defaults to 0.1
- psiMhSd (float): (Optional) The Metropolis-Hastings standard deviation
for the Compound Poisson-Gamma Scale.
- ageScaleVal (int): (Optional) A scale value for the ages.
Bchronology works best when the ages are scaled to be approximately between 0 and 100. The default value is thus 1000 for ages given in years.
- positionScaleVal (int): (Optional) A scale value for the positions.
Bchronology works best when the positions are scaled to be approximately between 0 and 100. The default value is thus 100 for positions given in cm.
- saveLipd (bool): If True, saves the ensemble, distribution, and probability
tables along with the parameters used to run the model in the LiPD file.
plot (bool): If True, makes a plot for the chronology figsize (list): The figure size. Default is [4,8] flipCoor (bool): If True, plots depth on the y-axis. xlabel (str): The label for the x-axis ylabel (str): The label for the y-axis xlim (list): Limits for the x-axis. Default corresponds to the min/max
of the depth vector.
ylim (list): Limits for the y-axis. Default set by matplotlib violinColor (str): The color for the violins. Default is purple medianLineColor (str): The color for the median line. Default is black. medianLineWidth (float): The width for the median line CIFillColor (str): Fill color in between the 95% confidence interval.
Default is silver.
- samplePaths (bool): If True, draws sample paths from the distribution.
Use the same color as the violins.
- samplePathNumber (int): The number of sample paths to draw. Default is 10.
Note: samplePaths need to be set to True.
alpha (float): The violins’ transparency. Number between 0 and 1 saveFig (bool): default is to not save the figure dir (str): the full path of the directory in which to save the figure.
If not provided, creates a default folder called ‘figures’ in the LiPD working directory (lipd.path).
- format (str): One of the file extensions supported by the active
backend. Default is “eps”. Most backend support png, pdf, ps, eps, and svg.
- Returns:
depth - the predicted positions (either same as the user or the default)
- chron - a numpy array of possible chronologies in each column.
The number of rows is the same as the length of depth
ageDist - the distribution of ages around each dates. fig - the figure run - the full R object containing the outputs of the Bchron run
- Warnings:
- This function requires R and the Bchron package and all its
dependencies to be installed on the same machine.
- Reference:
- Haslett, J., and Parnell, A. C. (2008). A simple monotone
process with application to radiocarbon-dated depth chronologies. Journal of the Royal Statistical Society, Series C, 57, 399-418. DOI:10.1111/j.1467-9876.2008.00623.x
- Parnell, A. C., Haslett, J., Allen, J. R. M., Buck, C. E.,
and Huntley, B. (2008). A flexible approach to assessing synchroneity of past events using Bayesian reconstructions of sedimentation history. Quaternary Science Reviews, 27(19-20), 1872-1885. DOI:10.1016/j.quascirev.2008.07.009
Using Pyleoclim without a LiPD file¶
The Pyleoclim modules can be called separately so the main functions can be used without a timeseries objects. The following modules are available:
pyleoclim.Map: mapping functions
pyleoclim.Plot: plotting functions
pyleoclim.Stats: statistics (including correlation)
pyleoclim.Timeseries: binning, interpolating
pyleoclim.Spectral: analysis in the frequency domain
pyleoclim.RBchron: Bchron age model analysis
In addition, the pyleoclim.LipdUtils module allows the basic manipulation of LiPD files and the pyleoclim.SummaryPlots module contains some functions to extract information about a timeseries object.