mspasspy.seismic#

gather#

class mspasspy.seismic.gather.BasicGather(capacity, size, npts, num_components, npartitions, input_data=None, input_obj=None, member_metadata=None, ensemble_metadata=None, dt=None, resample=True, regularize=False, regularizer=None, array_type='dask', is_compact=True, is_parallel=True)[source]#

Bases: ABC

Base class for a MsPASS ensemble class that uses array implementations to store the data. The implementation may or may not provide for arrays that are too large to fit in memory. That behavior is controlled by constructor parameters.

The data object defined by this class and its children is understood as appropriate only for ensemble data that satisfy several restrictions that the current MsPASS ensemble objects (TimeSeriesEnsemble and SeismogramEnsemble) do not require:

All data have the same sample rate.
Each signal has the same number of samples.
The data cannot have gaps. Data with gaps need to be discarded or patched (for example, with a gap fill) before being loaded into one of these containers.

Methods for this base class are largely getters and setters for universal parameters that match the above. It must be understood that with this design the base class is an incomplete skeleton that is fleshed out by subclasses. This class has some virtual methods (defined with the ABC @abstractmethod decorator) and a set of methods that would never work if only the base class were constructed (not allowed because of the virtual methods). In particular, the way the base class handles metadata is potentially confusing because the base class constructor only defines stubs for the data used to hold member and ensemble metadata

A design issue is whether a gather should implement the ator and rtoa functionality of BasicTimeSeries. The cost is tiny up front and retrofitting after that fact might cause a lot of headaches.

append(mspass_object)[source]#

Append one member along axis zero.

capacity is the allocated axis-zero length. Unused rows are retained until the array is full, then the backend grows to fit the new member.

ator(shift)[source]#: Convert the absolut time to relative time

column_values() → list[source]#: Returns the values assigned to the column axis. These should default to integers matching the column index values. They should be allowed to be anything, however, to handle things like variable offset record sections.

dead(j) → bool[source]#: Return true if jth member is marked dead (opposite of live). :param j: index number :type j: int

dt()[source]#: Return the sample rate of the ensemble

edit_metadata(j, md)[source]#

Add the contents of md to the current metadata for member j.

Unlike set_metadata(), this method leaves every omitted key unchanged. It only accepts keys already represented by the member metadata table and copies mutable values from the caller. This is intended for updating metadata after construction.

Parameters:

j (int) – index of member
md (dict or metadata) – the metadata to edit, dict or metadata

ensemble_metadata(return_type='dict')[source]#: Like metadata method but returns the ensemble metadata.

get_metadata(j, return_type='dict')[source]#: Return the Metadata components of member j. return_type should allow optional return as dict or Metadata. Not clear which should be default. :param j: index of member :type j: int :param return_type: return type, dict or metadata :type return_type: str

live(j) → bool[source]#: Return true if jth member is set live. :param j: index number :type j: int

abstract member(j)[source]#: Returns the data associated with member j. Virtual method returns different type for scalar ersus 3c data.

rtoa()[source]#: Convert the relative time to absolute time

sample_number(time, x) → ndarray[source]#: Return a numpy array of ints of the index position of an ordered pair defined by a time (row) value and a column value that can be mapped to the column index. :param x: a list of column names :param time: the time (row) value

samprate()[source]#: Return the sample rate of the ensemble

set_column_values(x)[source]#: Set the column values array to the values in x. :param x: a list of column names

set_metadata(j, md)[source]#

Replace the metadata of member j with the content of md.

Member metadata are stored in a rectangular DataFrame. Consequently, columns used by other members remain in the table, but keys omitted from md become missing values in row j. Values are copied so later edits to mutable objects held by the caller do not alter the gather. This full-row replacement is most useful for constructors; use edit_metadata() for a partial update.

Parameters:

j (int) – index of member
md (dict or metadata) – the metadata to set, dict or metadata

shift(timeshift)[source]#: Time shift for all the member in the ensemble :param timeshift: the shift time range :type timeshift: float

