TSP classes

These classes provide the core of the teaspoon package.

class tsp.core.TSP(times, depths, values, latitude: float | None = None, longitude: float | None = None, site_id: str | None = None, metadata: dict = {})

A Time Series Profile (a collection of time series data at different depths)

A TSP can also be: Thermal State of Permafrost Temperature du Sol en Profondeur Temperatures, Secondes, Profondeurs

Parameters:

times (pandas.DatetimeIndex) – DatetimeIndex with optional UTC offset. List-like array of datetime objects can also be passed, but will be converted to a DatetimeIndex with no UTC offset.
depths (list-like) – d-length array of depths
values (numpy.ndarray) – array with shape (t,d) containing values at (t)emperatures and (d)epths
longitude (float, optional) – Longitude at which data were collected
latitude (float, optional) – Latitude at which data were collected
site_id (str, optional) – Name of location at which data were collected
metadata (dict) – Additional metadata

values

latitude

Latitude at which data were collected

Type:: float

longitude

Longitude at which data were collected

Type:: float

metadata

Additional metadata provided at instantiation or by other methods

Type:: dict

property freq: int | None: Measurement frequency [s]

property completeness: DataFrame | None: Data completeness

classmethod from_tidy_format(times, depths, values, number_of_observations=None, latitude: float | None = None, longitude: float | None = None, site_id: str | None = None, metadata: dict = {})

Create a TSP from data in a ‘tidy’ or ‘long’ format

Parameters:

times (list-like) – n-length array of datetime objects
depths (list-like) – n-length array of depths
values (numpy.ndarray) – n-length array of (temperaure) values at associated time and depth
number_of_observations (numpy.ndarray, optional) – n-length array of number of observations at associated time and depth for aggregated values (default: 1)
longitude (float, optional) – Longitude at which data were collected
latitude (float, optional) – Latitude at which data were collected
site_id (str, optional) – Name of location at which data were collected
metadata (dict) – Additional metadata

classmethod from_json(json_file) → TSP

Read data from a json file

Parameters:: json_file (str) – Path to a json file from which to read

Create a ‘synthetic’ temperature time series using the analytical solution to the heat conduction equation. Suitable for testing

Parameters:

depths (np.ndarray) – array of depths in m
start (str) – array of times in seconds
Q (Optional[float], optional) – Ground heat flux [W m-2], by default 0.2
c (Optional[float], optional) – heat capacity [J m-3 K-1], by default 1.6e6
k (Optional[float], optional) – thermal conductivity [W m-1 K-1], by default 2.5
A (Optional[float], optional) – Amplitude of temperature fluctuation [C], by default 6
MAGST (Optional[float], optional) – Mean annual ground surface temperature [C], by default -0.5

Returns:

A timeseries profile (TSP) object

Return type:

TSP

property long: DataFrame

Return the data in a ‘long’ or ‘tidy’ format (one row per observation, one column per variable)

Returns:

Time series profile data with columns:

time: time
depth: depth
temperature_in_ground: temperature
number_of_observations: If data are aggregated, how many observations are used in the aggregation

Return type:

pandas.DataFrame

property wide: DataFrame

Return the data in a ‘wide’ format (one column per depth)

Returns:: Time series profile data
Return type:: pandas.DataFrame

property number_of_observations: DataFrame

The number of observations for an average at a particular depth or time.

For pure observational data, the number of observations will always be ‘1’. When data are aggregated, (e.g. using monthly() or daily()) these numbers will be greater than 1.

Returns:: Number of observations
Return type:: DataFrame

reset_counts(): Set observation count to 1 if data exists, 0 otherwise

set_utc_offset(offset: int | str) → None

Set the time zone of the data by providing a UTC offset

Parameters:: offset (int, str) – If int, the number of seconds. If str, a string in the format “+HH:MM” or “-HH:MM”

property utc_offset: tzinfo | None

Get the time zone of the data by providing a UTC offset

Returns:: A timezone object
Return type:: datetime.tzinfo

property output_utc_offset: tzinfo | None

Get the time zone in which to output or display the data by providing a UTC offset

Returns:: A timezone object
Return type:: datetime.tzinfo

set_output_utc_offset(offset: int | str) → None: Set the time zone in which to display the output or data by providing a UTC offset :param offset: If int, the number of seconds. If str, a string in the format “+HH:MM” or “-HH:MM” :type offset: int, str

reset_output_utc_offset() → None: Reset the time zone in which to output or display the data to the default (the one set by set_utc_offset)

monthly(min_count: int | None = 24, max_gap: int | None = 691200, min_span: int | None = 1814400) → TSP

Monthly averages, possibly with some months unavailable (NaN) if there is insufficient data

Parameters:

min_count (int) – Minimum number of observations in a month to be considered a valid average, defaults to None
max_gap (int) –

