Station

This module contains the Station class, which is the main component of a Network and contains Timeseries, Model and associated fits.

class disstans.station.Station(name, location)[source]

Representation of a station, which contains both metadata such as location as well as timeseries, models and fits.

Timeseries are saved in the timeseries dictionary, and their associated models and fits are saved in the models and fits dictionaries, respectively.

Parameters

name (str) – Name of the station.
location (list[float] | tuple[float, float, float] | ndarray) – Location (Latitude [°], Longitude [°], Altitude [m]) of the station.

__contains__(ts_description)[source]

Special function that allows to check whether a certain timeseries is in the station.

Return type: bool

Example

If mystat is a Station instance, and we want to see whether 'myts' is contained by the station, the following two are equivalent:

# long version
'myts' in station.timeseries
# short version
'myts' in station

__delitem__(ts_description)[source]

Convenience special function that allows a dictionary-like removing of timeseries from the station by wrapping remove_timeseries(). :rtype: None

See also

remove_timeseries: Remove a timeseries from the station instance.

__getitem__(ts_description)[source]

Convenience special function that provides a shorthand notation to access the station’s timeseries.

Parameters: ts_description (str) – Description of the timeseries.
Return type: Timeseries
Returns: Timeseries in station.

Example

If stat is a Station instance and ts_description the ts_description of a station, the following two are equivalent:

stat.timeseries[ts_description]
stat[ts_description]

__iter__()[source]

Convenience special function that allows for a shorthand notation to quickly iterate over all timeseries.

Return type: Iterator[Timeseries]

Example

If stat is a Station instance,then the following two loops are equivalent:

# long version
for ts in stat.timeseries.values():
    pass
# shorthand
for ts in stat:
    pass

__setitem__(ts_description, timeseries)[source]

Convenience special function that allows a dictionary-like adding of timeseries to the station by wrapping add_timeseries(). :rtype: None

See also

add_timeseries: Add a timeseries to the station instance.

__str__()[source]

Special function that returns a readable summary of the station. Accessed, for example, by Python’s print() built-in function.

Return type: str
Returns: Station summary.

add_fit(ts_description, fit, model_description=None, return_ts=False)[source]

Add a fit dictionary to a timeseries’ model (overwrites the fit if it has already been added for the model).

Parameters

ts_description (str) – Timeseries to add the fit to.
fit (dict[str, Optional[ndarray]]) – Dictionary with the keys 'time', 'fit', 'var' and 'cov' (the latter two can be set to None).
model_description (Optional[str], default: None) – Model description the fit applies to. If None, the fit is the sum of all individual model fits.
return_ts (bool, default: False) – If True, return the created timeseries.

Return type

Optional[Timeseries]

Returns

(If return_ts=True.) The fit as a Timeseries object.

See also

disstans.timeseries.Timeseries.from_fit: Convert a fit dictionary to a Timeseries object.

add_local_model(ts_description, model_description, model)[source]

Add a model to a timeseries (overwrites the model if it has already been added with the same description).

Parameters

ts_description (str) – Timeseries to add the model to.
model_description (str) – Model description.
model (Model) – Model object.

Return type

None

add_local_model_dict(ts_description, model_dict)[source]

Add a dictionary of models to a timeseries (overwrites the models if they have already been added with the same description).

Wraps add_local_model().

Parameters

ts_description (str) – Timeseries to add the model to.
model_dict (dict[str, Model]) – Dictionary of {model_description: model} key-value pairs to add.

Return type

None

add_local_model_kwargs(ts_description, model_kw_args)[source]

Add models to a timeseries from a dictionary of keyword arguments needed to create them (overwrites the models if they have already been added with the same description).

Wraps add_local_model().

Parameters

ts_description (str) – Timeseries to add the model to.
model_kw_args (dict[str, dict[str, Any]]) – Dictionary of structure {model_name: {"type": modelclass, "kw_args": {**kw_args}}} that contains the names, types and necessary keyword arguments to create each model object.

Return type

None

add_timeseries(ts_description, timeseries, uncertainties_from=None, override_src=None, override_data_unit=None, override_data_cols=None, override_var_cols=None, override_cov_cols=None, add_models=None, warn_existing=True)[source]