starttime() → list[source]#: Return a list (python array) of starttimes. We should assume times are always stored as doubles.

abstract subset()[source]#: Return a subset of the data defined by either a collection of members or a restricted sample range (a form of windowing). Concrete implementtions can define what this means. Minimum usage would be something functionally equivalent to the f90/matlab synatx of ensemble.member[i:j]. We may also want to be less generic and require addition methods with other names like “extract_members” or “window” (time range).

sync_metadata()[source]#: This would act like the one in Ensemble in C++ copying all the ensemble key-value pairs to the members. It is debatable that this would be needed but would be trivial to implement.

time(i, j)[source]#

Return time of array position i,j (Note works the same for 3c and scalar data)

Parameters:

i (int) – row index
j (int) – column index

time_is_UTC()[source]#: Returns True if the time standard for the data is set as UTC

time_is_relative()[source]#: Returns True if the time standard for the data is set as relative

class mspasspy.seismic.gather.Gather(capacity=0, size=0, npts=0, num_components=0, npartitions=0, input_data=None, input_obj=None, member_metadata=None, ensemble_metadata=None, resample=True, dt=None, regularize=False, regularizer=None, array_type='dask', is_compact=True)[source]#

Bases: BasicGather

Concrete implementtion for a scalar gather. This is the array equivalent of a TimeSeriesEnsemble appropriate when the input matches the concept of BasicGather. It follows the OOP stndard pardigm that creation is initialization. This puts a lot of features in the constructor for the class.

data(j) → ndarray[source]#: Return the raw data vector associated with column j. Defined here as an ndarray return but probably should be any iterable container that acts like a vector. :param j: index :param j: int

member(j) → TimeSeries[source]#: Returns the data associated with member j. Unlike above I suggest we not do the idea of “data_only”. Aways return a TimeSeries. Suggest data method for that purpose :param j: index :param j: int

subset(start, end=None) → Gather[source]#

Return members selected by an index iterable or a start:end range.

Iterable selection preserves order and duplicate indices. An empty iterable returns an empty Gather with the same trailing axes/backend.

Parameters:

start – the start index of the subset
end – specifies the index where the subset ends, excluding the value at this index just like array slicing.

class mspasspy.seismic.gather.SeismogramGather(capacity=0, size=0, npts=0, num_components=0, npartitions=0, input_data=None, input_obj=None, member_metadata=None, ensemble_metadata=None, resample=True, dt=None, regularize=False, regularizer=None, array_type='dask', is_compact=True)[source]#

Bases: BasicGather

Gather for three-component data. Can only be created from inputs that satisfy the restrictions of BasicGather. It is much like Gather but with a 3D instead of a 2D array holding sample data.

data(j) → ndarray[source]#: Return the raw data matrix associated with column j. Defined here as an ndarray return but probably should be any iterable container that acts like a matrix. Not clear what will be needed to support large matrix formats. :param j: index :param j: int

member(j) → Seismogram[source]#: Returns the data associated with member j. Unlike above I suggest we not do the idea of “data_only”. Aways return a TimeSeries. Suggest data method for that purpose :param j: index :param j: int

subset(start, end=None) → SeismogramGather[source]#

Return members selected by an index iterable or a start:end range.

Iterable selection preserves order and duplicate indices. An empty iterable returns an empty Gather with the same trailing axes/backend.

Parameters:

start – the start index of the subset
end – specifies the index where the subset ends, excluding the value at this index just like array slicing.

mspasspy.seismic.gather.extractDataFromMsPassObject(mspass_object)[source]#

mspass_object is either a seismogram or a timeseries, mspass_object.data is a DoubleVector/dmatrix, we want to convert it extract the data from it and convert it into a numpy array The return type is np.ndarray

Parameters:: mspass_object – Seismogram or TimeSeries to extract data from

mspasspy.seismic.gather.extractDataFromOldEnsemble(ensemble_object)[source]#

