Making permafrost data effortless
Project description
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()
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.