Add a timeseries to the station.

Optionally, can override some Timeseries attributes when adding the object, and add models.

Parameters

ts_description (str) – Description of the timeseries.
timeseries (Timeseries) – Timeseries object to add.
uncertainties_from (Optional[Timeseries], default: None) – If the variance and covariance data should come from another timeseries, specify the source timeseries here.
override_src (Optional[str], default: None) – Override the src attribute of timeseries.
override_data_unit (Optional[str], default: None) – Override the data_unit attribute of timeseries.
override_data_cols (Optional[str], default: None) – Override the data_cols attribute of timeseries.
override_var_cols (Optional[str], default: None) – Override the var_cols attribute of timeseries.
override_cov_cols (Optional[str], default: None) – Override the cov_cols attribute of timeseries.
add_models (Optional[dict[str, Model]], default: None) – Dictionary of models to add to the timeseries, where the keys are the model description and the values are Model objects.
warn_existing (bool, default: True) – Issue a warning if a station’s timeseries is being overwritten.

Return type

None

See also

__setitem__: Shorthand notation wrapper when no optional arguments are necessary.

Example

If stat is a Station instance, ts_description the ts_description of a new timeseries, and ts a Timeseries instance, then the following two are equivalent:

stat.add_timeseries(ts_description, timeseries)
stat[ts_description] = timeseries

analyze_residuals(ts_description, verbose=False, t_start=None, t_end=None, mean=False, std=False, rms=False, n_observations=False, std_outlier=0, max_rolling_dev=0)[source]

Analyze, print and return the residuals of a station’s timeseries according to certain metrics defined in the arguments.

Parameters

ts_description (str) – Timeseries to analyze. Method assumes it already is a residual.
verbose (bool, default: False) – If True, additionally print the results.
t_start (UnionType[str, Timestamp, None], default: None) – If set, specify a lower bound for the analysis. t_start should be a Timestamp-convertible string of the start time, or a datetime-like object. None defaults to the first timestamp present in the timeseries.
t_end (UnionType[str, Timestamp, None], default: None) – If set, specify an upper bound for the analysis. t_end should be a Timestamp-convertible string of the end time, or a datetime-like object. None defaults to the last timestamp present in the timeseries.
mean (bool, default: False) – If True, calculate the mean of the timeseries. Adds the key 'Mean' to the output dictionary.
std (bool, default: False) – If True, calculate the standard deviation of the timeseries. Adds the key 'Standard Deviation' to the output dictionary.
rms (bool, default: False) – If True, calculate the root-mean-squared over all components combined, or if rms is a list, only using those components. Adds the key 'RMS' to the output dictionary.
n_observations (bool, default: False) – If True, count the number of observations (excluding NaNs) and NaNs. Adds the keys 'Observations' and 'Gaps' to the output dictionary.
std_outlier (int | float, default: 0) – If std_outlier > 0, count the number of non-NaN outliers, defined by the number of standard deviations they are away from the mean. Adds the key 'Outliers' to the output dictionary.
max_rolling_dev (int, default: 0) – If max_rolling_dev > 0, calculate the (sign-aware) maximum of the rolling deviation from the mean with window size max_rolling_dev for each component. If this is significantly larger than the standard deviation, this is an indicator of model inadequacies, as not all the data trends can be captured.

Return type

dict[str, ndarray]

Returns

Dictionary that includes the results as defined by the arguments. Empty by default.

fits

Dictionary of FitCollection objects associated with a timeseries saved in timeseries.

Example

If 'myts' is a timeseries saved in the station stat, and 'mymodel' is the name of a model that is associated with it, then the fitted timeseries is saved as:

stat.fits['myts']['mymodel']

get_arch()[source]

Build a dictionary describing the architecture of this station, to be used when creating a network JSON configuration file.

Return type: dict[str, Any]
Returns: Ditionary of attributes.

See also

disstans.network.Network.to_json: Export the Network configuration as a JSON file.
disstans.timeseries.Timeseries.get_arch: Get the architecture dictionary of a Timeseries instance.
disstans.models.Model.get_arch: Get the architecture dictionary of a Model instance.

