Version:

salvus.flow.collections.event_data

salvus.flow.collections.event_data salvus flow collections event_data
The EventData object which is an Event object with waveform data and/or other types of attached data.

Functions

plot_event_data_gathers()

Plot a custom gather using a list of event_data objects.
SIGNATURE
def plot_event_data_gathers(
    event_data_objects: list[EventData],
    receiver_field: str,
    component: str,
    event_data_labels: str | list[str] | None = None,
    sort_by: typing.Callable | None = None,
    filter_by: typing.Callable[[_Base], bool] | None = None,
    select_by: (
        typing.Callable[
            [list[tuple[_Base, obspy.Stream]], EventData],
            list[tuple[_Base, obspy.Stream]],
        ]
        | None
    ) = None,
    interleave: bool = False,
    colors: list[typing.Any] | None = None,
    alpha: float | None = None,
    plot_using: PlotProperties | mpl.axes.Axes = PlotProperties(
        width=11.5, height=6.33, dpi=100
    ),
    fast_unsafe: bool = False,
) -> mpl.axes.Axes: ...
ARGUMENTS
Required
event_data_objects
Type:list[EventData]
Description:
A list of the event data objects to use.
Required
receiver_field
Type:str
Description:
The receiver field to plot.
Required
component
Type:str
Description:
The component to plot.
Optional
event_data_labels
Type:str | list[str] | None
Default value:None
Description:
Data name or list of data names to plot. This variable will simply be used for the labelling of the data in the event_data_objects list. If not specified, names will be generated from the event_data_objects list.
Optional
sort_by
Type:typing.Callable | None
Default value:None
Description:
Callback function called with the receiver objects to determine the sorting. Works like the key callback for the standard Python sorted() method.
Optional
filter_by
Type:typing.Callable[[_Base], bool] | None
Default value:None
Description:
Callback function called with the receiver objects in internal Salvus format to determine the filtering. Works like the callback for the standard Python filter() method. For complex filter operations requiring all receivers, defer to the select_by method.
Optional
select_by
Type:typing.Callable[[list[tuple[_Base, obspy.Stream]], EventData], list[tuple[_Base, obspy.Stream]]] | None
Default value:None
Description:
Callback function called with a list of tuples in the receiver objects in both internal Salvus and ObsPy Stream format, as well as the EventData objects.
Optional
interleave
Type:bool
Default value:False
Description:
Whether or not to alternatingly plot data. If false, traces from all data will be plotted on top of each other.
Optional
colors
Type:list[typing.Any] | None
Default value:None
Description:
The colors for the individual traces. Must be exactly as many colors as data items. If not given, it will attempt to choose suitable colors.
Optional
alpha
Type:float | None
Default value:None
Description:
The opacity of all data, as used in Matplotlib. useful when setting interleave to false.
Optional
plot_using
Type:PlotProperties | mpl.axes.Axes
Default value:PlotProperties(width=11.5, height=6.33, dpi=100)
Description:
The configuration of the axis to create or reuse. Will default to the standard size as defined in the PlotProperties dataclass.
Optional
fast_unsafe
Type:bool
Default value:False
Description:
Collect data on the largest instead of smallest time step. Will potentially alias data if largest time step of the event data objects is larger than the highest relevant frequencies across the data, but does speed up plotting in cases where time axes are restrictive, e.g. simulations with relatively many time steps, which would normally lead to massive interpolation expense.
RETURNS
Return type: mpl.axes.Axes

Classes

EventData

An event object that also contains waveform data.
SIGNATURE
class EventData(salvus.flow.collections.event.Event):
    def __init__(
        self,
        event: Event,
        data: pathlib.Path | dict | xr.Dataset | xr.DataArray,
        data_hash: str | None = None,
        path_to_meta_json: pathlib.Path | None = None,
        path_to_job_info_json: pathlib.Path | None = None,
    ): ...
ARGUMENTS
Required
event
Type:Event
Description:
The event object.
Required
data
Type:pathlib.Path | dict | xr.Dataset | xr.DataArray
Description:
Path to the actual waveform data or a dictionary describing the data.
Optional
data_hash
Type:str | None
Default value:None
Description:
Uniquely identifying hash of that pieces of data. Might not always be available.
Optional
path_to_meta_json
Type:pathlib.Path | None
Default value:None
Description:
Optionally specify the meta.json path of the run. Necessary if you later want to compute adjoint sources.
Optional
path_to_job_info_json
Type:pathlib.Path | None
Default value:None
Description:
Optionally specify the job_info.json path of the run.

