tsp 1.0.0

Making permafrost data effortless

Teaspoon

teaspoon is a python library designed to make working with permafrost time series data more straightforward, efficient, and reproduceable. Some of the features include:

• Read a variety of common published data formats, datalogger outputs, and model results into a common data structure
  • GEOtop model output
  • GTN-P database export csv
  • NTGS ground temperature report csv
  • Geoprecision datalogger export
  • HoboWare datalogger export
• Export data in a variety of common formats
  • netcdf
  • 'GTN-P'-style csv
  • 'NTGS'-style csv
• Perform common data transformations
  • Calculate daily, monthly, or yearly means, ignoring averaging periods with missing data
  • Switch between "long" and "wide" dataframes
• Visualize and explore your data with commonly used plots
  • Trumpet curves
  • Temperature-time graphs
  • Colour-contour profiles

See the full documentation on the ReadTheDocs Pages

Why "teaspoon" (tsp)?

• The data represent the Thermal State of Permafrost (or alternatively the Temperature du Sol en Profondeur)
• The data are easily represented by the netcdf Time Series Profile discrete feature geometry
• It's short and memorable!

Warning The distribution name (tsp) differs from the module you import (teaspoon)! So you would run (pip install tsp) vs (from teaspoon import *)

Installation

With pip

pip install tsp[nc,plotting]

From source

git clone https://gitlab.com/permafrostnet/teaspoon.git
cd teaspoon
python setup.py develop

Usage

import warnings
warnings.filterwarnings('ignore')
%matplotlib inline
from teaspoon.readers import read_gtnp, read_geotop
import pkg_resources

## Read common CSV exports
tsp_geotop = read_geotop(pkg_resources.resource_filename('teaspoon', 'data/example_geotop.csv'))
tsp_gtnp = read_gtnp(pkg_resources.resource_filename('teaspoon', 'data/example_gtnp.csv'))

## Make interesting plots
fig = tsp_geotop.plot_trumpet(title="A trumpet plot using teaspoon", year=2015, max_depth=4)

Classes

TSP

A time series profile, consisting of a time series at multiple depths is represented by the TSP class.

Optionally, you can provide coordinates and a dictionary with metadata information.

import datetime
from teaspoon import TSP

today = datetime.datetime.now()
t = [today - datetime.timedelta(days=365*x) for x in range(3)]

d = [1, 5, 10]

T = [[-1, -3, -5],
     [-0.5, -2, -4.9],
     [-0.4, -1.8, -4.8]]
mdict = {'terrain_type': 'Ice Wedge Polygon'}
data = TSP(depths = d, times=t, values=T, latitude=72, longitude=-114, metadata=mdict)

## Access original data as numpy arrays
data.depths
data.times
data.values

array([[-1. , -3. , -5. ],
       [-0.5, -2. , -4.9],
       [-0.4, -1.8, -4.8]])

Now we can access the 'long' (tidy) and the 'wide' data format

from IPython.display import Markdown, display

long_data = data.long

display(Markdown(long_data[1:10].to_markdown()))

	time	depth	temperature_in_ground	count
1	2021-07-18 15:28:14.401608	1	-0.5	1
2	2020-07-18 15:28:14.401608	1	-0.4	1
3	2022-07-18 15:28:14.401608	5	-3	1
4	2021-07-18 15:28:14.401608	5	-2	1
5	2020-07-18 15:28:14.401608	5	-1.8	1
6	2022-07-18 15:28:14.401608	10	-5	1
7	2021-07-18 15:28:14.401608	10	-4.9	1
8	2020-07-18 15:28:14.401608	10	-4.8	1

from IPython.display import Markdown, display

wide_data = data.wide

display(Markdown(wide_data[1:10].to_markdown()))

	time	1	5	10
2021-07-18 15:28:14.401608	2021-07-18 15:28:14.401608	-0.5	-2	-4.9
2020-07-18 15:28:14.401608	2020-07-18 15:28:14.401608	-0.4	-1.8	-4.8

Plotting with TSP

The TSP class has several methods to easily generate plots

%matplotlib inline
import pkg_resources as pr
import teaspoon as tsp

data = tsp.read_geotop(pr.resource_filename("teaspoon", "data/example_geotop.csv"))

data.plot_trumpet(year=2017, max_depth=10)
data.plot_contour(year=2017, contour=[0], max_depth=5, colours='dynamic')
data.plot_timeseries(title="What a great plot!", depths=[1, 5]);

Ensemble

A bunch of time series profiles with ways to slice and dice them

Plotting

You can also access the plotting functions directly

Trumpet Curve

from teaspoon.plots import trumpet_curve
import numpy as np

# Make up some data
dat =np.array([[0, 35, -30, -5],
               [-1, 20 , -25, -3],
               [-3, 10, -15,-2],
               [-6, -1, -5, -1.5],
               [-10, -1.2, -5, -1.1]])

# Make plot with plotting function
fig = trumpet_curve(depth=dat[:,0], t_max=dat[:,1], 
                    t_min=dat[:,2], t_mean=dat[:,3],
                    title="Example of trumpet plot", max_depth=-5)

fig.show()

Time series plot

The time series plot features a clickable legend that toggles the legend item on or off.

%matplotlib inline
import pkg_resources as pr
from teaspoon import read_geotop
from teaspoon.plots import time_series

# Get some data
data = read_geotop(pr.resource_filename("teaspoon", "data/example_geotop.csv"))
t = data.times
d = data.depths
T = data.values # z._values

# Make plot with plotting function
fig = time_series(depths=d, times=t, values=T,
                  title="Example of time series plot")
fig.show()

Colour Contour plot

%matplotlib inline
import pkg_resources as pr
from teaspoon import read_geotop
from teaspoon.plots import colour_contour

# Get some data
data = read_geotop(pr.resource_filename("teaspoon", "data/example_geotop.csv"))
t = data.times
d = data.depths
T = data.values # z._values

# Make plot with plotting function
fig = colour_contour(depths=d, times=t, values=T,
                     title="Example of colour contour plot",
                     max_depth=7, 
                     colours="symmetric", contour=[-3, 0], label_contour=True)
fig.show()