get_trend(ts_description, fit_list=None, components=None, total=False, t_start=None, t_end=None, use_formal_variance=None, include_sigma=False, time_unit='D', ignore_missing=False)[source]

Calculates a linear trend through the desired model fits (or timeseries data) and over some time span.

Parameters

ts_description (str) – Timeseries whose fits to use.
fit_list (Optional[list[str]], default: None) – List of strings containing the model names of the subset of the fitted models to be used. None defaults to all fitted models. If ts_description the trend of the timeseries itself is to be calculated, pass an empty list ([]).
components (Optional[list[int]], default: None) – List of the numerical indices of which components of the timeseries to use. None defaults to all components.
total (bool, default: False) – By default, the function will return the trend per time_unit. If True, the function will instead give the total difference over the entire timespan.
t_start (UnionType[str, Timestamp, None], default: None) – Timestamp-convertible string of the start time. None defaults to the first timestamp present in the timeseries.
t_end (UnionType[str, Timestamp, None], default: None) – Timestamp-convertible string of the end time. None defaults to the last timestamp present in the timeseries.
use_formal_variance (Optional[bool], default: None) – By default, the trend fitting will use variance information if present. This usually makes sense for actual timeseries, but not for fitted models where the formal variance can be very unphysical. Setting this parameter overrides the default behavior.
include_sigma (bool, default: False) – If True, also calculate the formal standard deviation on the trend estimate.
time_unit (str, default: 'D') – Time unit for output (only required if total=False).
ignore_missing (bool, default: False) – By default, this method will throw an error if the timeseries or the models are not present in the station. Set to True if the method should return (None, None) instead (as done when the requested timespan is outside the observed one).

Return type

tuple[Optional[ndarray], Optional[ndarray]]

Returns

trend – 1D array of size len(components) containing the trends.
trend_sigma – 1D array of size len(components) containing the standard deviation of the trend estimate. Returns None if no standard deviations are available.

location: Location of the station (Latitude [°], Longitude [°], Altitude [m]).

models

Dictionary of ModelCollection objects associated with a timeseries saved in timeseries.

Example

If 'myts' is a timeseries saved in the station stat, then the model collection object for that timeseries is stored in:

stat.models['myts']

name: Name of the station.

remove_fit(ts_description, model_description)[source]

Remove a fit from a timeseries’ model.

Parameters

ts_description (str) – Timeseries to remove the fit from.
model_description (str) – Model description to remove the fit from.

Return type

None

remove_local_models(ts_description, model_descriptions, verbose=False)[source]

Remove models from a timeseries.

Parameters

ts_description (str) – Timeseries to remove the model from.
model_descriptions (str | list[str]) – Model description(s).
verbose (bool, default: False) – If True, raise a warning if a timeseries or model could not be found in the network.

Return type

None

remove_timeseries(ts_description)[source]

Remove a timeseries (including associated fits and models) from the station.

Parameters: ts_description (str) – Description of the timeseries.
Return type: None

See also

__delitem__: Shorthand notation wrapper.

Example

If stat is a Station instance, ts_description the ts_description of the timeseries to remove, then the following two are equivalent:

stat.remove_timeseries(ts_description)
del stat[ts_description]

sum_fits(ts_description, fit_list=None)[source]

Method to quickly sum fits of a timeseries.

Parameters

ts_description (str) – Timeseries whose fits to sum.
fit_list (Optional[list[str]], default: None) – List of strings containing the model names of the subset of the fitted models to be summed. None defaults to all fitted models.

Return type

tuple[ndarray, Optional[ndarray]]

Returns

fit_sum – 2D array of shape \((\text{n_observations},\text{n_components})\)
fit_sum_var – 2D array of shape \((\text{n_observations},\text{n_components})\). Returns None if no standard deviations are available.

timeseries: Dictionary of timeseries, where the keys are their string descriptions and the values are Timeseries instances.

property ts: dict[str, disstans.timeseries.Timeseries]: Abbreviation for timeseries.

unused_models: Same as models but for models whose timeseries is not present in timeseries.