Properties

  • data(_Backends)-Access the actual data via a proxy that abstracts different file formats.
  • file_format(str)-Returns the file format, either `"hdf5"`, `"xarray"`, or `"asdf"`.
  • is_synthetic(bool)-Is the data from a Salvus simulation?
  • job_info_json_contents(dict | None)-Contents of the job_info.json file.
  • meta_json_contents(dict | None)-Contents of the meta.json file.
  • path_to_meta_json(pathlib.Path | None)-Path to the meta.json file for the simulation that created the data. Can be None for observed data.
  • receiver_channels(list[ReceiverChannel])-The receiver channels for this event.
  • receiver_name_list(list[str])-Return a list of receiver names for this event.
  • receivers(list[simple_config.receiver._Base])-The receivers for this event.
  • sources(list[simple_config.source._Base])-The sources for this event.

Class Methods

EventData.from_output_folder()
Construct an EventData object from a folder containing Salvus outputs.
SIGNATURE
def from_output_folder(output_folder: pathlib.Path) -> EventData: ...
ARGUMENTS
Required
output_folder
Type:pathlib.Path
Description:
Folder where the output files are stored.
EventData.from_output_hdf5_file()
Construct an EventData object from an HDF5 file containing Salvus outputs.
SIGNATURE
def from_output_hdf5_file(filename: pathlib.Path) -> EventData: ...
ARGUMENTS
Required
filename
Type:pathlib.Path
Description:
File where the output data are stored.

Methods

