ice_shelf_state_and_fate.timeseries_module.timeseries

Module for creating a timeseries object.

Classes

Timeseries(label, timeseries_type[, ...])

The timeseries data class.
class Timeseries(label: str, timeseries_type: TimeseriesType, measurement_name: str | None = None, measurements: Series | None = None, measurement_std: Series | None = None, measurement_n: Series | None = None, measurement_uncertainties: Series | None = None, measurement_uncertainties_std: Series | None = None, measurement_uncertainties_n: Series | None = None, measurement_coverage: Series | None = None, measurement_coverage_n: Series | None = None, extent_polygon: Polygon | MultiPolygon | None = None, unit: str = '', uncertainty: UncertaintyType = UncertaintyType.STD)

Bases: object

The timeseries data class. A wrapper to maintain metadata with the timeseries.

detect_anomalies(stationary_check: bool = False) → tuple[Series, Series, Series]

Identify outlier events using Tukey’s method.

Detect statistical outliers in timeseries using interquartile range, with optional stationarity testing.

Parameters:

stationary_check (bool) – Whether to test for stationarity. Default is False.

Returns:

Boolean arrays for total outliers, upper outliers, and lower outliers.

Return type:

tuple[pd.Series, pd.Series, pd.Series]

detect_changes(model: str = 'l2', penalty: float = 2, min_size: int = 3, jump: int = 1) → tuple[Series, list[int]]

Detect change points in timeseries using PELT algorithm.

Apply Pruned Exact Linear Time algorithm to identify abrupt changes in timeseries mean.

Parameters:

  • model (str) – Cost function for change detection. Default is “l2”.

  • penalty (float) – Penalty value for change detection. Default is 2.

  • min_size (int) – Minimum segment size. Default is 3.

  • jump (int) – Subsample factor for speed. Default is 1.

Returns:

change_regionspd.Series

Series indicating the region each point belongs to.

change_pointslist[int]

Indices of detected change points.

Return type:

tuple[pd.Series, list[int]]

extent_polygon: Polygon | MultiPolygon | None = None
label: str
measurement_coverage: Series | None = None
measurement_coverage_n: Series | None = None
measurement_n: Series | None = None
measurement_name: str | None = None
measurement_std: Series | None = None
measurement_uncertainties: Series | None = None
measurement_uncertainties_n: Series | None = None
measurement_uncertainties_std: Series | None = None
measurements: Series | None = None
plot(spread: str | None, x_label: str | None = None, y_label: str | None = None) → None

Plot the timeseries data.

Parameters:

  • spread (str | None) – The spread to display on the line plot. This can be one of None, “uncertainties” and “percentiles”.

  • x_label (str | None) – A X-axis label to use, by default None

  • y_label (str | None) – A Y-axis label to use, by default None

plot_coverage(x_label: str | None = None) → None

Plot the data coverage.

The data coverage is defined as the percentage of points within a masked area with a valid measurement.

Parameters:

x_label (str | None) – A X-axis label to use, by default None

process_timeseries(data: Dataset, measurement_name: str, measurement_uncertainty_name: str | None, mask_geometry: Polygon | MultiPolygon | None, apply_mask: bool, aggregate: AggregationStrategy = AggregationStrategy.MEAN, period: AggregationPeriod | None = AggregationPeriod.MONTH, uncertainty: UncertaintyType | None = None, independent: bool = False, t0_normalisation: str | None = None) → None

Process the input data into a timeseries with associated uncertainties and coverage.

This is the main method processing the datacube into the time series. This works with both 3D and 1D data.

NOTE: Main entry point. NOTE: This function has been split into two separate functions depending on the data dimensionality. This is in attempt to simplify and make things more readable.

Parameters:

  • data (xr.Dataset) – The xarray dataset containing the measurement of interest as well as any other data of interest such as uncertainties. Ideally, this should be an xr.Dataset which has been read from an appropriately formatted GeoZarr.

  • measurement_name (str) – The specific measurement to be processed. This must be a key of a DataArray with the data xr.Dataset.

  • measurement_uncertainty_name (str | None) – The specific name of the uncertainty associated with the measurement. If None, it is assumed that the measurement will have no associated uncertainty.

  • mask_geometry (Polygon | MultiPolygon | None) – The mask geometry

  • apply_mask (bool) – Boolean flag whereby if True the mask supplied to the data will be used to mask the data. If False then the mask is only used to calculate the coverage.

  • aggregate (AggregationStrategy) –

    The aggregation to perform on the data, by default AggregationStrategy.MEAN. Currently these are limited to: mean, median, max, min. Note, the aggregation chosen determines the spread according to the following rules:

    • mean: standard deviation

    • median: IQR

    • max/min: None

  • period (AggregationPeriod | None) – The time period over which to aggregate, by default AggregationPeriod.MONTH

  • uncertainty (UncertaintyType | None) – The statistic type describing the uncertainty, by default None

  • independent (bool) – Whether the uncertainties are independent or not, by default False

  • t0_normalisation (str | None) – Whether to normalise the time series against time zero, by default None

summary_statistics() → None

Generate a set of summary statistics for a time series.

This assumes that the timeseries is ordered. It also assumes that there are associated uncertainties.

timeseries_type: TimeseriesType
uncertainty: UncertaintyType = 'std'
unit: str = ''