tsp 0.3.0

permafrost temperature time series

Teaspoon

teaspoon is a library for permafrost time series data. Some of the features are:

• easily switch between "long" and "wide" data formats
• read a variety of common published data formats and model outputs
• useful plots

See the full documentation on the ReadTheDocs Pages

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

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_gtnp.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

long_data = data.long

long_data[1:10]

	time	depth	temperature_in_ground
1	2021-05-06 16:04:33.770647	1	-0.5
2	2020-05-06 16:04:33.770647	1	-0.4
3	2022-05-06 16:04:33.770647	5	-3
4	2021-05-06 16:04:33.770647	5	-2
5	2020-05-06 16:04:33.770647	5	-1.8
6	2022-05-06 16:04:33.770647	10	-5
7	2021-05-06 16:04:33.770647	10	-4.9
8	2020-05-06 16:04:33.770647	10	-4.8

wide_data = data.wide

wide_data[1:10]

	time	1	5	10
2021-05-06 16:04:33.770647	2021-05-06 16:04:33.770647	-0.5	-2	-4.9
2020-05-06 16:04:33.770647	2020-05-06 16:04:33.770647	-0.4	-1.8	-4.8

Plotting with TSP

The TSP class has several methods to easily generate plots

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.

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

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()