EventData.compute_data_hash()
Compute a unique hash for the event data.
SIGNATURE
def compute_data_hash(self) -> str: ...
EventData.delete_associated_job_and_data()
Delete the associated Salvus job, if it still exists, and any potentially existing remote outputs.
SIGNATURE
def delete_associated_job_and_data(self) -> None: ...
EventData.download_extra_outputs()
Download extra outputs from the simulation if they don't locally exist yet.
SIGNATURE
def download_extra_outputs(
    self,
    data_types_to_download: (
        typing.Collection[typing.Literal["volume", "surface"]]
        | typing.Literal["volume", "surface"]
    ) = frozenset({"surface", "volume"}),
    localpath: pathlib.Path | str | None = None,
) -> None: ...
ARGUMENTS
Optional
data_types_to_download
Type:typing.Collection[typing.Literal['volume', 'surface']] | typing.Literal['volume', 'surface']
Default value:frozenset({'surface', 'volume'})
Description:
The data types to download. Defaults to downloading everything.
Optional
localpath
Type:pathlib.Path | str | None
Default value:None
Description:
By default, downloads will be stored next to the meta.json of the EventData object. If this is set to a folder (that must exist) it will instead download to that folder and only put symlinks in the meta.json file's folder.
EventData.expected_components_from_receiver()
Get the expected components from a receiver object and field name.
SIGNATURE
def expected_components_from_receiver(
    receiver: simple_config.receiver._Base | dict, receiver_field: str
) -> list[str]: ...
ARGUMENTS
Required
receiver
Type:simple_config.receiver._Base | dict
Description:
The receiver object or dictionary representation.
Required
receiver_field
Type:str
Description:
The receiver field.
EventData.get_associated_salvus_job()
Get the associated Salvus job, if it still exists.
SIGNATURE
def get_associated_salvus_job(self) -> SalvusJob: ...
EventData.get_data_cube()
Deprecated method, please use get_waveform_data_xarray for similar functionality. Get a data cube for a given field and component. Useful for plotting shotgathers and wiggle plots.
Returns a 2-D array with dimensions of (number of receivers, npts). Sorting, filtering, and composed operations are available through sort_by(), filter_by() and select_by(). In absence of these, receivers will be sorted as in the event object, unless sort_by or select_by are altering the sort order.
SIGNATURE
def get_data_cube(
    self,
    receiver_field: str,
    component: str,
    sort_by: typing.Callable[[_Base], int] | None = None,
    filter_by: typing.Callable[[_Base], bool] | None = None,
    select_by: (
        typing.Callable[
            [list[tuple[_Base, obspy.core.stream.Stream]], EventData],
            list[tuple[_Base, obspy.core.stream.Stream]],
        ]
        | None
    ) = None,
    ignore_deprecation: bool = False,
) -> tuple[np.ndarray, np.ndarray]: ...
ARGUMENTS
Required
receiver_field
Type:str
Description:
Receiver field to retrieve.
Required
component
Type:str
Description:
The component to retrieve. Note that for legacy reasons, this is always converted to an uppercase string, to mirror ObsPy behaviour, which was case-insensitive.
Optional
sort_by
Type:typing.Callable[[_Base], int] | None
Default value:None
Description:
Callback function called with the receiver objects to determine the sorting. Works like the key callback for the standard Python sorted() method.
Optional
filter_by
Type:typing.Callable[[_Base], bool] | None
Default value:None
Description:
Callback function called with the receiver objects in internal Salvus format to determine the filtering. Works like the callback for the standard Python filter() method. For complex filter operations requiring all receivers, defer to the select_by method.
Optional
select_by
Type:typing.Callable[[list[tuple[_Base, obspy.core.stream.Stream]], EventData], list[tuple[_Base, obspy.core.stream.Stream]]] | None
Default value:None
Description:
Callback function called with a list of tuples in the receiver objects in both internal Salvus and ObsPy Stream format, as well as the EventData object.
Optional
ignore_deprecation
Type:bool
Default value:False
Description:
Hide the deprecation warning.
EventData.get_receiver()
Returns a receiver object by name.
The receiver name should be NET.STA.LOC - if LOC is omitted it will be assumed to be an empty string.
SIGNATURE
def get_receiver(self, receiver_name: str) -> simple_config.receiver._Base: ...
ARGUMENTS
Required
receiver_name
Type:str
Description:
The name of the receiver.
EventData.get_receiver_channel()
Returns a receiver channel object by its identifier.
SIGNATURE
def get_receiver_channel(
    self, receiver_channel_name: str
) -> ReceiverChannel: ...
ARGUMENTS
Required
receiver_channel_name
Type:str
Description:
The name of the receiver channel.
EventData.get_receiver_data()
Please use .get_waveform_data() instead.
SIGNATURE
def get_receiver_data(
    self,
    receiver_name: str,
    receiver_field: str,
    header: typing.Any | None = None,
    _ignore_temporal_weights: bool = False,
    _use_cache: bool = False,
) -> obspy.Stream: ...
ARGUMENTS
Required
receiver_name
Type:str
Description:
The name of the receiver
Required
receiver_field
Type:str
Description:
The field to get.
Optional
header
Type:typing.Any | None
Default value:None
Description:
Manually set the tr.stats.header to that value. Sometimes useful to have access to extra meta data in the processing and data selection functions.
Optional
_ignore_temporal_weights
Type:bool
Default value:False
Description:
Ignore temporal weights, even if they are set. Useful mainly for plotting and debugging purposes. Don't set this if you are not aware of the consequences.
Optional
_use_cache
Type:bool
Default value:False
Description:
Utilize a cache for this function. Useful for certain use cases with repeated per-station access.
EventData.get_remote_extra_output_filenames()
Get a dictionary of the remote paths of extra output files.
These files might no longer exist and might already have been transferred to the local site or deleted. These are the paths of the extra output files of the solver.
SIGNATURE
def get_remote_extra_output_filenames(
    self,
) -> dict[tuple[str, ...], pathlib.Path]: ...
EventData.get_time_axis_from_meta_json()
Return the start time, end time, sampling rate and number of samples by parsing the meta.json file.
Naturally only works for synthetic data.
SIGNATURE
def get_time_axis_from_meta_json(
    self,
    output_type: typing.Literal[
        "simulation", "point_data", "surface_data", "volume_data"
    ] = "simulation",
) -> TimeAxis: ...
ARGUMENTS
Optional
output_type
Type:typing.Literal['simulation', 'point_data', 'surface_data', 'volume_data']
Default value:'simulation'
Description:
Optionally define for which output type the time axis is constructed. The output_type "simulation" will always output the time axis as used by SalvusCompute. The other variations will adhere to the sampling rates of the output data for the relevant type.
EventData.get_wavefield_output()
Get a surface or volume wavefield output object for the given simulation.
This will read the full volume or surface output to memory so please use this with caution.
SIGNATURE
def get_wavefield_output(
    self,
    output_type: typing.Literal["volume", "surface"],
    field: str,
    time_steps: slice = slice(None, None, None),
    download_if_not_exists: bool = False,
    delete_remote_data_after_download: bool = False,
) -> salvus.toolbox.helpers.wavefield_output.WavefieldOutput: ...
ARGUMENTS
Required
output_type
Type:typing.Literal['volume', 'surface']
Description:
The output type to get, "surface" or "volume".
Required
field
Type:str
Description:
The field to get.
Optional
time_steps
Type:slice
Default value:slice(None, None, None)
Description:
The time step indices to read expressed as a Python slice object.
Optional
download_if_not_exists
Type:bool
Default value:False
Description:
The data might not yet exist locally and only on a remote Salvus site. If that is the case, try to automatically download it. It will be stored in the same folder as the meta.json file for the simulation.
Optional
delete_remote_data_after_download
Type:bool
Default value:False
Description:
Delete the remote data and associated Salvus job after the download has succeeded. If set, this will delete all remote files for the current event, even if only a subset has been downloaded.
EventData.get_waveform_data()
Get the waveform data for a given receiver and field in a consistent manner. The receiver name can also correspond to a receiver channel.
This is the central waveform retrieval function in SalvusProject and thus will return fully usable waveforms - this means fully filtered and selected/windowed waveforms, if so requested.
Might contain multiple traces per component, but only for data with a data selection configuration.
The order of the traces is always in the order of the expected output components.
It uses ObsPy's Stream/Trace classes as they are just very suitable containers for waveform data.
SIGNATURE
def get_waveform_data(
    self,
    receiver_name: str,
    receiver_field: str,
    header: typing.Any | None = None,
    enforce_regular_time_grid: bool = True,
    time_axis: TimeAxis | None = None,
    _ignore_temporal_weights: bool = False,
    _use_cache: bool = False,
) -> obspy.Stream: ...
ARGUMENTS
Required
receiver_name
Type:str
Description:
The name of the receiver or receiver channel
Required
receiver_field
Type:str
Description:
The field to get.
Optional
header
Type:typing.Any | None
Default value:None
Description:
Manually set the tr.stats.header to that value. Sometimes useful to have access to extra meta data in the processing and data selection functions.
Optional
enforce_regular_time_grid
Type:bool
Default value:True
Description:
Whether to check if a synthetic dataset that is subsampled during the simulation has an appropriate time axis. By default, SalvusCompute will always output the last time step of a simulation, even when the subsampling chosen wouldn't match that point. Setting this parameter to True will check the meta.json specifications and ensure that the final point is removed again if it doesn't match the regular grid of the time axis.
Optional
time_axis
Type:TimeAxis | None
Default value:None
Description:
Optionally specify a time axis for the data. Can be useful when dealing with heterogeneous data sources, such as seismological data, where the time axis may not be uniform across different stations.
Optional
_ignore_temporal_weights
Type:bool
Default value:False
Description:
Ignore temporal weights, even if they are set. Useful mainly for plotting and debugging purposes. Don't set this if you are not aware of the consequences.
Optional
_use_cache
Type:bool
Default value:False
Description:
Utilize a cache for this function. Useful for certain use cases with repeated per-station access.
EventData.get_waveform_data_xarray()
Get the waveform data for a given field for all receivers or receiver channels contained in the Event.
If the Event contains receiver channels. Only the data of the receiver channels will be returned and not of the individual receivers that form the channel.
SIGNATURE
def get_waveform_data_xarray(
    self,
    receiver_field: str,
    enforce_regular_time_grid: bool = True,
    include_receiver_channel_inputs: bool = False,
    receiver_ids: list[str] | None = None,
    time_axis: TimeAxis | None = None,
    _ignore_temporal_weights: bool = False,
    _header_template: xr.DataArray | None = None,
    _use_cache: bool = False,
    _extra_output: ExtraOutput | None = None,
    _extra_output_force_is_observed: bool | None = None,
) -> xr.DataArray: ...
ARGUMENTS
Required
receiver_field
Type:str
Description:
The field to get.
Optional
enforce_regular_time_grid
Type:bool
Default value:True
Description:
Whether to check if a synthetic dataset that is subsampled during the simulation has an appropriate time axis. By default, SalvusCompute will always output the last time step of a simulation, even when the subsampling chosen wouldn't match that point. Setting this parameter to True will check the meta.json specifications and ensure that the final point is removed again if it doesn't match the regular grid of the time axis.
Optional
include_receiver_channel_inputs
Type:bool
Default value:False
Description:
Include the input receivers for receiver channels in the returned data array. By default, only the final receiver channel data will be included.
Optional
receiver_ids
Type:list[str] | None
Default value:None
Description:
Optionally specify a list of receiver IDs to filter the data by. If this is set, only the data for the specified receivers will be returned. If this is None, all receivers will be returned.
Optional
time_axis
Type:TimeAxis | None
Default value:None
Description:
An optional time axis to resample the data to. This will overwrite any potentially set temporal interpolation settings of the event data object.
Optional
_ignore_temporal_weights
Type:bool
Default value:False
Description:
Ignore temporal weights, even if they are set. Useful mainly for plotting and debugging purposes. Don't set this if you are not aware of the consequences.
Optional
_header_template
Type:xr.DataArray | None
Default value:None
Description:
A data set to use as a template for the header.
Optional
_use_cache
Type:bool
Default value:False
Description:
Utilize a cache for this function. Useful for certain use cases with repeated per-station access.
Optional
_extra_output
Type:ExtraOutput | None
Default value:None
Description:
Optionally write intermediate data to disk.
Optional
_extra_output_force_is_observed
Type:bool | None
Default value:None
Description:
Force the waveform data to be considered observed data for the purpose of the extra output. Salvus considers all data that has been computed with it as synthetic but for the synthetic inversions the "observed" data should be written as observed extra output.
EventData.has_receiver()
Figure out if the given receiver is available.
SIGNATURE
def has_receiver(self, receiver_name: str) -> bool: ...
ARGUMENTS
Required
receiver_name
Type:str
Description:
Name of the receiver.
EventData.has_receiver_nsl()
Figure out if the given receiver is available.
SIGNATURE
def has_receiver_nsl(
    self, network_code: str, station_code: str, location_code: str
) -> bool: ...
ARGUMENTS
Required
network_code
Type:str
Description:
The network code.
Required
station_code
Type:str
Description:
The station code.
Required
location_code
Type:str
Description:
The location code.
EventData.plot()
Plot the waveforms.
SIGNATURE
def plot(
    self,
    plot_types: typing.Iterable[str] = ("wiggles",),
    receiver_field: str,
    component: str,
    sort_by: typing.Callable | None = None,
) -> None: ...
ARGUMENTS
Optional
plot_types
Type:typing.Iterable[str]
Default value:('wiggles',)
Description:
How to plot the data.
Required
receiver_field
Type:str
Description:
The receiver field to plot.
Required
component
Type:str
Description:
The component to plot.
Optional
sort_by
Type:typing.Callable | None
Default value:None
Description:
Callback function called with the receiver objects to determine the sorting. Works like the key callback for the standard Python sorted() method.
EventData.register_processing_function()
Register a function to process data on the fly.
The function must take the following arguments if it is supposed to operate on structured data:
  • da: An xarray.DataArray object with the data.
  • sources: The source objects of this event
