dplpy 0.1.1

Dendrochronology Program Library for Python

dplPy

The Dendrochronology Program Library for Python

---

Index

• Issues
• Requirements
• Building Environment
• Using jupyter
  • Linux, macOS
  • Windows
• Functionalities and usage
  • Loading data
  • Data Summary
  • Data Stastics
  • Data Report
  • Plotting
  • Autoregressive (AR) modeling
  • Detrending
  • Chronology

---

Issues

We're using ZenHub to manage our GitHub Issues

---

Requirements

:warning: Note: DplPy has been successfully tested on Ubuntu 20, Ubuntu 22, macOS (Intel, M2).

• Conda (Anaconda or Miniconda)
• (Suggested) Mamba
• (Suggested) VSCode

Building Environment

:warning: it is recommended to NOT use GitHub Codespaces (as of Mar 2022)

1. Clone and change directory to this repository

$ git clone https://github.com/OpenDendro/dplPy.git
$ cd dplPy

2. Create a conda environment through the environment.yml file. 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.yml

When prompted for permission to install required packages (with y/n), select y.

3. Activate your environment:

$ conda activate dplpy

Your environment should be successfully built.

4. Your python environment should be able to import numpy, pandas, matplotlib, statsmodels and csaps:

---

Using Jupyter

The Conda enviroment is essential as it provides will all necessary packages. To execute the code, use Jupyter Notebook.

:warning: Note: if using Jupyter from the terminal, you need to ensure that the kernel is findable by doing the following command once the environment is active:

python -m ipykernel install --user --name dplpy --display-name "Python (dplpy)"

Linux, MacOS

1. In your VSCode terminal, activate the conda environment with conda activate dplpy3. 2. Open a Jupyer Notebook (<file>.ipynb) and select the dplpy3 Kernel when prompted (or from the top right of your screen). This will automatically load the environment we created.

Windows

In VSCode:

1. In your VSCode terminal window, activate the conda environment with conda activate dplpy3. 2. In the same terminal window, start a Jupyter Notebook with jupyter notebook. Jupyter will then return URLs that you can copy; Copy one of these URLs.

3. Open a Jupyter Notebook (<file>.ipynb) and from the bottom right of the VSCode screen, click Jupyter Server;

A dropdown menu will open from the top of the screen: select Existing and paste the URL you copied.

4. Jupyter Notebook will now be able to access the environment created.

---

Functionalities and Usage

Import the DplPy tool with

import dplpy as dpl

This will load the necessary functions.

Loading data

• Description: reads data from supported file types (csv and rwl) and stores them in a dataframe.
• Options:
  • header: input files often have a header present; Default is False, use True if input has a header.
• Usage example:

  >>> data = dpl.readers("/path/to/file.rwl", header=True)
  

Data Summary

• Description: generates a summary of each series recorded in rwl and csv format files
• Usage Example:

  >>> dpl.summary("/path/to/file.rwl")
  # or
  >>> dpl.summary(data)
  

Data Stastics

• Description: generates summary statistics for rwl and csv format files
• Usage Example:

  >>> dpl.stats("/path/to/file.rwl")
  # or
  >>> dpl.stats(data)
  

Data Report

• Description: generates a report about absent rings in the data set
• Usage Example:

  >>> dpl.report("/path/to/file.rwl")
  # or
  >>> dpl.report(data)
  

Plotting

• Description: generates plots of tree ring with data from dataframes. Currently capable of generating line (default), spag (spaghetti) and seg (segment) plots.
• Options:
  • type="line": creates a line plot (default)
  • type="spag": creates a spaghetti plot
  • type="seg": creates a segment plot
• Usage 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")
  

Autoregressive (AR) modeling

• Description: 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 number
  • ar_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 number
• Options:
  • 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)
  

Detrending

• Description: 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 is True, accepts False.
• 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")
  

Chronology

• Description: 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; default True.
  • prewhiten: prewhitens data by fitting to an AR model; default False.
  • plot: plots results; default True.
• Usage Example:

  # Detrend data first!
  >>> rwi_data = dpl.detrend(data)
  
  # Perform chronology
  >>> dpl.chron(rwi_data, biweight=False, plot=False)