Metadata-Version: 2.1
Name: tsp
Version: 0.3.0
Summary: permafrost temperature time series
Home-page: https://gitlab.com/permafrostnet/teaspoon
Author: Nick Brown
Author-email: nick.brown@carleton.ca
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: regex
Provides-Extra: dev
Requires-Dist: manuel ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: coverage ; extra == 'dev'
Requires-Dist: mock ; extra == 'dev'
Provides-Extra: nc
Requires-Dist: netCDF4 ; extra == 'nc'
Provides-Extra: plotting
Requires-Dist: matplotlib ; extra == 'plotting'
Requires-Dist: scipy ; extra == 'plotting'

# 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](https://permafrostnet.gitlab.io/teaspoon/)

## Installation

### With pip
```bash
pip install tsp[nc,plotting]
```

### From source
```bash
git clone https://gitlab.com/permafrostnet/teaspoon.git
cd teaspoon
python setup.py develop
```

## Usage


```python
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)

```


    
![png](README_files/README_3_0.png)
    


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


```python
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


```python
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 |



```python
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


```python
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]);

```


    
![png](README_files/README_10_0.png)
    



    
![png](README_files/README_10_1.png)
    



    
![png](README_files/README_10_2.png)
    


### 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



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


    
![png](README_files/README_12_0.png)
    


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


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

```


    
![png](README_files/README_14_0.png)
    


### Colour Contour plot


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


    
![png](README_files/README_16_0.png)
    