If the function should operate on obspy.Stream objects per receiver, the function must take the following arguments:
  • st: An obspy.Stream object with the data.
  • receiver: The receiver object for the receiver.
  • sources: All sources for the event.
In the case of ASDF data it can also optionally take:
  • inv: An obspy.Inventory object for the station in case it is stored in an ASDF file. Might be None.
The function must return the processed xarray.DataArray or obspy.Stream. Both must contain exactly the same number of traces, components and time steps as the input data.
SIGNATURE
def register_processing_function(
    self,
    function: typing.Callable | None,
    chain_to_existing_function: bool = False,
) -> None: ...
ARGUMENTS
Required
function
Type:typing.Callable | None
Description:
Function to process data on the fly. Or None to unset it.
Optional
chain_to_existing_function
Type:bool
Default value:False
Description:
If True the new function will be chained to a possibly already pre-existing processing function. If this is False and there is an already pre-existing function it will raise.
EventData.register_temporal_weights_function()
Register a function to weight data on the fly.
The function must take two arguments if operating on structured xarray.DataArray objects:
  • da: An xarray.DataArray object with the data.
  • sources: All sources for the event.
If the function should operate on obspy.Stream objects per receiver, the function must take the following arguments:
  • st: An obspy.Stream object with the data.
  • receiver: The receiver object for the receiver.
  • sources: All sources for the event.
