Network

This module contains the Network class, which is the highest-level container object in DISSTANS.

class disstans.network.Network(name, default_location_path=None, auto_add=False, auto_add_filter=None, default_local_models={})[source]

Main class of DISSTANS. Contains information about the network, defines defaults, and most importantly, contains a dictionary of all stations in the network.

Parameters

name (str) – Name of the network.
default_location_path (Optional[str], default: None) – If station locations aren’t given directly, check for a file with this path for the station’s location. It needs to be an at-least four-column, space-separated text file with the entries name latitude[°] longitude[°] altitude[m]. Existing headers have to be able to be identified as not being floats in the coordinate columns.
auto_add (bool, default: False) – If true, instatiation will automatically add all stations found in default_location_path. If default_location_path is not set, this option is ignored.
auto_add_filter (Optional[bool], default: None) – If passed alongside default_location_path and auto_add, network instantiation will only add stations within the latitude, longitude polygon defined by auto_add_filter (shape \((\text{num_points}, \text{2})\)).
default_local_models (dict[str, Any], default: {}) – Add a default selection of models for the stations.

__contains__(name)[source]

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

Return type: bool

Example

If net is a Network instance, and we want to see whether 'mystat is in the network, the following two are equivalent:

# long version
'mystat` in net.stations
# short version
'mystat` in net

__delitem__(name)[source]

Convenience special function that allows a dictionary-like removing of stations from the network by wrapping remove_station(). :rtype: None

See also

remove_station: Remove a station from the network instance.

__getitem__(name)[source]

Convenience special function that provides a shorthand notation to access the network’s stations.

Parameters: name (str) – Name of the station.
Return type: Station
Returns: Station in network.

Example

If net is a Network instance and name the name of a station, the following two are equivalent:

net.stations[name]
net[name]

__iter__()[source]

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

Return type: Iterator[Station]

Example

If net is a Network instance, then the following two loops are equivalent:

# long version
for station in net.stations.values():
    pass
# shorthand
for station in net:
    pass

__len__()[source]

Special function that gives quick access to the number of stations in the network (num_stations) using Python’s built-in len() function to make interactions with iterators easier.

Return type: int

__setitem__(name, station)[source]

Convenience special function that allows a dictionary-like adding of stations to the network by wrapping add_station(). :rtype: None

See also

add_station: Add a station to the network instance.

__str__()[source]

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

Return type: str
Returns: Network summary.

add_default_local_models(ts_description, models=None)[source]

Add the network’s default local models (or a subset thereof) to all stations.

For example, this method can be used when instantiating a new network object from a JSON file using from_json() but skipping the adding of local models at that stage.

Parameters

ts_description (str) – Timeseries description to add the models to.
models (Optional[list[str]], default: None) – List of strings containing the model names of the subset of the default local models to add. Defaults to all local models.

Return type

None

See also

default_local_models: The network’s default list of models.

add_local_models(models, ts_description, station_subset=None)[source]

For each station in the network (or a subset thereof), add models to a timeseries using dictionary keywords.

Parameters