Maximum gap (in seconds) between data points to be considered a valid average,
defaults to None
min_span (int) – Minimum total data range (in seconds) to be consiered a valid average, defaults to None

Returns:

A TSP object with data aggregated to monthly averages

Return type:

TSP

daily(min_count: int | None = None, max_gap: int | None = None, min_span: int | None = None) → TSP

Daily averages, possibly with some days unavailable (NaN) if there is insufficient data

Parameters:

min_count (int) – Minimum number of observations in a day to be considered a valid average, defaults to None
max_gap (int) – Maximum gap (in seconds) between data points to be considered a valid average, defaults to None
min_span (int) – Minimum total data range (in seconds) to be consiered a valid average, defaults to None

Returns:

A TSP object with data aggregated to daily averages

Return type:

TSP

yearly(min_count: int | None = None, max_gap: int | None = None, min_span: int | None = None) → TSP

Yearly averages, possibly with some years unavailable (NaN) if there is insufficient data

Parameters:

min_count (int) – Minimum number of observations in a month to be considered a valid average, defaults to None
max_gap (int) – Maximum gap (in seconds) between data points to be considered a valid average, defaults to None
min_span (int) – Minimum total data range (in seconds) to be consiered a valid average, defaults to None

Returns:

A TSP object with data aggregated to yearly averages

Return type:

TSP

property depths: ndarray

Return the depth values in the profile

Returns:: The depths in the profile
Return type:: numpy.ndarray

property times

Return the timestamps in the time series

Returns:: The timestamps in the time series
Return type:: pandas.DatetimeIndex

to_gtnp(filename: str) → None

Write the data in GTN-P format

Parameters:: filename (str) – Path to the file to write to

to_ntgs(filename: str, project_name: str = '', site_id: str | None = None, latitude: float | None = None, longitude: float | None = None) → None

Write the data in NTGS template format

Parameters:

filename (str) – Path to the file to write to
project_name (str, optional) – The project name, by default “”
site_id (str, optional) – The name of the site , by default None
latitude (float, optional) – WGS84 latitude at which the observations were recorded, by default None
longitude (float, optional) – WGS84 longitude at which the observations were recorded, by default None

to_netcdf(file: str) → None: Write the data as a netcdf

to_json(file: str) → None: Write the data to a serialized json file

plot_profiles(P: int = 100, n: int = 10) → Figure

Create a plot of the temperature profiles at different times

Parameters:

P (int) – Percentage of time range to plot
n (int) – Number of evenly-spaced profiles to plot

Returns:

matplotlib Figure object

Return type:

Figure

plot_trumpet(year: int | None = None, begin: datetime | None = None, end: datetime | None = None, min_completeness: float | None = None, **kwargs) → Figure

Create a trumpet plot from the data

Parameters:

year (int, optional) – Which year to plot
begin (datetime, optional) – If ‘end’ also provided, the earliest measurement to include in the averaging for the plot
end (datetime, optional) – If ‘begin’ also provided, the latest measurement to include in the averaging for the plot
min_completeness (float, optional) – If provided, the minimum completeness (fractional, 0 to 1) required to include in temperature envelope, otherwise the point is plotted as an unconnected, slightly transparent dot, by default None
**kwargs (dict, optional) – Extra arguments to the plotting function: refer to the documentation for trumpet_curve() for a list of all possible arguments.

Returns:

a matplotlib Figure object

Return type:

Figure

plot_contour(**kwargs) → Figure

Create a contour plot

Parameters:: **kwargs (dict, optional) – Extra arguments to the plotting function: refer to the documentation for colour_contour() for a list of all possible arguments.
Returns:: matplotlib Figure object
Return type:: Figure

plot_timeseries(depths: list = [], **kwargs) → Figure

Create a time series T(t) plot

Parameters:

depths (list, optional) – If non-empty, restricts the depths to include in the plot, by default []
**kwargs (dict, optional) – Extra arguments to the plotting function: refer to the documentation for time_series() for a list of all possible arguments.

Returns:

matplotlib Figure object

Return type:

Figure

class tsp.core.IndexedTSP(times, values, **kwargs)

A Time Series Profile that uses indices (1,2,3,…) instead of depth values.

Used in situations when depths are unknown (such as when reading datlogger exports that don’t have depth measurements.)

Parameters:

times (list-like) – t-length array of datetime objects
values (numpy.ndarray) – array with shape (t,d) containing values at (t)emperatures and (d)epths
**kwargs (dict) – Extra arguments to parent class: refer to TSP documentation for a list of all possible arguments.

property depths: ndarray

Depth indices

Returns:: An array of depth indices
Return type:: numpy.ndarray

set_depths(depths: ndarray)

Assign depth values to depth indices. Change the object to a TSP

Parameters:: depths (np.ndarray) – An array or list of depth values equal in lenth to the depth indices