It furthermore must return a dictionary with a list of dictionaries for each component, e.g.
def compute_temporal_weights(
    da: xr.DataArray,
    sources: list[simple_config.source._Base],
) -> dict[str, list[dict]]:
    ...
    # Omit components which you want to ignore for the adjoint source
    # computation.
    weights = {
        "X": [
            {"values": np.array([...]), "misfit_weight": 0.5},
            {"values": np.array([...]), "misfit_weight": 0.5},
        ],
        "Y": [
            # If no "misfit_weight" is given, it defaults to 1.0.
            {"values": np.array([...])},
        ]}
    return weights
SIGNATURE
def register_temporal_weights_function(
    self, function: typing.Callable | None, extra_kwargs: dict | None = None
) -> None: ...
ARGUMENTS
Required
function
Type:typing.Callable | None
Description:
Function to compute windows on the fly. Or None to unset it.
Optional
extra_kwargs
Type:dict | None
Default value:None
Description:
Extra keyword arguments to pass to the function.
EventData.set_temporal_interpolation()
Set the desired temporal interpolation. Once this is set, all returned waveform data will be resampled in time using a sinc-based Lanczos interpolator.
The interpolation will taper and pad with zeros if necessary. It will raise if it would result in more than 50 % of padded new samples.
SIGNATURE
def set_temporal_interpolation(
    self,
    start_time_in_seconds: float,
    sampling_rate_in_hertz: float,
    npts: int,
    lanczos_window_width: int = 12,
    taper_in_samples: int = 5,
    reference_time: float | None = None,
) -> None: ...
ARGUMENTS
Required
start_time_in_seconds
Type:float
Description:
The new start time in seconds. Can be interpreted as a UNIX timestamp if so desired.
Required
sampling_rate_in_hertz
Type:float
Description:
The new sampling rate in Hertz.
Required
npts
Type:int
Description:
The new number of samples.
Optional
lanczos_window_width
Type:int
Default value:12
Description:
The width in samples on either side to use when interpolating onto a new sample.
Optional
taper_in_samples
Type:int
Default value:5
Description:
In case padding with zeros is necessary each traces will be tapered to zero using this many samples at each end it is being padded at. Necessary to avoid introducing unresolved frequencies.
Optional
reference_time
Type:float | None
Default value:None
Description:
Reference time as a UTC timestamp in seconds. Needs to be set for seismological data.
EventData.shallow_copy()
Create a shallow copy of the object - things like data and sources and receivers are just references. Useful to have multiple versions of an event data object.
SIGNATURE
def shallow_copy(self) -> EventData: ...
EventData.unset_temporal_interpolation()
Unsets any temporal interpolation and data will from now on be returned with the original sampling.
SIGNATURE
def unset_temporal_interpolation(self) -> None: ...

PlotProperties

Properties to use of an internally generated plot. This dataclass configures a Matplotlib axes object used in the internal plotting routine. It allows you to customize the dimensions and DPI of the resulting plot.
SIGNATURE
class PlotProperties(builtins.object):
    def __init__(
        self, width: float = 11.5, height: float = 6.33, dpi: float = 100
    ) -> None: ...
ARGUMENTS
Optional
width
Type:float
Default value:11.5
Description:
The width of the figure in inches. This parameter determines the horizontal size of the plot.
Optional
height
Type:float
Default value:6.33
Description:
The height of the figure in inches. This parameter determines the vertical size of the plot.
Optional
dpi
Type:float
Default value:100
Description:
Dots per inch (DPI) for the figure. DPI is a measure of the resolution or quality of the plot. Higher DPI values result in smoother and more detailed output.

Used in tutorials

Functionality from this module is used in the following tutorials.
PAGE CONTENTS