A wrapper function to extract data data from an old ensemble object, works by iterating the member in the ensemble and calling extractDataFromMsPassObject on each of them.

Parameters:: ensemble_object – TimeSeriesEnsemble or SeismogramEnsemble

mspasspy.seismic.gather.extractMemberMetadataFromOldEnsemble(ensemble_object)[source]#

A helper function to extract the member metadata from the old ensemble object It iterates all the members, reads the metadata and concatenate them into one single dataframe.

Parameters:: ensemble_object – TimeSeriesEnsemble or SeismogramEnsemble

mspasspy.seismic.gather.isMsPassObject(obj)[source]#

mspasspy.seismic.gather.isOldEnsembleObject(obj)[source]#

mspasspy.seismic.gather.read_basic_array_ensemble(db, ensemble_object, object_id)[source]#

Read an array from the database into an ensemble object.

Parameters:

db – database containing the ensemble collection.
ensemble_object – object that receives the stored metadata and data.
object_id – MongoDB identifier of the ensemble document. The identifier provides a one-to-one mapping to the ensemble metadata and member data.

The ensemble document schema is:

_id : unique id
metadata : a dict that stores the ensemble's metadata
member_metadata : a list of metadata for each member
store_type = 'zarr' : we might support other storage?
zarr_group_path : str, the path of the zarr group
zarr_arr_name : str, the name of the zarr array

mspasspy.seismic.gather.regularize_ensemble(ens, regularizer=None, grid_alignment='snap')[source]#

A helper function to regularize all the member data in an ensemble. The purpose of this function is to set all member data to have the same start time. By default, the regularization is carried out by simply applying a time window on each live member. The default window is the inclusive physical intersection of the live member time ranges. Consequently, an intersection with equal start and end times contains one sample when all members share that sample. Dead members are not used to define the intersection and are returned unchanged.

The output members must resolve to the same sampled time axis. This is checked on copied members before replacing any ensemble member, so a disjoint interval or incompatible sample grids leave the input ensemble unchanged. By default, members with a common sample interval are snapped to the first live member’s nearest sample grid without changing sample values. Set grid_alignment="interpolate" to linearly interpolate those members onto that grid instead. Members with different sample intervals must be resampled first. A user-supplied regularizer retains control of member selection and replacement and is called with every member as in the original API.

Parameters:

ens – input TimeSeriesEnsemble or SeismogramEnsemble. The object is modified in place and returned.
regularizer (Callable[[TimeSeries|Seismogram], TimeSeries|Seismogram]) – A function object defined by user that regularize all data members in the ensemble, it should take only one argument (a timeseries/seismogram) and return the regularized object.
grid_alignment – "snap" (default) preserves sample values and moves each selected window to the common grid. "interpolate" linearly interpolates off-grid windows onto that grid. Ignored when regularizer is supplied.

Raises:

TypeError – if ens is not an MsPASS ensemble object.
ValueError – when live members have no common physical sample or the common window has incompatible sample intervals.

mspasspy.seismic.gather.resample_ensemble(ens, dt=None)[source]#: A wrapper for the resample function defined in resample.py. It would automate handling of resampling any valid data object to a common sample rate. User can pass the sample interval for the resampler, if not given by the user, we would use the sample interval from the first data member.

mspasspy.seismic.gather.write_basic_array_ensemble(db, ensemble_object, object_id)[source]#

Write an ensemble object’s data and metadata to storage.

Parameters:

db – database containing the ensemble collection.
ensemble_object – object whose metadata and data are written.
object_id – MongoDB identifier of the ensemble document. The identifier provides a one-to-one mapping to the ensemble metadata and member data.

The ensemble document schema is:

_id : unique id
metadata : a dict that stores the ensemble's metadata
member_metadata : a list of metadata for each member
store_type = 'zarr' : we might support other storage?
zarr_group_path : str, the path of the zarr group
zarr_arr_name : str, the name of the zarr array

mspasspy.seismic#

gather#

This Page