models (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 (see check_model_dict()).
ts_description (str) – Timeseries to add the models to.
station_subset (Optional[list[str]], default: None) – If provided, only add the models to the stations in this list.

Return type

None

add_station(name, station)[source]

Add a station to the network.

Parameters

name (str) – Name of the station.
station (Station) – Station object to add.

Return type

None

See also

__setitem__: Shorthand notation wrapper.

Example

If net is a Network instance, name the name of a new station, and station a Station instance, then the following two are equivalent:

net.add_station(name, station)
net[name] = station

add_unused_local_models(target_ts, hidden_ts=None, models=None)[source]

Add a station’s unused models (or subset thereof) to a target timeseries.

Unused models are models that have been defined for a specific timeseries at the import of a JSON file, but there is no associated information for that timeseries itself. Usually, this happens when after the network is loaded, the target timeseries still needs to be added.

Parameters

target_ts (str) – Timeseries description to add the models to.
hidden_ts (Optional[str], default: None) – Description of the timeseries that contains the unused model. None defaults to target_ts.
models (Optional[list[str]], default: None) – List of strings containing the model names of the subset of the default local models to add. None defaults to all hidden models.

Return type

None

ampphaseplot(ts_description, mdl_description, components=None, phase=True, fname=None, subset_stations=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, scale=1.0, annotate_stations=True, legend_refs=None, legend_labels=None, month_range=None, return_figure=False, save_kw_args={'format': 'png'}, colorbar_kw_args=None, gui_kw_args={})[source]

Plot the amplitude and phase of a Sinusoid model on a network map.

Parameters

ts_description – The name of the timeseries to be used.
mdl_description – The name of the model to be plotted.
components (default: None) – Specify the components to be used. By default (None), all available components are combined. If an integer, only a single component is used (in which case the phase can be used to color the marker). If a list, the indices of the list specify the components to be combined.
phase (default: True) – (Only used if a single component is selected.) If True, use the phase of the sinusoid to color the station markers.
fname (default: None) – If set, save the map to this filename, if not (default), show the map interactively (unless return_figure=True).
subset_stations (default: None) – If set, a list of strings that contains the names of stations to be shown.
lon_min (default: None) – Specify the map’s minimum longitude (in degrees).
lon_max (default: None) – Specify the map’s maximum longitude (in degrees).
lat_min (default: None) – Specify the map’s minimum latitude (in degrees).
lat_max (default: None) – Specify the map’s maximum latitude (in degrees).
scale (default: 1.0) – Scale factor for the markers.
annotate_stations (default: True) – If True, add the station names to the map. If a float or a string, add the station names to the map with the font size set as required by Text.
legend_refs (default: None) – If set, a list of amplitudes that will be used to generate legend entries.
legend_labels (default: None) – If set, a list of labels that will be used for legend_refs.
month_range (default: None) – By default, the phase range will be an entire year, and therefore circular. Pass a different range (in inclusive months, e.g., (5, 10) for all of May through all of October) to subset the range. This automatically switches to a non-circular colormap.
return_figure (default: False) – If True, return the figure and axis objects instead of showing the plot interactively. Only used if fname is not set.
save_kw_args (default: {'format': 'png'}) – Additional keyword arguments passed to savefig(), used when fname is specified.
colorbar_kw_args (default: None) – (Only used if a phases are plotted.) If None (default), no colorbar is added to the plot. If a dictionary is passed, a colorbar is added, with the dictionary containing additional keyword arguments to the colorbar() method.
gui_kw_args (default: {}) – Override default GUI settings of defaults.

Returns

(Only if return_figure=True) The Figure and Axis objects of the plot.

analyze_residuals(ts_description, **kw_args)[source]

Analyze residual timeseries for all stations and components, calling analyze_residuals().

Parameters

ts_description (str) – Timeseries to analyze. Method assumes it already is a residual.
**kw_args – Additional keyword arguments are directly passed on to analyze_residuals().

Return type

DataFrame

Returns

DataFrame with the station names as index, the different metrics as top-level columns, and the different components as lower-level columns. Averages of each metric can easily be calculated with the Pandas command mean().

call_func_no_return(func, no_pbar=False, **kw_args)[source]

A convenience wrapper that for each station in the network, calls a given function on each station. Also provides a progress bar.

Parameters

func (str | Callable) – Function to use. If provided with a string, will check for that function in processing, otherwise the function will be assumed to adhere to the same input format than the included ones.
no_pbar (bool, default: False) – Suppress the progress bar with True.
**kw_args – Additional keyword arguments to be passed onto func.

Return type

None

Example

If net is a Network instance, and func is the function to use, then the following two are equivalent:

# long version
for station in net:
    func(station, **kw_args)
# shorter version
net.call_func_no_return(func, **kw_args)
# shorter version, no need to import a disstans.processing function first
net.call_func_no_return('clean', **kw_args)

call_func_ts_return(func, ts_in, ts_out=None, no_pbar=False, **kw_args)[source]

A convenience wrapper that for each station in the network, calls a given function which takes timeseries as input and returns a timeseries (which is then added to the station). Also provides a progress bar. Will automatically use multiprocessing if parallelization has been enabled in the configuration (defaults to parallelization if possible).

Parameters

func (str | Callable) – Function to use. If provided with a string, will check for that function in processing, otherwise the function will be assumed to adhere to the same input and output format than the included ones.
ts_in (str) – Name of the timeseries to use as input to func.
ts_out (Optional[str], default: None) – Name of the timeseries that the output of func should be assigned to. None defaults to overwriting ts_in.
no_pbar (bool, default: False) – Suppress the progress bar with True.
**kw_args – Additional keyword arguments to be passed onto func.

Return type

None

Example

If net is a Network instance, 'input' and 'output' are the names of the input and output timeseries, respectively, and func is the function to use, then the following two are equivalent:

# long version, not parallelized
for station in net:
    ts_in = station.timeseries['input']
    ts_out = func(ts_in, **kw_args)
    station.add_timeseries('output', ts_out)
# short version, automatically parallelizes according to disstans.defaults
net.call_func_ts_return(func, 'input', ts_out='output', **kw_args)
# if using a disstans.processing function, no need to import that function
net.call_func_ts_return('clean', 'input', ts_out='output', **kw_args)

See also

defaults: Dictionary of settings, including parallelization.
disstans.tools.parallelize: Automatically execute a function in parallel or serial.

call_netwide_func(func, ts_in, ts_out=None, **kw_args)[source]

A convenience wrapper for functions that operate on an entire network’s timeseries at once.

Parameters

func (str | Callable) – Function to use. If provided with a string, will check for that function in processing, otherwise the function will be assumed to adhere to the same input and output format than the included ones.
ts_in (str) – Name of the timeseries to use as input to func.
ts_out (Optional[str], default: None) – Name of the timeseries that the output of func should be assigned to. None defaults to overwriting ts_in.
**kw_args – Additional keyword arguments to be passed onto func.

Return type

None

Example

If net is a Network instance, 'input' and 'output' are the names of the input and output timeseries, respectively, and func is the function to use, then the following two are equivalent:

# long version
net_in = net.export_network_ts('input')
net_out = func(net_in, **kw_args)
net.import_network_ts('output', net_out)
# short version
net.call_netwide_func(func, ts_in='input, ts_out='output', **kw_args)
# the short version also knows about the functions in disstans.processing
net.call_netwide_func('decompose', ts_in='input, ts_out='output', **kw_args)

See also

export_network_ts: Export the timeseries of all stations in the network.
import_network_ts: Import an entire netwrok’s timeseries and distribute to stations.

copy_uncertainties(origin_ts, target_ts)[source]

Convenience function that copies the uncertainties of one timeseries to another for all stations.

Parameters

origin_ts (str) – Name of the timeseries that contains the uncertainty data.
target_ts (str) – Name of the timeseries that should receive the uncertainty data.

Return type

None

create_station(name, location=None)[source]

Create a station and add it to the network.

Parameters

name (str) – Name of the station.
location (UnionType[list[float], ndarray, None], default: None) – Location (Latitude [°], Longitude [°], Altitude [m]) of the station. If None, the location information needs to be provided in default_location_path.

Raises

ValueError – If no location data is passed or found in default_location_path.

Return type

None

decompose(ts_in, ts_out=None, **decompose_kw_args)[source]

Decomposes a timeseries in the network and returns its best-fit models and spatiotemporal sources.

Parameters

ts_in (str) – Name of the timeseries to analyze.
ts_out (Optional[str], default: None) – If provided, save the model as a timeseries called ts_out to the stations in the network.
**decompose_kw_args – Additional keyword arguments passed to decompose().

Return type

tuple[dict[str, Timeseries], ndarray, dict[str, ndarray]]

Returns

model – Dictionary of best-fit models at each station and for each data component. The keys are the data components of the ts_in timeseries, and the values are Timeseries objects. The Timeseries objects have the station names as columns, and their observation record length is the joint length of all stations in the network, \(\text{num_observations}\). If a station is missing a certain timestamp, that value is NaN.
spatial – Dictionary of the spatial sources. Each key is one of the data components, and the values are ndarray objects of shape \((\text{num_components},\text{n_stations})\).
temporal – Dictionary of the temporal sources. Each key is one of the data components, and the values are ndarray objects of shape \((\text{num_observations},\text{num_components})\).

See also

disstans.processing.decompose: Function to get the individual components.

default_local_models

Dictionary of default station timeseries models of structure {model_name: {"type": modelclass, "kw_args": {**kw_args}}} that contains the names, types and necessary keyword arguments to create each model object.

These models can be added easily to all stations with add_default_local_models(), and will make the JSON export file cleaner.

Using update_default_local_models() to update the dictionary will perform input checks.

Example

If net is a Network instance, the following adds an annual Sinusoid model:

models = {"Annual": {"type": "Sinusoid",
                     "kw_args": {"period": 365.25,
                                 "t_reference": "2000-01-01"}}}
net.update_default_local_models(models)

default_location_path: Fallback path for station locations.

euler_rot_field(ts_description, mdl_description, comps=(0, 1), use_vars=True, use_covs=True, subset_stations=None, extrapolate=True)[source]

Calculate the best-fit Euler pole for a given timeseries’ model in the network, and compute the resulting velocities at each station. This function requires a Polynomial model to have been fitted to a timeseries in the network.

Wraps estimate_euler_pole().

Parameters

ts_description (str) – Name of the ts_description to use.
mdl_description (str) – Name of the Polynomial model that contains the estimated linear station velocities.
comps (tuple[int, int], default: (0, 1)) – Specifies the components of the fitted model to use as the East and North directions, respectively. Defaults to the first two components.
use_vars (bool, default: True) – If True, use the formal parameter variances in the model during the inversion. If False, all velocities will be weighted equally.
use_covs (bool, default: True) – If True and use_vars=True, also use the formal parameter covariance for the inversion.
subset_stations (Optional[list[str]], default: None) – If set, a list of strings that contains the names of stations to be used.
extrapolate (list[str] | bool, default: True) – If True, the velocity will be predicted for all stations in the network. If False, the prediction will only be made for the station subset being used in the inversion. Note that False is only different from True if subset_stations is set. If a list, the prediction will be made for the stations in the list. Note that no output will be made for stations that do not contain the passed 'ts_description' and 'mdl_description'.

Return type

tuple[DataFrame, ndarray, ndarray]

Returns

df_v_pred – DataFrame containing the Euler pole modeled velocities at each station (rows) in the East and North components (columns).
rotation_vector – Rotation vector [rad/time] containing the diagonals of the \(3 \times 3\) rotation matrix specifying the Euler pole in cartesian, ECEF coordinates.
rotation_covariance – Formal \(3 \times 3\) covariance matrix [rad^2/time^2] of the rotation vector.

See also

disstans.tools.rotvec2eulerpole: Convert from rotation vector and covariance matrix to Euler pole and covariance notation

evaluate(ts_description, timevector=None, output_description=None, progress_desc=None, no_pbar=False)[source]

Evaluate a timeseries’ models at all stations and adds them as a fit to the timeseries. Can optionally add the aggregate model as an independent timeseries to the station as well. Also provides a progress bar. Will automatically use multiprocessing if parallelization has been enabled in the configuration (defaults to parallelization if possible).

Parameters

ts_description (str) – Description of the timeseries to evaluate.
timevector (UnionType[Series, DatetimeIndex, None], default: None) – Series of Timestamp or alternatively a DatetimeIndex of when to evaluate the model. None defaults to the timestamps of the timeseries itself.
output_description (Optional[str], default: None) – If provided, add the sum of the evaluated models as a new timeseries to each station with the provided description (instead of only adding the model as a fit to the timeseries).
progress_desc (Optional[str], default: None) – If provided, override the description of the progress bar.
no_pbar (bool, default: False) – Suppress the progress bar with True.

Return type

None

Example

If net is a Network instance, 'mydata' is the timeseries to evaluate the models for, then the following two are equivalent:

# long version, not parallelized, and not creating a new independent timeseries
for station in net:
    station_ts = station.timeseries['mydata']
    fit_all = station_models.evaluate(station_ts)
    station.add_fit('mydata', fit_all)
    for (model_description, model) in station_models.items():
        fit = model.evaluate(station_ts)
        station.add_fit('mydata', fit, model_description)
# short version, automatically parallelizes according to disstans.defaults,
# and creating a new timeseries
net.evaluate('mydata', output_description='evaluated')

See also

fit: Fit models at all stations.
defaults: Dictionary of settings, including parallelization.
disstans.tools.parallelize: Automatically execute a function in parallel or serial.

export_network_ts(ts_description, subset_stations=None)[source]

Collects a specific timeseries from all stations and returns them in a dictionary of network-wide Timeseries objects.

Parameters

ts_description (str | (str, str)) – Timeseries description that will be collected from all stations in the network. If a tuple, specifies the timeseries and name of a fitted model for the timeseries at each station.
subset_stations (list[str] | None, default: None) – If set, this is a list of station names to include in the output, all other stations will be ignored.

Return type

dict[str, Timeseries]

Returns

Dictionary with the data components of the ts_description timeseries as keys and Timeseries objects as values (which will have in turn the station names as column names).

See also

import_network_ts: Inverse function.

fit(ts_description, solver='linear_regression', local_input={}, return_solutions=False, progress_desc=None, no_pbar=False, **kw_args)[source]

Fit the models for a specific timeseries at all stations, and read the fitted parameters into the station’s model collection. Also provides a progress bar. Will automatically use multiprocessing if parallelization has been enabled in the configuration (defaults to parallelization if possible).

Parameters

ts_description (str) – Description of the timeseries to fit.
solver (str | Callable, default: 'linear_regression') – Solver function to use. If given a string, will look for a solver with that name in solvers, otherwise will use the passed function as a solver (which needs to adhere to the same input/output structure as the included solver functions).
local_input (dict[str, Any], default: {}) – Provides the ability to pass individual keyword arguments to the solver, potentially overriding the (global) keywords in kw_args.
return_solutions (bool, default: False) – If True, return a dictionary of all solutions produced by the calls to the solver function.
progress_desc (bool, default: None) – If provided, override the description of the progress bar.
no_pbar (bool, default: False) – Suppress the progress bar with True.
**kw_args – Additional keyword arguments that are passed on to the solver function.

Return type

Optional[dict[str, Solution]]

Returns

If return_solutions=True, a dictionary that contains the Solution objects for each station.

Example

If net is a Network instance, 'mydata' is the timeseries to fit, and mysolver is the solver to use, then the following two are equivalent:

# long version, not parallelized
for station in net:
    station_ts = station.timeseries['mydata']
    station_models = station.models['mydata']
    sol = mysolver(station_ts, station_models, **kw_args)
    station_models.read_parameters(sol.parameters_zeroed, sol.covariances_zeroed)
# short version, automatically parallelizes according to disstans.defaults,
# also allows skipping the import of disstans.solvers
net.fit('mydata', solver='lasso_regression', **kw_args)

See also

evaluate: Evaluate the fitted models at all stations.
defaults: Dictionary of settings, including parallelization.
disstans.tools.parallelize: Automatically execute a function in parallel or serial.

fitevalres(ts_description, solver='linear_regression', local_input={}, return_solutions=False, timevector=None, output_description=None, residual_description=None, progress_desc=None, no_pbar=False, **kw_args)[source]

Convenience method that combines the calls for fit(), evaluate() and math() (to compute the fit residual) into one method call.

Parameters

ts_description (str) – See fit() and evaluate().
solver (str | Callable, default: 'linear_regression') – See fit().
local_input (dict[str, Any], default: {}) – See fit().
return_solutions (bool, default: False) – See fit().
timevector (UnionType[Series, DatetimeIndex, None], default: None) – See evaluate().
output_description (Optional[str], default: None) – See evaluate().
residual_description (Optional[str], default: None) – If provided, calculate the residual as the difference between the data and the model fit, and store it as the timeseries residual_description.
progress_desc (Optional[tuple[Optional[str], Optional[str]]], default: None) – If provided, set progress_desc of fit() and evaluate() using the first or second element of a tuple, respectively. Leave None if only overriding one of them.
no_pbar (bool, default: False) – Suppress the progress bars with True.
**kw_args – Additional keyword arguments that are passed on to the solver function, see fit().

Return type

Optional[dict[str, Solution]]

Returns

If return_solutions=True, a dictionary that contains the Solution objects for each station.

Example

If net is a Network instance, 'mydata' is the timeseries to fit and evaluate the models for, mysolver is the solver to use, 'myfit' should contain the model fit, and the residuals should be put into the timeseries 'myres', then the following two are equivalent:

# three-line version
net.fit('mydata', solver=mysolver, **kw_args)
net.evaluate('mydata', output_description='myfit')
net.math('myres', 'mydata', '-', 'myfit')
# one-liner
net.fitevalres('mydata', solver=mysolver, output_description='myfit',
               residual_description='myres')

See also

evaluate: Evaluate the fitted models at all stations.
fit: Fit models at all stations.
defaults: Dictionary of settings, including parallelization.
disstans.tools.parallelize: Automatically execute a function in parallel or serial.

freeze(ts_description, model_list=None, zero_threshold=1e-10)[source]

Convenience method that calls freeze() for the ModelCollection for a certain timeseries at every station.

Parameters

ts_description (str) – Description of the timeseries to to freeze the models for.
model_list (Optional[list[str]], default: None) – If None, freeze all models. If a list of strings, only freeze the corresponding models in the collection.
zero_threshold (float, default: 1e-10) – Model parameters with absolute values below zero_threshold will be set to zero and set inactive.

Return type

None

See also

unfreeze: The reverse network method.

classmethod from_json(path, add_default_local_models=True, no_pbar=False, station_kw_args={}, timeseries_kw_args={})[source]

Create a Network instance from a JSON configuration file.

Parameters

path (str) – Path of input JSON file.
add_default_local_models (bool, default: True) – If false, skip the adding of any default local model found in a station.
no_pbar (bool, default: False) – Suppress the progress bar with True.
station_kw_args (dict[str, Any], default: {}) – Additional keyword arguments passed on to the Station constructor.
timeseries_kw_args (dict[str, Any], default: {}) – Additional keyword arguments passed on to the Timeseries constructor.

Return type

Network

Returns

Network instance.

See also

to_json: Export a network configuration to a JSON file.

get_stations_with(ts_description, mdl_description=None)[source]

Return the list of all station names that contain a given timeseries (and optionally, a model).

Parameters

ts_description (str) – Name of the timeseries that the stations should contain.
mdl_description (Optional[str], default: None) – Name of the model that the stations’ timeseries should contain.

Return type

list[str]

Returns

Names of stations.

graphical_cme(ts_in, ts_out=None, annotate_stations=True, save=False, save_kw_args={'format': 'png'}, gui_kw_args={}, **decompose_kw_args)[source]

Calculates the Common Mode Error (CME) of the network and shows its spatial and temporal pattern. Optionally saves the model for each station.

Parameters

ts_in (str) – Name of the timeseries to analyze.
ts_out (Optional[str], default: None) – If provided, save the model as a timeseries called ts_out to the stations in the network.
annotate_stations (bool | str | float, default: True) – If True, add the station names to the map. If a float or a string, add the station names to the map with the font size set as required by Text.
save (bool, default: False) – If True, save the map and timeseries plots to the current folder.
save_kw_args (dict[str, Any], default: {'format': 'png'}) – Additional keyword arguments passed to savefig(), used when save=True.
gui_kw_args (dict[str, Any], default: {}) – Override default GUI settings of defaults.
**decompose_kw_args – Additional keyword arguments passed to decompose().

Return type

None

See also

decompose: Decomposer method to calculate the CME.

gui(station=None, timeseries=None, fit_list=None, sum_models=True, verbose=False, annotate_stations=True, save=False, save_map=False, save_kw_args={'format': 'png'}, scalogram_kw_args=None, mark_events=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, stepdetector={}, trend_kw_args={}, analyze_kw_args={}, rms_on_map={}, gui_kw_args={})[source]

Provides a Graphical User Interface (GUI) to visualize the network and all of its different stations, timeseries, and models.

In its base form, this function will show

a window with a map of all stations, underlain optionally with coastlines and/or imagery, and
another window which will show a station’s timeseries including all fitted models.

Stations are selected by clicking on their markers on the map. Optionally, this function can

start with a station pre-selected,
show only a subset of fitted models,
sum the models to an aggregate one,
mark events associated with a station’s timeseries,
restrict the output to a timewindow showing potential steps from multiple sources,
color the station markers by RMS and include a colormap,
show a scalogram (Model class permitting),
save the output timeseries (and scalogram) as an image,
print statistics of residuals, and
print station information.

Parameters

station (Optional[str], default: None) – Pre-select a station.
timeseries (UnionType[str, list[str], None], default: None) – String or list of strings with the descriptions of the timeseries to plot. None defaults to all timeseries.
fit_list (Optional[list[str]], default: None) – List of strings containing the model names of the subset of the models to be plotted. None defaults to all fitted models.
sum_models (bool, default: True) – If True, plot the sum of all selected models instead of every model individually.
verbose (bool, default: False) – If True, when clicking on a station, print its details (see __str__()).
annotate_stations (bool | str | float, default: True) – If True, add the station names to the map. If a float or a string, add the station names to the map with the font size set as required by Text.
save (bool | str, default: False) – If True, save the figure of the selected timeseries. If a scalogram is also created, save this as well. The output directory is the current folder. Ignored if stepdetector is set. Suppresses all interactive figures. If save is a string, it will be included in the output file name for easier referencing.
save_map (bool, default: False) – If True, also save a map if save=True.
save_kw_args (dict[str, Any], default: {'format': 'png'}) – Additional keyword arguments passed to savefig(), used when save=True.
scalogram_kw_args (Optional[dict[str, Any]], default: None) – If passed, also plot a scalogram. None defaults to no scalogram shown. The dictionary has to contain 'ts' and 'model' keys. The string values are the names of the timeseries and associated model that are of the BaseSplineSet class, and therefore have a make_scalogram() method.
mark_events (UnionType[DataFrame, list[DataFrame], None], default: None) – If passed, a DataFrame or list of DataFrames that contain the columns 'station' and 'time'. For each timestamp, a vertical line is plotted onto the station’s timeseries and the relevant entries are printed out.
lon_min (Optional[float], default: None) – Specify the map’s minimum longitude (in degrees).
lon_max (Optional[float], default: None) – Specify the map’s maximum longitude (in degrees).
lat_min (Optional[float], default: None) – Specify the map’s minimum latitude (in degrees).
lat_max (Optional[float], default: None) – Specify the map’s maximum latitude (in degrees).
stepdetector (dict[str, Any], default: {}) – Passing this dictionary will enable the plotting of events related to possible steps, both on the map (in case of an earthquake catalog) and in the timeseries (in case of detected steps by StepDetector or a maintenance catalog). To reduce cluttering, it will also only show a subset of each timeseries, centered around consecutive probable steps. Using the terminal, one can cycle through each period. The stepdetector dictionary must contain the keys 'plot_padding' (which determines how many days before and after to include in the plotting), 'step_table' and 'step_ranges' (both returned by search_network()), 'step_padding' (which determines how many days before and after the 'step_ranges' should be scanned for possible steps), optionally 'catalog' and 'eqcircle' (an earthquake catalog of same style as used in earthquakes and a maximum distance of stations to earthquakes of magnitude less than 7.5), and optionally, 'maint_table' (a maintenance table as parsed by parse_maintenance_table()).
trend_kw_args (dict[str, Any], default: {}) – If passed, also plot velocity trends on the station map. {} defaults to no velocity arrows shown. The dictionary can contain all the keywords that are passed to get_trend(), but has at least has to contain the ts_description. If no fit_list is included, the fit_list passed to gui() will be used instead. If the number of components available is 3 or more, only the first two will be used. If two components are plotted, they correspond to the East and North components. If only one component is plotted (for example for vertical motion), it will be plotted as the North component.
analyze_kw_args (dict[str, Any], default: {}) – If provided and non-empty, call analyze_residuals() and pass the dictionary on as keyword arguments (overriding 'verbose' to True to force an output). {} defaults to no residual analysis.
rms_on_map (dict[str, Any], default: {}) – If provided and non-empty, this option will call analyze_residuals() to calculate a residual timeseries’ root-mean-squares to color the station markers on the map. The dictionary must include the key 'ts' (the residual timeseries’ name), and can optionally include the keys 'comps' (a list of components to combine for the RMS, defaults to all components), 'c_max' (maximum colormap range, defaults to maximum of the RMS), 't_start', 't_end' (to restrict the time window, defaults to analyze_kw_args if given, otherwise the entire timeseries), and 'orientation' (for the colorbar orientation).
gui_kw_args (dict[str, Any], default: {}) – Override default GUI settings of defaults.

Return type

None

hom_velocity_field(ts_description, mdl_description, comps=(0, 1), use_vars=True, use_covs=True, utmzone=None, subset_stations=None, extrapolate=True, reference_station=None, use_parts=(True, True, True))[source]

Assuming the entire network (or a subset thereof) is located on the same body undergoing translation, strain and rotation, calculate the homogenous velocity field as well as the horizontal strain and rotation rate tensors. This function requires a Polynomial model to have been fitted to a timeseries in the network.

Wraps get_hom_vel_strain_rot().

Parameters

ts_description (str) – Name of the timeseries to use.
mdl_description (str) – Name of the Polynomial model that contains the estimated linear station velocities.
comps (tuple[int, int], default: (0, 1)) – Specifies the components of the fitted model to use as the East and North directions, respectively. Defaults to the first two components.
use_vars (bool, default: True) – If True, use the formal parameter variances in the model during the inversion. If False, all velocities will be weighted equally.
use_covs (bool, default: True) – If True and use_vars=True, also use the formal parameter covariance for the inversion.
utmzome – If provided, the UTM zone to use for the horizontal approximation. By default (None), the average longitude will be calculated, and the respective UTM zone will be used.
subset_stations (Optional[list[str]], default: None) – If set, a list of strings that contains the names of stations to be used.
extrapolate (list[str] | bool, default: True) – If True, the velocity will be predicted for all stations in the network. If False, the prediction will only be made for the station subset being used in the inversion. Note that False is only different from True if subset_stations is set. If a list, the prediction will be made for the stations in the list. Note that no output will be made for stations that do not contain the passed 'ts_description' and 'mdl_description'.
reference_station (Optional[str], default: None) – Reference station to be used by the calculation. If all parts are removed (translation, rotation, strain), the reference station is not relevant, otherwise, it changes the results significantly. None defaults to the first station in the Network.
use_parts (tuple[bool, bool, bool], default: (True, True, True)) – By default, all three parts are used in the calculation of the best-fit average velocity field: translation, strain relative to the origin, and rotation about the origin. By changing this list of booleans, the individual parts can be turned on and off, e.g., setting the third element to False will return a predicted velocity only composed of the translation and strain parts.

Return type

tuple[DataFrame, ndarray, ndarray, ndarray]

Returns

df_v_pred – DataFrame containing the predicted velocities at each station (rows) in the East and North components (columns).
v_O – 1D translation vector.
epsilon – 2D strain rate tensor.
omega – 2D rotation rate tensor.

See also

disstans.tools.strain_rotation_invariants: Use the strain and rotation rate tensors to calculate invariants such as the dilatation or shearing rates.

import_network_ts(ts_description, dict_of_timeseries)[source]

Distributes a dictionary of network-wide Timeseries objects onto the network stations.

Parameters

ts_description (str) – Timeseries description where the data will be placed.
dict_of_timeseries (dict[str, Timeseries]) – Dictionary with the data components of the ts_description timeseries as keys and Timeseries objects as values (which will have in turn the station names as column names).

Return type

None

See also

export_network_ts: Inverse function.

load_maintenance_dict(maint_dict, ts_description, model_description, only_active=True)[source]

Convenience wrapper to add Step models to the stations in the network where they experienced maitenance and therefore likely a jump in station coordinates.

Parameters

maint_dict (dict[str, list]) – Dictionary of structure {station_name: [steptimes]} where station_name is the station name as present in the Network object, and steptimes is a list of either datetime-like strings or Timestamp.
ts_description (str) – Timeseries to add the steps to.
model_description (str) – Name for the step models.
only_active (bool, default: True) – If True, will check for the active time period of the timeseries, and only add steps that fall inside it.

Return type

None

See also

Step: Model used to add steps.

math(result, left, operator, right)[source]

Convenience method that performs simple math for all stations. Syntax is result = left operator right.

Parameters

result (str) – Name of the result timeseries.
left (str) – Name of the left timeseries.
operator (Literal['+', '-', '*', '/']) – Operator symbol (see prepare_math() for all supported operations).
right (str) – Name of the right timeseries.

Return type

None

Example

If net is a Network instance, and we want to calculate the residual 'res' between the data in timeseries 'data' and the model in the timeseries 'model', then the following two are equivalent:

# long version
for station in net:
    station['res'] = station['data'] - station['model']

# short version
net.math('res', 'data', '-', 'model')

property mean_longitude: Mean longitude [°] of all stations

name: Network name.

property num_stations: int: Number of stations present in the network.

plot_availability(ts_description, sampling=Timedelta('1 days 00:00:00'), sort_by_latitude=True, saveas=None)[source]

Create an availability figure for the network.

Parameters

ts_description (str) – The name of the timeseries to be used.
sampling (Timedelta, default: Timedelta('1 days 00:00:00')) – Assume that breaks strictly larger than sampling constitute a data gap.
sort_by_latitude (bool, default: True) – If True, sort the stations by latitude, else alphabetical. (Always falls back to alphabetical if location information is missing.)
saveas (Optional[str], default: None) – If provided, the figure will be saved at this location.

Return type

None

remove_station(name)[source]

Remove a station from the network.

Parameters: name (str) – Name of the station.
Return type: None

See also

__delitem__: Shorthand notation wrapper.

Example

If net is a Network instance and name is the name of an existing station, then the following two are equivalent:

net.remove_station(name)
del net[name]

remove_timeseries(*ts_to_remove)[source]

Convenience function that scans all stations for timeseries of given names and removes them (together with models and fits).

Parameters: *ts_to_remove (str) – Pass all timeseries to remove as function arguments.
Return type: None

See also

disstans.station.Station.remove_timeseries: Station-specific equivalent

spatialfit(ts_description, penalty, reweight_func, spatial_l0_models, spatial_reweight_iters, spatial_reweight_percentile=0.5, spatial_reweight_max_rms=1e-09, spatial_reweight_max_changed=0.0, spatial_reweight_agg_comps=True, dist_num_avg=4, dist_weight_min=None, dist_weight_max=None, local_l0_models=[], local_reweight_iters=1, local_reweight_coupled=True, formal_covariance=False, use_data_variance=True, use_data_covariance=True, use_internal_scales=True, verbose=False, no_pbar=False, extended_stats=False, keep_mdl_res_as=None, return_solutions=False, zero_threshold=0.0001, cov_zero_threshold=1e-06, num_threads_evaluate=None, roll_mean_kernel=30, cvxpy_kw_args={'solver': 'SCS'})[source]

Fit the models for a specific timeseries at all stations using the spatiotemporal capabilities of lasso_regression(), and read the fitted parameters into the station’s model collection. Also provides a progress bar. Will automatically use multiprocessing if parallelization has been enabled in the configuration (defaults to parallelization if possible).

The function solve the network-wide fitting problem as proposed by [riel14]:

Fit the models individually using a single iteration step from lasso_regression().

Collect the L0 weights \(\mathbf{w}^{(i)}_j\) after iteration \(i\) from each station \(j\).

Spatially combine the weights, and redistribute them to the stations for the next iteration.

Repeat from 1.

The iteration can stop early if either the conditions set by spatial_reweight_max_rms or spatial_reweight_max_changed are satisfied, for all models in spatial_l0_models.

In the third step, a distance-weighted median is used at each station to combine the L0 regularization weights \(\mathbf{w}^{(i)}_j\). The distance weights \(v_{j,k}\) from station \(j\) to station \(k\) are based on the average distance \(D_j\) from the station in question to the dist_num_avg closest stations, following an exponential curve: \(v_{j,k}=\exp \left( - r_{j,k} / D_j \right)\) where \(r_{j,k}\) is the distance between the stations \(j\) and \(k\). dist_weight_min and dist_weight_max allow to set boundaries for \(D_j\).

Parameters

ts_description (str) – Description of the timeseries to fit.
penalty (float | list[float] | ndarray) – Penalty hyperparameter \(\lambda\). For non-reweighted models (i.e., regularized models that are neither in spatial_l0_models nor in local_l0_models), this is the constant penalty applied for every iteration. For the reweighted models, and if local_reweight_coupled=True (default), this is just the penalty at the first iteration. After that, the penalties are largely controlled by reweight_func. If local_reweight_coupled=False, the penalty is applied on top of the updated weights at each iteration. penalty can either be a single value used for all components, or a list or NumPy array specifying a penalty for each component in the data.
reweight_func (Callable) – An instance of a reweighting function that will be used by lasso_regression().
spatial_l0_models (list[str]) – Names of models to use in the spatial reweighting, resulting in spatial L0 regularization.
spatial_reweight_iters (int) – Number of spatial reweighting iterations.
spatial_reweight_percentile (float, default: 0.5) – Percentile used in the spatial reweighting.
spatial_reweight_max_rms (float, default: 1e-09) – Stop the spatial iterations early if the difference in the RMS (Root Mean Square) of the change of the parameters between reweighting iterations is less than spatial_reweight_max_rms.
spatial_reweight_max_changed (float, default: 0.0) – Stop the spatial iterations early if the number of changed parameters (i.e., flipped between zero and non-zero) falls below a threshold. The threshold spatial_reweight_max_changed is given as the percentage of changed over total parameters (including all models and components). 0.0 defaults to no early stopping.
spatial_reweight_agg_comps (bool, default: True) – If False, the spatial reweighting is done individually for each component, i.e., the distance-weighted median of the weights will be calculated for each component. If True, a single median is calculated from the aggregated weights in all data components, and then used for all components.
dist_num_avg (int, default: 4) – Calculate the characteristic distance for the drop-off of station weights as the average of the dist_num_avg closest stations .
dist_weight_min (Optional[float], default: None) – Enforce a minimum value of \(D_j\) (in kilometers).
dist_weight_max (Optional[float], default: None) – Enforce a maximum value of \(D_j\) (in kilometers).
local_l0_models (list[str], default: []) – Names of models that should carry over their weights from one solver iteration to the next, but should not be reweighted spatially, resulting in local L0 regularization.
local_reweight_iters (int, default: 1) – Number of local reweighting iterations, see reweight_max_iters in lasso_regression().
local_reweight_coupled (bool, default: True) – If True and reweighting is active, the L1 penalty hyperparameter is coupled with the reweighting weights (see Notes in lasso_regression()).
formal_covariance (bool, default: False) – If True, calculate the formal model covariance.
use_data_variance (bool, default: True) – If True and ts_description contains variance information, this uncertainty information will be used.
use_data_covariance (bool, default: True) – If True, ts_description contains variance and covariance information, and use_data_variance is also True, this uncertainty information will be used.
use_internal_scales (bool, default: True) – Sets whether internal scaling should be used when reweighting, see use_internal_scales in lasso_regression().
verbose (bool, default: False) – If True, print statistics along the way.
no_pbar (bool, default: False) – Suppress the progress bars with True.
extended_stats (bool, default: False) – If True, the fitted models are evaluated at each iteration to calculate residual and fit statistics. These extended statistics are added to statistics (see Returns below).
keep_mdl_res_as (tuple[str, str], default: None) – If extended_stats=True, the network’s models are evaluated, and a model fit and residuals timeseries are created. Between iterations, they are removed by default, but passing this parameter a 2-element tuple of strings keeps the evaluated model and residual timeseries after the last iteration. This effectively allows the user to skip evaluate() (for output_description) and the calculation of the residual as done with residual_description by fitevalres() after finishing the spatial fitting.
return_solutions (bool, default: False) – If True, return a dictionary of all solutions produced by the calls to the solver function.
zero_threshold (float, default: 0.0001) – When calculating statistics, assume parameters with absolute values smaller than zero_threshold are effectively zero.
cov_zero_threshold (float, default: 1e-06) – Covariance zero threshold, see lasso_regression().
num_threads_evaluate (Optional[int], default: None) – If extended_stats=True and formal_covariance=True, there will be calls to evaluate() that will estimate the predicted variance, which will be memory-intensive if the timeseries are long. Using the same number of threads as defined in defaults might therefore exceed the available memory on the system. This option allows to set a different number of threads or disable parallelized processing entirely for those calls. Defaults to None, which uses the same setting as in the defaults.
roll_mean_kernel (int, default: 30) – Only used if extended_stats=True. This is the kernel size that gets used in the analysis of the residuals between each fitting step.
cvxpy_kw_args (dict, default: {'solver': 'SCS'}) – Additional keyword arguments passed on to CVXPY’s solve() function, see cvxpy_kw_args in lasso_regression().

Return type

tuple[dict[str, Any], Optional[dict[str, Solution]]]

Returns

statistics – See the Notes for an explanation of the solution and convergence statistics that are returned.
solutions – If return_solutions=True, a dictionary that contains the Solution objects for each station.

Notes

The statistics dictionary contains the following entries:

'num_total' (int): Total number of parameters that were reweighted.
'arr_uniques' (ndarray): Array of shape \((\text{spatial_reweight_iters}+1, \text{num_components})\) of the number of unique (i.e., over all stations) parameters that are non-zero for each iteration.
'list_nonzeros' (list): List of the total number of non-zero parameters for each iteration.
'dict_rms_diff' (dict): Dictionary that for each reweighted model and contains a list (of length spatial_reweight_iters) of the RMS differences of the reweighted parameter values between spatial iterations.
'dict_num_changed' (dict): Dictionary that for each reweighted model and contains a list (of length spatial_reweight_iters) of the number of reweighted parameters that changed from zero to non-zero or vice-versa.
'list_res_stats' (list): (Only present if extended_stats=True.) List of the results dataframe returned by analyze_residuals() for each iteration.
'dict_cors' (dict): (Only present if extended_stats=True.) For each of the reweighting models, contains a list of spatial correlation matrices for each iteration and component. E.g., the correlation matrix for model 'my_model' after 5 reweighting iterations (i.e. the sixth solution, taking into account the initial unweighted solution) for the first component can be found in statistics['dict_cors']['my_model'][5][0] and has a shape of \((\text{num_stations}, \text{num_stations})\).
'dict_cors_means' (dict): (Only present if extended_stats=True.) Same shape as 'dict_cors', but containing the average of the upper triagonal parts of the spatial correlation matrices (i.e. for each model, iteration, and component).

References

riel14: Riel, B., Simons, M., Agram, P., & Zhan, Z. (2014). Detecting transient signals in geodetic time series using sparse estimation techniques. Journal of Geophysical Research: Solid Earth, 119(6), 5140–5160. doi:10.1002/2014JB011077

property station_locations: DataFrame: DataFrame of all locations for all stations in the network.

property station_names: list[str]: Names of stations present in the network.

stations: Dictionary of network stations, where the keys are their string names and the values are their Station objects.

to_json(path)[source]

Export network configuration to a JSON file.

Parameters: path (str) – Path of output JSON file.
Return type: None

See also

from_json: Create a Network instance from a JSON configuration file.

unfreeze(ts_description, model_list=None)[source]

Convenience method that resets any frozen parameters for a certain timeseries at every station.

Parameters

ts_description (str) – Description of the timeseries to to unfreeze the models for.
model_list (Optional[list[str]], default: None) – If None, unfreeze all models. If a list of strings, only unfreeze the corresponding models in the collection.

Return type

None

See also

freeze: The reverse network method.

update_default_local_models(models)[source]

Perform input checks for the structure of models and if successful, update default_local_models.

Parameters: models (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 (see check_model_dict()).
Return type: None

wormplot(ts_description, fname=None, fname_animation=None, subset_stations=None, t_min=None, t_max=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, en_col_names=(0, 1), scale=100.0, interval=10, annotate_stations=True, no_pbar=False, return_figure=False, save_kw_args={'format': 'png'}, colorbar_kw_args=None, legend_ref_dict=None, gui_kw_args={})[source]

Creates an animated worm plot given the data in a timeseries.

Parameters

ts_description – Specifies the timeseries to plot. If a string, the name of a timeseries directly associated with a station, and if a tuple, specifies the timeseries and name of a fitted model for the timeseries.
fname (default: None) – If set, save the map to this filename, if not (default), show the map interactively (unless return_figure=True).
fname_animation (default: None) – If specified, make an animation and save the video to this filename.
subset_stations (default: None) – If set, a list of strings that contains the names of stations to be shown.
t_min (default: None) – Start the plot at this time. None defaults to first observation.
t_max (default: None) – End the plot at this time. None defaults to last observation.
lon_min (default: None) – Specify the map’s minimum longitude (in degrees).
lon_max (default: None) – Specify the map’s maximum longitude (in degrees).
lat_min (default: None) – Specify the map’s minimum latitude (in degrees).
lat_max (default: None) – Specify the map’s maximum latitude (in degrees).
en_col_names (default: (0, 1)) – By default, the first two components of the timeseries will be assumed to be the East and North components, respectively, by having the default value (0, 1) indicating the desired components as integer indices. Alternatively, this can be a tuple of strings with the two component’s column names.
scale (default: 100.0) – Specify the conversion scale factor for the displacement timeseries to be visible on a map. The final distance for a unit displacement on the map will be (timeseries assumed as meters) times (scale). E.g., for a timeseries in millimeters and a scale of 1e2, one millimeter displacement will result in a mapped displacement of 100 meters.
interval (default: 10) – The number of milliseconds each frame is shown.
annotate_stations (default: True) – If True, add the station names to the map. If a float or a string, add the station names to the map with the font size set as required by Text.
no_pbar (default: False) – Suppress the progress bar when creating the animation with True.
return_figure (default: False) – If True, return the figure and axis objects instead of showing the plot interactively. Only used if fname is not set.
save_kw_args (default: {'format': 'png'}) – Additional keyword arguments passed to savefig(), used when fname is specified.
colorbar_kw_args (default: None) – If None, no colorbar is added to the plot. If a dictionary is passed, a colorbar is added, with the dictionary containing additional keyword arguments to the colorbar() method.
legend_ref_dict (default: None) – If legend_ref_dict is provided and contains all of the following information, a reference line will be plotted at the specified location to act as a legend. Necessary keys: location (a tuple containing the longitude and latitude of the reference line), length (the length of the line in meters) and label (a label placed below the line). The dictionary can optionally include rect_args and rect_kw_args entries for arguments and parameters that will be passed onto the creation of the background Rectangle.
gui_kw_args (default: {}) – Override default GUI settings of defaults.

Returns

(Only if return_figure=True) The Figure and Axis objects of the plot.