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]#: Appends data in mspass_object to internal array object. For now, we don’t handle resizing similar to std containers in C++ where allocs (in this case a resize) is triggered by filling. Instead, we would just rely on the xarray/numpy’s append.

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]#: Differs from set_metadata in that the contents of md are added to the current and do not fully repalce them. Needed for updating metadata after costruction :param j: index of member :type j: int :param md: the metadata to edit, dict or metadata :type md: 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]#: Setter for metadata of member j. md is the new continer that would replace current conent. Most useful for constructors. :param j: index of member :type j: int :param md: the metadata to set, dict or metadata :type md: 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) → Gather[source]#

Return a subset of the Gather with signals from start to end (like start:end in F90 or matlab).

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) → SeismogramGather[source]#

Return a subset of the Gather with signals from start to end (like start:end in F90 or matlab).

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)[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 member. :param regularizer: 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. :type regularizer: Callable[[TimeSeries|Seismogram], TimeSeries|Seismogram]

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