Package: dplpy
dplPy -the Dendrochronology Program Library in PythonThe Dendrochronology Program Library (DPL) in Python has its roots in both theoriginal FORTRAN programcreated by thelegendary Richard Holmesand the subsequent R Project package by Andy Bunn,dplR.  Our aim is to provide researchers working with tree-ring data the necessary tools in open-source environments, promoting open science practices, enhancing rigor and transparency in dendrochronology, and eventually allowing reproducible research entirely in a single programming language.The development of dplPy is supported by a grant from the Paleoclimate program of the US National Science Foundation (AGS-2054516) to Andy Bunn, Kevin Anchukaitis, Ed Cook, and Tyson Swetnam.IndexdplPy - the Dendrochronology Program Library in PythonIndexRequirementsCurrent Version and ChangelogInstallationBuilding directly from GithubUsing VSCode in your operating systemLinux or MacOSWindowsFunctionalities and UsageLoading data usingreadersData Summary fromsummaryData Stastics fromstatsData Report fromreportPlottingDetrending usingdetrendAutoregressive (AR) modelingBuild a chronology withchronCrossdate withxdateRequirementsPython (>=3.10)Conda (AnacondaorMiniconda)(Suggested)Mamba(Suggested)VSCodeUnder the hood, dplPy usesnumpy,pandas,matplotlib,statsmodels,scipy, andcsaps.:warning: dplPy has been successfully tested thus far on Ubuntu 20, Ubuntu 22, macOS (Intel and M2). Other operating systems may experience unexpected errors or conflicts.  Please let the developers know.Current Version and ChangelogdplPy is currently at versionv0.1.2- The project is changing to a new development structure where all development will be onmainand releases and updates toPypiwill be branched and tagged frommain.InstallationdplPy is now available toinstall via pip:pip install dplpyTo ensure you have the latest version of dplPy installed, you can run:pip install dplpy --upgradeYou can install a conda virtual environment using theenvironment.yml for the project:$ conda env create -f environment.ymlBuilding directly from GithubYou can still still install dplPy firectly from Github if you wish:1. Clone and change directory to this repository$ git clone https://github.com/OpenDendro/dplPy.git
$ cd dplPy2. Create a conda environment through theenvironment.ymlfile. This will ensure all packages required are installed.$ conda env create -f environment.yml     

# if you have mamba installed you could instead do

$ mamba env create -f environment.ymlWhen prompted for permission to install required packages (withy/n), selecty.3. Activate your environment:$ conda activate dplpyYour environment should be successfully built.4. Your python environment should be able to importnumpy,pandas,matplotlib,statsmodelsandcsaps.Using VSCode in your operating systemLinux or MacOS1. In your VSCode terminal, activate the conda environment withconda activate dplpy3.2. Open a Jupyer Notebook (<file>.ipynb) and select thedplpy3Kernel when prompted (or from the top right of your screen). This will automatically load the environment we created.WindowsIn VSCode:1. In your VSCode terminal window, activate the conda environment withconda activate dplpy3.2. In the same terminal window, start a Jupyter Notebook withjupyter notebook. Jupyter will then return URLs that you can copy;Copyone of these URLs.3. Open a Jupyter Notebook (<file>.ipynb) and from thebottom rightof the VSCode screen, clickJupyter Server;A dropdown menu will open from the top of the screen: select Existing andpastethe URL you copied.4. Jupyter Notebook will now be able to access the environment created.Functionalities and UsageImport the dplPy tool withimport dplpy as dplor alternatively:import dplpyThis will load the package and its functions.Loading data usingreadersDescription: reads data from supported file types (csvandrwl) and stores them in a dataframe.Options:header: input files often have a header present; Default isFalse, useTrueif input has a header.Usage example:>>> data = dpl.readers("/path/to/file.rwl", header=True)Data Summary fromsummaryDescription: generates a summary of each series recorded inrwlandcsvformat filesUsage Example:>>> dpl.summary("/path/to/file.rwl")
# or
>>> dpl.summary(data)Data Stastics fromstatsDescription: generates summary statistics forrwlandcsvformat filesUsage Example:>>> dpl.stats("/path/to/file.rwl")
# or
>>> dpl.stats(data)Data Report fromreportDescription: generates a report about absent rings in the data setUsage Example:>>> dpl.report("/path/to/file.rwl")
# or
>>> dpl.report(data)PlottingDescription: generates plots of tree ring with data from dataframes. Currently capable of generatingline(default),spag(spaghetti) andseg(segment) plots.Options:type="line": creates a line plot (default)type="spag": creates a spaghetti plottype="seg": creates a segment plotUsage Example:>>> dpl.report("/path/to/file.rwl")
# or 
>>> dpl.plot(data)

# User is able to select specific series of interests.
# In the example below, the user selects SERIES_1, SERIES_2, SERIES_3 
# from the "data" dataset and generates a spaghetti plot
>>> dpl.plot(data[[SERIES_1, SERIES_2, SERIES_3]], type="spag")Detrending usingdetrendDescription: Detrends a given series or data frame, first by fitting data to curve(s), and then by calculating residuals or differences compared to the original data.Options:fit="spline": default detrending method.fit="ModNegEx": detrending using negative exponent method.fit="Hugershoff": detrending using the Hugenshoff method.fit="linear": detrending using the linear method.fit="horizontal": detrending using the horizontal method.method="residual": calculates residuals vs original data (default).method="difference": calculates differences vs original data.Plot: plotting results default isTrue, acceptsFalse.Usage Example:>>> dpl.detrend(data)
# or
>>> dpl.detrend(data, fit="Hugershoff", method="difference")

# User is able to select specific series of interests.
>>> dpl.detrend(data[[SERIES_1, SERIES_2, SERIES_3]], fit="Hugershoff", method="difference")Autoregressive (AR) modelingDescription: ontains methods that fit series to autoregressive models and perform functions related to AR modeling.Functions:autoreg(data['Name of series'], max_lag): returns parameters of best fit AR model with maxlag of 5 (default) or other specified numberar_func(data['Name of series'], max_lag): returns residuals plus mean of best fit from AR models with max lag of either 5 (default) or specified numberOptions:max_lag: default 5, can be specified to user's needs.Usage Example:>>> dpl.autoreg(data[SERIES_1])
# or
>>> dpl.ar_func(data[SERIES_2], max_lag=7)Build a chronology withchronDescription: creates a mean value chronology for a dataset, typically the ring width indices of a detrended series.Note: input data has to be detrended first.Options:biweight: find means using Tukey's biweight robust mean; defaultTrue.prewhiten: prewhitens data by fitting to an AR model; defaultFalse.plot: plots results; defaultTrue.Usage Example:# Detrend data first!
>>> rwi_data = dpl.detrend(data)

# Perform chronology
>>> dpl.chron(rwi_data, biweight=False, plot=False)Crossdate withxdateDescription: evaluate the dating accuracy of a set of tree-ring measurementsOptions: