gwadama.datasets#

datasets.py

Main classes to manage GW datasets.

There are two basic type of datasets, clean and injected:

Clean datasets’ classes inherit from the Base class, extending their properties as needed.
Injected datasets’ classes inherit from the BaseInjected class, and optionally from other UserDefined(Base) classes.

class gwadama.datasets.Base[source]#

Bases: object

Base class for all datasets.

TODO: Update docstring.

Any dataset made of ‘clean’ (noiseless) GW must inherit this class. It is designed to store strains as nested dictionaries, with each level’s key identifying a class/property of the strain. Each individual strain is a 1D NDArray containing the features.

By default there are two basic levels:

Class; to group up strains in categories.

Id; An unique identifier for each strain, which must exist in the metadata DataFrame as Index.

Extra depths can be added, and will be thought of as modifications of the same original strains from the upper identifier level. If splitting the dataset into train and test susbsets, only combinations of (Class, Id) will be considered.

NOTE: This class shall not be called directly. Use one of its subclasses.

Attributes:

classesdict

Dict of strings and their integer labels, one per class (category).

metadatapandas.DataFrame

All parameters and data related to the strains. The order is the same as inside ‘strains’ if unrolled to a flat list of strains up to the second depth level (the ID). The total number of different waves must be equal to len(metadata); this does not include possible variations such polarizations or multiple scallings of the same waveform when performing injections.

strainsdict[dict […]]

Strains stored as a nested dictionary, with each strain in an independent array to provide more flexibility with data of a wide range of lengths.

Shape: {class: {id: strain} }
The ‘class’ key is the name of the class, a string which must exist in the ‘classes’ list.
The ‘id’ is a unique identifier for each strain, and must exist in the index of the ‘metadata’ (DataFrame) attribute.
Extra depths can be added as variations of each strain, such as polarizations.

labelsdict

Class label of each wave ID, with shape {id: class_label}. Each ID points to the label of its class in the ‘classes’ attribute. Can be automatically constructed by calling the ‘_gen_labels()’ method.

max_lengthint

Length of the longest strain in the dataset. Remember to update it if modifying the strains length.

timesdict, optional

Time samples associated with the strains, following the same structure up to the second depth level: {class: {id: time_points} } Useful when the sampling rate is variable or different between strains. If None, all strains are assumed to be constantly sampled to the sampling rate indicated by the ‘sample_rate’ attribute.

sample_rateint, optional

If the ‘times’ attribute is present, this value is ignored. Otherwise it is assumed all strains are constantly sampled to this value.

NOTE: If dealing with variable sampling rates, avoid setting this attribute to anything other than None.

random_seedint, optional

Value passed to ‘sklearn.model_selection.train_test_split’ to generate the Train and Test subsets. Saved for reproducibility purposes.

Xtrain, Xtestdict, optional

Train and test subsets randomly split using SKLearn train_test_split function with stratified labels. Shape: {id: strain}. The ‘id’ corresponds to the strain’s index at ‘self.metadata’. They are just another views into the same data stored at ‘self.strains’, so no copies are performed.

Ytrain, YtestNDArray[int], optional

1D Array containing the labels in the same order as ‘Xtrain’ and ‘Xtest’ respectively. See the attribute ‘labels’ for more info.

id_train, id_testNDArray[int], optional

1D Array containing the id of the signals in the same order as ‘Xtrain’ and ‘Xtest’ respectively.

Methods

`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, with_id, with_index])	Get the filtered test labels.
`get_ytrain_array`([classes, with_id, with_index])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`stack_by_id`(id_list[, length])	Stack an subset of strains by their ID into a Numpy array.
`whiten`([asd_array, pad, highpass, flength, ...])	Whiten the strains.

__init__()[source]#: Overwrite when inheriting!

build_train_test_subsets(train_size: int | float, random_seed: int = None)[source]#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

find_class(id)[source]#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

get_strain(*indices, normalize=False) → ndarray[source]#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray[source]#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray[source]#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length=None, classes='all')[source]#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Stacks all signals in the test subset into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

test_arraynp.ndarray: test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.

get_xtrain_array(length=None, classes='all')[source]#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Stacks all signals in the train subset into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional: Target length of the ‘train_array’. If None, the longest signal determines the length.
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

train_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_ytest_array(classes='all', with_id=False, with_index=False)[source]#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', with_id=False, with_index=False)[source]#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()[source]#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list[source]#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None[source]#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

resample(sample_rate, verbose=False) → None[source]#

Resample strain and time arrays to a constant rate.

This assumes time tracking either with time arrays or with the sampling rate provided during initialization, which will be used to generate the time arrays previous to the resampling.

This method updates the sample_rate and the max_length.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None[source]#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

The limits of the interval to shrink to. If limits is a tuple, it must be of the form (start, end) in samples. If limits is a dictionary, it must be of the form {id: (start, end)}, where id is the identifier of each strain.

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

stack_by_id(id_list: list, length: int = None)[source]#

Stack an subset of strains by their ID into a Numpy array.

Stack an arbitrary selection of strains by their original ID into a zero-padded 2d-array. The resulting order is the same as the order of that in ‘id_list’.

Parameters:

id_listlist: The IDs of the strains to be stacked.
lengthint, optional: The target length of the stacked array. If None, the longest signal determines the length.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(asd_array: ndarray = None, pad: int = 0, highpass: int = None, flength: float = None, normed: bool = False, verbose=False) → None[source]#

Whiten the strains.

Calling this method performs the whitening of all strains. Optionally, strains are first zero-padded, whitened and then shrunk to their initial size. This is useful to remove the vignetting effect.

NOTE: Original (non-whitened) strains will be stored in the ‘nonwhiten_strains’ attribute.

class gwadama.datasets.BaseInjected(clean_dataset: Base, *, psd: ndarray | Callable, detector: str, noise_length: int, freq_cutoff: int | float, freq_butter_order: int | float, whiten_params: dict = None, random_seed: int = None)[source]#

Bases: Base

Manage an injected dataset with multiple SNR values.

It is designed to store strains as nested dictionaries, with each level’s key identifying a class/property of the strain. Each individual strain is a 1D NDArray containing the features.

NOTE: Instances of this class or any other Class(BaseInjected) are initialized from an instance of any Class(Base) instance (clean dataset).

By default there are THREE basic levels:

Class; to group up strains in categories.

Id; An unique identifier for each strain, which must exist in the metadata DataFrame as Index.

SNR; the signal-to-noise ratio at which has been injected w.r.t. a power spectral density of reference (e.g. the sensitivity of a GW detector).

An extra depth can be added below, and will be treated as multiple injections at the same SNR value. This is usfeul for example to make injections at multiple noise realizations.

Attributes:

classeslist[str]

List of labels, one per class (category).

metadatapandas.DataFrame

All parameters and data related to the original strains, inherited (copied) from a clean Class(Base) instance. The order is the same as inside ‘strains’ if unrolled to a flat list of strains up to the second depth level (the ID). The total number of different waves must be equal to len(metadata); this does not include possible variations such polarizations or multiple scallings of the same waveform when performing injections.

strains_cleandict[dict]

Strains inherited (copied) from a clean Class(Base) instance. This copy is kept in order to perform new injections.

Shape: {class: {id: strain} }
The ‘class’ key is the name of the class, a string which must exist in the ‘classes’ list.
The ‘id’ is a unique identifier for each strain, and must exist in the index of the ‘metadata’ (DataFrame) attribute.

NOTE: These strains should be not modified. If new clean strains are needed, create a new clean dataset instance first, and then initialise this class with it.

TODO: Accept extra layers in the clean_strains dictionary.

strainsdict[dict]

Injected trains stored as a nested dictionary, with each strain in an independent array to provide more flexibility with data of a wide range of lengths.

Shape: {class: {id: {snr: strain} } }
The ‘class’ key is the name of the class, a string which must exist in the ‘classes’ list.
The ‘id’ is a unique identifier for each strain, and must exist in the index of the ‘metadata’ (DataFrame) attribute.
The ‘snr’ key is an integer indicating the signal-to-noise ratio of the injection.
A fourth depth can be added below as additional injections per SNR.

labelsdict

Indices of the class of each wave ID, inherited from a clean Class(Base) instance, with shape {id: class_index}. Each ID points to the index of its class in the ‘classes’ attribute.

unitsstr

Flag indicating whether the data is in ‘geometrized’ or ‘IS’ units.

timesdict, optional

Time samples associated with the strains, following the same structure. Useful when the sampling rate is variable or different between strains. If None, all strains are assumed to be constantly sampled to the sampling rate indicated by the ‘sample_rate’ attribute.

sample_rateint

Inherited from the parent Class(Base) instance.

max_lengthint

Length of the longest strain in the dataset. Remember to update it if manually changing strains’ length.

random_seedint

Value passed to ‘sklearn.model_selection.train_test_split’ to generate the Train and Test subsets. Saved for reproducibility purposes. Also used to initialize Numpy’s default RandomGenerator.

rngnp.random.Generator

Random number generator used for sampling the background noise. Initialized with np.random.default_rng(random_seed).

detectorstr

GW detector name.

psd_NDArray

Numerical representation of the Power Spectral Density (PSD) of the detector’s sensitivity.

asd_NDArray

Numerical representation of the Amplitude Spectral Density (ASD) of the detector’s sensitivity.

noisegwadama.synthetic.NonwhiteGaussianNoise

Background noise instance from NonwhiteGaussianNoise.

snr_listlist

List of SNR values at which each signal has been injected.

paddict

Padding introduced at each SNR injection, used in case the strains will be whitened after, to remove the vigneting at edges. It is associated to SNR values because the only implemented way to pad the signals is during the signal injection.

injections_per_snrint

Number of injections per SNR value.

whitenedbool

Flat indicating whether the dataset has been whitened. Initially will be set to False, and changed to True after calling the ‘whiten’ method. Once whitened, this flag will remain True, since the whitening is implemented to be irreversible instance-wise.

whiten_paramsdict

TODO

freq_cutoffint | float: Frequency cutoff below which no noise bins will be generated in the frequency space, and also used for the high-pass filter applied to clean signals before injection.
freq_butter_orderint: Butterworth filter order. See (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html) for more information.

Xtrain, Xtestdict, optional

Train and test subsets randomly split using SKLearn train_test_split function with stratified labels. Shape adds the SNR layer: {id: {snr: strain}}. The ‘id’ corresponds to the strain’s index at ‘self.metadata’.

Ytrain, YtestNDArray[int], optional

1D Array containing the labels in the same order as ‘Xtrain’ and ‘Xtest’ respectively.

NOTE: Does not include the SNR layer, therefore labels are not repeated.

Methods

`asd`(frequencies)	Amplitude spectral density (ASD) of the detector at given frequencies.
`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`export_strains_to_gwf`(path, channel[, ...])	Export all strains to GWF format, one file per strain.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`gen_injections`(snr[, pad, randomize_noise, ...])	Inject all strains in simulated noise with the given SNR values.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes, snr, ...])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes, snr, ...])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, snr, with_id, ...])	Get the filtered test labels.
`get_ytrain_array`([classes, snr, with_id, ...])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`psd`(frequencies)	Power spectral density (PSD) of the detector at given frequencies.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`stack_by_id`(id_list[, length, snr_included])	Stack a subset of strains by ID into a zero-padded 2d-array.
`whiten`([verbose])	Whiten injected strains.

__init__(clean_dataset: Base, *, psd: ndarray | Callable, detector: str, noise_length: int, freq_cutoff: int | float, freq_butter_order: int | float, whiten_params: dict = None, random_seed: int = None)[source]#

Base constructor for injected datasets.

TODO: Update docstring.

When inheriting from this class, it is recommended to run this method first in your __init__ function.

Relevant attributes are inherited from the ‘clean_dataset’ instance, which can be any inherited from BaseDataset whose strains have not been injected yet.

If train/test subsets are present, they too are updated when performing injections or changing units, but only through re-building them from the main ‘strains’ attribute using the already generated indices. Original train/test subsets from the clean dataset are not inherited.

WARNING: Initializing this class does not perform the injections! For that use the method ‘gen_injections’.

Parameters:

clean_datasetBase

Instance of a Class(Base) with noiseless signals.

psdnp.ndarray | Callable

Power Spectral Density of the detector’s sensitivity in the range of frequencies of interest. Can be given as a callable function whose argument is expected to be an array of frequencies, or as a 2d-array with shape (2, psd_length) so that

` psd[0] = frequency_samples psd[1] = psd_samples `.

NOTE: It is also used to compute the ‘asd’ attribute (ASD).

detectorstr

GW detector name. Not used, just for identification.

noise_lengthint

Length of the background noise array to be generated for later use. It should be at least longer than the longest signal expected to be injected.

freq_cutoffint | float

Frequency cutoff below which no noise bins will be generated in the frequency space, and also used for the high-pass filter applied to clean signals before injection.

freq_butter_orderint | float

Butterworth filter order. See (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html) for more information.

flengthint

Length (in samples) of the time-domain FIR whitening filter.

whiten_paramsdict, optional

Parameters of the whitening filter, with the following entries:

‘flength’int
Length (in samples) of the time-domain FIR whitening.
‘highpass’float
Frequency cutoff.
‘normed’bool
Normalization applied after the whitening filter.

random_seedint, optional

Value passed to ‘sklearn.model_selection.train_test_split’ to generate the Train and Test subsets. Saved for reproducibility purposes, and also used to initialize Numpy’s default RandomGenerator.

asd(frequencies: float | ndarray[float]) → ndarray[float][source]#

Amplitude spectral density (ASD) of the detector at given frequencies.

Interpolates the ASD at the given frequencies from their array representation. If during initialization the ASD was given as its array representation, the interpolant is computed using SciPy’s quadratic spline interpolant function.

build_train_test_subsets(train_size: int | float, random_seed: int = None)#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

export_strains_to_gwf(path: str, channel: str, t0_gps: float = 0, verbose=False) → None[source]#: Export all strains to GWF format, one file per strain.

find_class(id)#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

gen_injections(snr: int | float | list, pad: int = 0, randomize_noise: bool = False, random_seed: int = None, injections_per_snr: int = 1, verbose=False)[source]#

Inject all strains in simulated noise with the given SNR values.

The SNR is computed using a matched filter against the noise PSD.
If pad > 0, it also updates the time arrays.
If strain units are in geometrized, they will be converted first to IS, injected, and converted back to geometrized.
After each injection, applies a highpass filter at the low-cut frequency specified at __init__.
If the method ‘whiten’ has been already called, all further injections will automatically be whitened and their pad removed.

Parameters:

snrint | float | list

padint

Number of zeros to pad the signal at both ends before the injection.

randomize_noisebool

If True, the noise segment is randomly chosen before the injection. This can be used to avoid having the same noise injected for all clean strains. False by default.

NOTE: To avoid the possibility of repeating the same noise section in different injections, the noise realization must be reasonably large, e.g:

noise_length > n_clean_strains * self.max_length * len(snr)

random_seedint, optional

Random seed for the noise realization. Only used when randomize_noise is True.

injections_per_snrint

Number of injections per SNR value. Defaults to 1.

This is useful to minimize the statistical impact of the noise when performing injections at a sensitive (low) SNR.

Raises:

ValueError: Once injections have been performed at a certain SNR value, there cannot be injected again at the same value. Trying it will trigger this exception.

Notes

If whitening is intended to be applied afterwards it is useful to pad the signal in order to avoid the window vignetting produced by the whitening itself. This pad will be cropped afterwards.
New injections are stored in the ‘strains’ atrribute, with the pad associated to all the injections performed at once. Even when whitening is also performed right after the injections.

get_strain(*indices, normalize=False) → ndarray#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray[source]#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length: int = None, classes: str | list = 'all', snr: int | list | str = 'all', with_metadata: bool = False)[source]#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Allows the possibility to filter by class and SNR.

NOTE: Same signals injected at different SNR are stacked continuously.

Parameters:

lengthint, optional

Target length of the ‘test_array’. If None, the longest signal determines the length.

classesstr | list[str]

Whitelist of classes to include in the stack. All classes are included by default.

snrint | list[int] | str

Whitelist of SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` eos0 id0 snr0 eos0 id0 snr1

…

```

All injections are included by default.

with_metadatabool

If True, the associated metadata is returned in addition to the test array in a Pandas DataFrame instance. This metadata is obtained from the original ‘metadata’ attribute, with the former index inserted as the first column, ‘id’, and with an additional column for the SNR values. False by default.

Returns:

test_arraynp.ndarray: Test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.
metadatapd.DataFrame, optional: If ‘with_metadata’ is True, the associated metadata is returned with its entries in the same order as the ‘test_array’.

get_xtrain_array(length: int = None, classes: str | list = 'all', snr: int | list | str = 'all', with_metadata: bool = False)[source]#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Allows the possibility to filter by class and SNR.

NOTE: Same signals injected at different SNR are stacked continuously.

Parameters:

lengthint, optional

Target length of the ‘train_array’. If None, the longest signal determines the length.

classesstr | list[str]

Whitelist of classes to include in the stack. All classes are included by default.

snrint | list[int] | str

Whitelist of SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` eos0 id0 snr0 eos0 id0 snr1

…

```

All injections are included by default.

with_metadatabool

If True, the associated metadata is returned in addition to the train array in a Pandas DataFrame instance. This metadata is obtained from the original ‘metadata’ attribute, with the former index inserted as the first column, ‘id’, and with an additional column for the SNR values. False by default.

Returns:

train_arraynp.ndarray: Train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.
metadatapd.DataFrame, optional: If ‘with_metadata’ is True, the associated metadata is returned with its entries in the same order as the ‘train_array’.

get_ytest_array(classes='all', snr='all', with_id=False, with_index=False)[source]#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: Whitelist of classes to include in the labels. All classes are included by default.
snrint | list[int] | str: Whitelist of SNR injections to include in the labels. All injections are included by default.
with_idbool: If True, return also the related IDs. False by default.
with_indexbool: If True, return also the related GLOBAL indices w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', snr='all', with_id=False, with_index=False)[source]#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: Whitelist of classes to include in the labels. All classes are included by default.
snrint | list[int] | str: Whitelist of SNR injections to include in the labels. All injections are included by default.
with_idbool: If True, return also the related IDs. False by default.
with_indexbool: If True, return also the related GLOBAL indices w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

psd(frequencies: float | ndarray[float]) → ndarray[float][source]#

Power spectral density (PSD) of the detector at given frequencies.

Interpolates the PSD at the given frequencies from their array representation. If during initialization the PSD was given as its array representation, the interpolant is computed using SciPy’s quadratic spline interpolant function.

resample(sample_rate, verbose=False) → None#

Resample strain and time arrays to a constant rate.

This assumes time tracking either with time arrays or with the sampling rate provided during initialization, which will be used to generate the time arrays previous to the resampling.

This method updates the sample_rate and the max_length.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

stack_by_id(id_list: list, length: int = None, snr_included: int | list[int] | str = 'all')[source]#

Stack a subset of strains by ID into a zero-padded 2d-array.

This may allow (for example) to group up strains by their original ID without leaking differnet injections (SNR) of the same strain into different splits.

Parameters:

id_listarray-like

The IDs of the strains to be stacked.

lengthint, optional

The target length of the stacked array. If None, the longest signal determines the length.

snr_includedint | list[int] | str, optional

The SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` id0 snr0 id0 snr1

…

```

All injections are included by default.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Raises:

ValueError: If the value of ‘snr’ is not valid.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(verbose=False)[source]#

Whiten injected strains.

Calling this method performs the whitening of all injected strains. Strains are later cut to their original size before adding the pad, to remove the vigneting.

NOTE: This is an irreversible action; if the original injections need to be preserved it is advised to make a copy of the instance before performing the whitening.

class gwadama.datasets.CoReWaves(*, coredb: CoReManager, classes: dict[str], discarded: set, cropped: dict, distance: float, inclination: float, phi: float)[source]#

Bases: Base

Manage all operations needed to perform over a noiseless CoRe dataset.

Initial strains and metadata are obtained from a CoReManager instance.

NOTE: This class treats as different classes (categories) each equation of state (EOS) present in the CoReManager instance.

NOTE^2: This class adds a time attribute with time samples related to each GW.

Workflow:

Load the strains from a CoreWaEasy instance, discarding or cropping those indicated with their respective arguments.
Resample.
Project onto the ET detector arms.
Change units and scale from geometrized to IS and vice versa.
Export the (latest version of) dataset to a HDF5.
Export the (latest version of) dataset to a GWF.

Attributes:

classesdict

Dict of strings and their integer labels, one per class (category). The keys are the name of the Equation of State (EOS) used to describe the physics behind the simulation which produced each strain.

strainsdict {class: {id: gw_strain} }

Strains stored as a nested dictionary, with each strain in an independent array to provide more flexibility with data of a wide range of lengths. The class key is the name of the class, a string which must exist in the ‘classes’ list. The ‘id’ is an unique identifier for each strain, and must exist in the self.metadata.index column of the metadata DataFrame. Initially, an extra depth layer is defined to store the polarizations of the CoRe GW simulated data. After the projection this layer will be collapsed to a single strain.

timesdict {class: {id: gw_time_points} }

Time samples associated with the strains, following the same structure. Useful when the sampling rate is variable or different between strains.

metadatapandas.DataFrame

All parameters and data related to the strains. The order is the same as inside ‘strains’ if unrolled to a flat list of strains up to the second depth level (the id.). Example:

``` metadata[eos][key] = {

‘id’: str, ‘mass’: float, ‘mass_ratio’: float, ‘eccentricity’: float, ‘mass_starA’: float, ‘mass_starB’: float, ‘spin_starA’: float, ‘spin_starB’: float

unitsstr

Flag indicating whether the data is in ‘geometrized’ or ‘IS’ units.

sample_rateint, optional

Initially this attribute is None because the initial GW from CoRe are sampled at different and non-constant sampling rates. After the resampling, this attribute will be set to the new global sampling rate.

Caveat: If the ‘times’ attribute is present, this value is ignored. Otherwise it is assumed all strains are constantly sampled to this.

Methods

`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`convert_to_IS_units`()	Convert data from scaled geometrized units to IS units.
`convert_to_scaled_geometrized_units`()	Convert data from IS to scaled geometrized units.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, with_id, with_index])	Get the filtered test labels.
`get_ytrain_array`([classes, with_id, with_index])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`project`(*, detector, ra, dec, geo_time, psi)	Project strains into the chosen detector at specified coordinates.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`shrink_to_merger`([offset])	Shrink strains and time arrays w.r.t.
`stack_by_id`(id_list[, length])	Stack an subset of strains by their ID into a Numpy array.
`whiten`([asd_array, pad, highpass, flength, ...])	Whiten the strains.

find_merger

__init__(*, coredb: CoReManager, classes: dict[str], discarded: set, cropped: dict, distance: float, inclination: float, phi: float)[source]#

Initialize a CoReWaves dataset.

TODO

Parameters:

coredbioo.CoReManager: Instance of CoReManager with the actual data.
classesdict[str]: Dictionary with the Equation of State (class) name as key and the corresponding label index as value.
discardedset[str]: Set of GW IDs to discard from the dataset.
croppeddict[str]: Dictionary with the class name as key and the corresponding cropping range as value. The range is given as a tuple of the form (start_index, stop_index).
distancefloat: Distance to the source in Mpc.
inclinationfloat: Inclination of the source in radians.
phifloat: Azimuthal angle of the source in radians.

build_train_test_subsets(train_size: int | float, random_seed: int = None)#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

convert_to_IS_units() → None[source]#

Convert data from scaled geometrized units to IS units.

Convert strains and times from geometrized units (scaled to the mass of the system and the source distance) to IS units.

Will raise an error if the data is already in IS units.

convert_to_scaled_geometrized_units() → None[source]#

Convert data from IS to scaled geometrized units.

Convert strains and times from IS to geometrized units, and scaled to the mass of the system and the source distance.

Will raise an error if the data is already in geometrized units.

find_class(id)#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

find_merger(strain: ndarray) → int[source]#

get_strain(*indices, normalize=False) → ndarray#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length=None, classes='all')#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

test_arraynp.ndarray: test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.

get_xtrain_array(length=None, classes='all')#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional: Target length of the ‘train_array’. If None, the longest signal determines the length.
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

train_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_ytest_array(classes='all', with_id=False, with_index=False)#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', with_id=False, with_index=False)#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

project(*, detector: str, ra: float, dec: float, geo_time: float, psi: float)[source]#

Project strains into the chosen detector at specified coordinates.

Project strains into the chosen detector at specified coordinates, using Bilby.

This collapses the polarization layer in ‘strains’ and ‘times’ to a single strain. The times are rebuilt taking as a reference point the merger (t = 0).

Parameters:

detectorstr: Name of the ET arm in Bilby for InterferometerList().
ra, decfloat: Sky position in equatorial coordinates.
geo_timeint | float: Time of injection in GPS.
psifloat: Polarization angle.

resample(sample_rate, verbose=False) → None[source]#

Resample strain and time arrays to a constant rate.

Resample CoRe strains (from NR simulations) to a constant rate.

This method updates the sample_rate, the max_length and the merger_pos inside the metadata attribute.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

shrink_to_merger(offset: int = 0) → None[source]#

Shrink strains and time arrays w.r.t. the merger.

Shrink strains (and their associated time arrays) discarding the left side of the merger (inspiral), with a given offset in samples.

This also updates the metadata column ‘merger_pos’.

NOTE: This is an irreversible action.

Parameters:

offsetint: Offset in samples relative to the merger position.

stack_by_id(id_list: list, length: int = None)#

Stack an subset of strains by their ID into a Numpy array.

Stack an arbitrary selection of strains by their original ID into a zero-padded 2d-array. The resulting order is the same as the order of that in ‘id_list’.

Parameters:

id_listlist: The IDs of the strains to be stacked.
lengthint, optional: The target length of the stacked array. If None, the longest signal determines the length.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(asd_array: ndarray = None, pad: int = 0, highpass: int = None, flength: float = None, normed: bool = False, verbose=False) → None#

Whiten the strains.

Calling this method performs the whitening of all strains. Optionally, strains are first zero-padded, whitened and then shrunk to their initial size. This is useful to remove the vignetting effect.

NOTE: Original (non-whitened) strains will be stored in the ‘nonwhiten_strains’ attribute.

class gwadama.datasets.InjectedCoReWaves(clean_dataset: Base, *, psd: ndarray | Callable, detector: str, noise_length: int, whiten_params: dict, freq_cutoff: int | float, freq_butter_order: int | float, random_seed: int)[source]#

Bases: BaseInjected

Manage injections of GW data from CoRe dataset.

Tracks index position of the merger.
Computes the SNR only at the ring-down starting from the merger.
Computes also the usual SNR over the whole signal and stores it for later reference (attr. ‘whole_snr_list’).

Attributes:

snr_listlist: Partial SNR values at which each signal is injected. This SNR is computed ONLY over the Ring-Down section of the waveform starting from the merger, hence the name ‘partial SNR’.
whole_snrdict: Nested dictionary storing for each injection the equivalent SNR value computed over the whole signal, hence the name ‘whole SNR’. Structure: {id_: {partial_snr: whole_snr}}
TODO

Methods

`asd`(frequencies)	Amplitude spectral density (ASD) of the detector at given frequencies.
`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`export_strains_to_gwf`(path, channel[, ...])	Export all strains to GWF format, one file per strain.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`gen_injections`(snr[, pad, randomize_noise, ...])	Inject all strains in simulated noise with the given SNR values.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes, snr, ...])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes, snr, ...])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, snr, with_id, ...])	Get the filtered test labels.
`get_ytrain_array`([classes, snr, with_id, ...])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`psd`(frequencies)	Power spectral density (PSD) of the detector at given frequencies.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`stack_by_id`(id_list[, length, snr_included])	Stack a subset of strains by ID into a zero-padded 2d-array.
`whiten`([verbose])	Whiten injected strains.

__init__(clean_dataset: Base, *, psd: ndarray | Callable, detector: str, noise_length: int, whiten_params: dict, freq_cutoff: int | float, freq_butter_order: int | float, random_seed: int)[source]#

Initializes an instance of the InjectedCoReWaves class.

Parameters:

clean_datasetBase

An instance of a BaseDataset class with noiseless signals.

psdnp.ndarray | Callable

```: psd[0] = frequency_samples psd[1] = psd_samples.

```

NOTE: It is also used to compute the ‘asd’ attribute (ASD).

detectorstr

GW detector name.

noise_lengthint

Length of the background noise array to be generated for later use. It should be at least longer than the longest signal expected to be injected.

whiten_paramsdict

Parameters to be passed to the ‘whiten’ method of the ‘BaseInjected’ class.

freq_cutoffint | float

Frequency cutoff for the filter applied to the signal.

freq_butter_orderint | float

Order of the Butterworth filter applied to the signal.

random_seedint

Random seed for generating random numbers.

asd(frequencies: float | ndarray[float]) → ndarray[float]#

Amplitude spectral density (ASD) of the detector at given frequencies.

build_train_test_subsets(train_size: int | float, random_seed: int = None)#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

export_strains_to_gwf(path: str, channel: str, t0_gps: float = 0, verbose=False) → None#: Export all strains to GWF format, one file per strain.

find_class(id)#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

gen_injections(snr: int | float | list, pad: int = 0, randomize_noise: bool = False, random_seed: int = None, injections_per_snr: int = 1, verbose=False)[source]#

Inject all strains in simulated noise with the given SNR values.

See ‘BaseInjected.gen_injections’ for more details.

Parameters:

snrint | float | list

padint

Number of zeros to pad the signal at both ends before the injection.

randomize_noisebool

If True, the noise segment is randomly chosen before the injection. This can be used to avoid having the same noise injected for all clean strains. False by default.

NOTE: To avoid the possibility of repeating the same noise section in different injections, the noise realization must be reasonably large, e.g:

noise_length > n_clean_strains * self.max_length * len(snr)

random_seedint, optional

Random seed for the noise realization. Only used when randomize_noise is True.

injections_per_snrint

Number of injections per SNR value. 1 by default.

Raises:

ValueError: Once injections have been performed at a certain SNR value, there cannot be injected again at the same value. Trying it will trigger this exception.

Notes

If whitening is intended to be applied afterwards it is useful to pad the signal in order to avoid the window vignetting produced by the whitening itself. This pad will be cropped afterwards.
New injections are stored in the ‘strains’ atrribute, with the pad associated to all the injections performed at once. Even when whitening is also performed right after the injections.

get_strain(*indices, normalize=False) → ndarray#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length: int = None, classes: str | list = 'all', snr: int | list | str = 'all', with_metadata: bool = False)#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Allows the possibility to filter by class and SNR.

NOTE: Same signals injected at different SNR are stacked continuously.

Parameters:

lengthint, optional

Target length of the ‘test_array’. If None, the longest signal determines the length.

classesstr | list[str]

Whitelist of classes to include in the stack. All classes are included by default.

snrint | list[int] | str

Whitelist of SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` eos0 id0 snr0 eos0 id0 snr1

…

```

All injections are included by default.

with_metadatabool

Returns:

test_arraynp.ndarray: Test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.
metadatapd.DataFrame, optional: If ‘with_metadata’ is True, the associated metadata is returned with its entries in the same order as the ‘test_array’.

get_xtrain_array(length: int = None, classes: str | list = 'all', snr: int | list | str = 'all', with_metadata: bool = False)#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Allows the possibility to filter by class and SNR.

NOTE: Same signals injected at different SNR are stacked continuously.

Parameters:

lengthint, optional

Target length of the ‘train_array’. If None, the longest signal determines the length.

classesstr | list[str]

Whitelist of classes to include in the stack. All classes are included by default.

snrint | list[int] | str

Whitelist of SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` eos0 id0 snr0 eos0 id0 snr1

…

```

All injections are included by default.

with_metadatabool

Returns:

train_arraynp.ndarray: Train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.
metadatapd.DataFrame, optional: If ‘with_metadata’ is True, the associated metadata is returned with its entries in the same order as the ‘train_array’.

get_ytest_array(classes='all', snr='all', with_id=False, with_index=False)#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: Whitelist of classes to include in the labels. All classes are included by default.
snrint | list[int] | str: Whitelist of SNR injections to include in the labels. All injections are included by default.
with_idbool: If True, return also the related IDs. False by default.
with_indexbool: If True, return also the related GLOBAL indices w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', snr='all', with_id=False, with_index=False)#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: Whitelist of classes to include in the labels. All classes are included by default.
snrint | list[int] | str: Whitelist of SNR injections to include in the labels. All injections are included by default.
with_idbool: If True, return also the related IDs. False by default.
with_indexbool: If True, return also the related GLOBAL indices w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

psd(frequencies: float | ndarray[float]) → ndarray[float]#

Power spectral density (PSD) of the detector at given frequencies.

resample(sample_rate, verbose=False) → None#

Resample strain and time arrays to a constant rate.

This assumes time tracking either with time arrays or with the sampling rate provided during initialization, which will be used to generate the time arrays previous to the resampling.

This method updates the sample_rate and the max_length.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

stack_by_id(id_list: list, length: int = None, snr_included: int | list[int] | str = 'all')#

Stack a subset of strains by ID into a zero-padded 2d-array.

This may allow (for example) to group up strains by their original ID without leaking differnet injections (SNR) of the same strain into different splits.

Parameters:

id_listarray-like

The IDs of the strains to be stacked.

lengthint, optional

The target length of the stacked array. If None, the longest signal determines the length.

snr_includedint | list[int] | str, optional

The SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` id0 snr0 id0 snr1

…

```

All injections are included by default.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Raises:

ValueError: If the value of ‘snr’ is not valid.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(verbose=False)[source]#

Whiten injected strains.

Calling this method performs the whitening of all injected strains. Strains are later cut to their original size before adding the pad, to remove the vigneting.

NOTE: This is an irreversible action; if the original injections need to be preserved it is advised to make a copy of the instance before performing the whitening.

class gwadama.datasets.InjectedSyntheticWaves(clean_dataset: SyntheticWaves, *, psd: ndarray | Callable, detector: str, noise_length: int, freq_cutoff: int | float, freq_butter_order: int | float, random_seed: int)[source]#

Bases: BaseInjected

TODO

Methods

`asd`(frequencies)	Amplitude spectral density (ASD) of the detector at given frequencies.
`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`export_strains_to_gwf`(path, channel[, ...])	Export all strains to GWF format, one file per strain.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`gen_injections`(snr[, pad, randomize_noise, ...])	Inject all strains in simulated noise with the given SNR values.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes, snr, ...])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes, snr, ...])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, snr, with_id, ...])	Get the filtered test labels.
`get_ytrain_array`([classes, snr, with_id, ...])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`psd`(frequencies)	Power spectral density (PSD) of the detector at given frequencies.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`stack_by_id`(id_list[, length, snr_included])	Stack a subset of strains by ID into a zero-padded 2d-array.
`whiten`([verbose])	Whiten injected strains.

__init__(clean_dataset: SyntheticWaves, *, psd: ndarray | Callable, detector: str, noise_length: int, freq_cutoff: int | float, freq_butter_order: int | float, random_seed: int)[source]#

Base constructor for injected datasets.

TODO: Update docstring.

When inheriting from this class, it is recommended to run this method first in your __init__ function.

Relevant attributes are inherited from the ‘clean_dataset’ instance, which can be any inherited from BaseDataset whose strains have not been injected yet.

WARNING: Initializing this class does not perform the injections! For that use the method ‘gen_injections’.

Parameters:

clean_datasetBase

Instance of a Class(Base) with noiseless signals.

psdnp.ndarray | Callable

` psd[0] = frequency_samples psd[1] = psd_samples `.

NOTE: It is also used to compute the ‘asd’ attribute (ASD).

detectorstr

GW detector name. Not used, just for identification.

noise_lengthint

Length of the background noise array to be generated for later use. It should be at least longer than the longest signal expected to be injected.

freq_cutoffint | float

Frequency cutoff below which no noise bins will be generated in the frequency space, and also used for the high-pass filter applied to clean signals before injection.

freq_butter_orderint | float

Butterworth filter order. See (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html) for more information.

flengthint

Length (in samples) of the time-domain FIR whitening filter.

whiten_paramsdict, optional

Parameters of the whitening filter, with the following entries:

‘flength’int
Length (in samples) of the time-domain FIR whitening.
‘highpass’float
Frequency cutoff.
‘normed’bool
Normalization applied after the whitening filter.

random_seedint, optional

asd(frequencies: float | ndarray[float]) → ndarray[float]#

Amplitude spectral density (ASD) of the detector at given frequencies.

build_train_test_subsets(train_size: int | float, random_seed: int = None)#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

export_strains_to_gwf(path: str, channel: str, t0_gps: float = 0, verbose=False) → None#: Export all strains to GWF format, one file per strain.

find_class(id)#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

gen_injections(snr: int | float | list, pad: int = 0, randomize_noise: bool = False, random_seed: int = None, injections_per_snr: int = 1, verbose=False)#

Inject all strains in simulated noise with the given SNR values.

The SNR is computed using a matched filter against the noise PSD.
If pad > 0, it also updates the time arrays.
If strain units are in geometrized, they will be converted first to IS, injected, and converted back to geometrized.
After each injection, applies a highpass filter at the low-cut frequency specified at __init__.
If the method ‘whiten’ has been already called, all further injections will automatically be whitened and their pad removed.

Parameters:

snrint | float | list

padint

Number of zeros to pad the signal at both ends before the injection.

randomize_noisebool

If True, the noise segment is randomly chosen before the injection. This can be used to avoid having the same noise injected for all clean strains. False by default.

NOTE: To avoid the possibility of repeating the same noise section in different injections, the noise realization must be reasonably large, e.g:

noise_length > n_clean_strains * self.max_length * len(snr)

random_seedint, optional

Random seed for the noise realization. Only used when randomize_noise is True.

injections_per_snrint

Number of injections per SNR value. Defaults to 1.

This is useful to minimize the statistical impact of the noise when performing injections at a sensitive (low) SNR.

Raises:

ValueError: Once injections have been performed at a certain SNR value, there cannot be injected again at the same value. Trying it will trigger this exception.

Notes

If whitening is intended to be applied afterwards it is useful to pad the signal in order to avoid the window vignetting produced by the whitening itself. This pad will be cropped afterwards.
New injections are stored in the ‘strains’ atrribute, with the pad associated to all the injections performed at once. Even when whitening is also performed right after the injections.

get_strain(*indices, normalize=False) → ndarray#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length: int = None, classes: str | list = 'all', snr: int | list | str = 'all', with_metadata: bool = False)#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Allows the possibility to filter by class and SNR.

NOTE: Same signals injected at different SNR are stacked continuously.

Parameters:

lengthint, optional

Target length of the ‘test_array’. If None, the longest signal determines the length.

classesstr | list[str]

Whitelist of classes to include in the stack. All classes are included by default.

snrint | list[int] | str

Whitelist of SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` eos0 id0 snr0 eos0 id0 snr1

…

```

All injections are included by default.

with_metadatabool

Returns:

test_arraynp.ndarray: Test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.
metadatapd.DataFrame, optional: If ‘with_metadata’ is True, the associated metadata is returned with its entries in the same order as the ‘test_array’.

get_xtrain_array(length: int = None, classes: str | list = 'all', snr: int | list | str = 'all', with_metadata: bool = False)#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Allows the possibility to filter by class and SNR.

NOTE: Same signals injected at different SNR are stacked continuously.

Parameters:

lengthint, optional

Target length of the ‘train_array’. If None, the longest signal determines the length.

classesstr | list[str]

Whitelist of classes to include in the stack. All classes are included by default.

snrint | list[int] | str

Whitelist of SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` eos0 id0 snr0 eos0 id0 snr1

…

```

All injections are included by default.

with_metadatabool

Returns:

train_arraynp.ndarray: Train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.
metadatapd.DataFrame, optional: If ‘with_metadata’ is True, the associated metadata is returned with its entries in the same order as the ‘train_array’.

get_ytest_array(classes='all', snr='all', with_id=False, with_index=False)#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: Whitelist of classes to include in the labels. All classes are included by default.
snrint | list[int] | str: Whitelist of SNR injections to include in the labels. All injections are included by default.
with_idbool: If True, return also the related IDs. False by default.
with_indexbool: If True, return also the related GLOBAL indices w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', snr='all', with_id=False, with_index=False)#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: Whitelist of classes to include in the labels. All classes are included by default.
snrint | list[int] | str: Whitelist of SNR injections to include in the labels. All injections are included by default.
with_idbool: If True, return also the related IDs. False by default.
with_indexbool: If True, return also the related GLOBAL indices w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

psd(frequencies: float | ndarray[float]) → ndarray[float]#

Power spectral density (PSD) of the detector at given frequencies.

resample(sample_rate, verbose=False) → None#

Resample strain and time arrays to a constant rate.

This assumes time tracking either with time arrays or with the sampling rate provided during initialization, which will be used to generate the time arrays previous to the resampling.

This method updates the sample_rate and the max_length.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

stack_by_id(id_list: list, length: int = None, snr_included: int | list[int] | str = 'all')#

Stack a subset of strains by ID into a zero-padded 2d-array.

This may allow (for example) to group up strains by their original ID without leaking differnet injections (SNR) of the same strain into different splits.

Parameters:

id_listarray-like

The IDs of the strains to be stacked.

lengthint, optional

The target length of the stacked array. If None, the longest signal determines the length.

snr_includedint | list[int] | str, optional

The SNR injections to include in the stack. If more than one are selected, they are stacked zipped as follows:

``` id0 snr0 id0 snr1

…

```

All injections are included by default.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Raises:

ValueError: If the value of ‘snr’ is not valid.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(verbose=False)#

Whiten injected strains.

Calling this method performs the whitening of all injected strains. Strains are later cut to their original size before adding the pad, to remove the vigneting.

NOTE: This is an irreversible action; if the original injections need to be preserved it is advised to make a copy of the instance before performing the whitening.

class gwadama.datasets.SyntheticWaves(*, classes: dict, n_waves_per_class: int, wave_parameters_limits: dict, max_length: int, peak_time_max_length: float, amp_threshold: float, tukey_alpha: float, sample_rate: int, random_seed: int = None)[source]#

Bases: Base

Class for building synthetically generated wavforms and background noise.

Part of the datasets for the CLAWDIA main paper.

The classes are hardcoded:

SG: Sine Gaussian,

G: Gaussian,

RD: Ring-Down.

Attributes:

classesdict: Dict of strings and their integer labels, one per class (category).
strainsdict {class: {key: gw_strains} }: Strains stored as a nested dictionary, with each strain in an independent array to provide more flexibility with data of a wide range of lengths. The class key is the name of the class, a string which must exist in the ‘classes’ attribute. The ‘key’ is an identifier of each strain. In this case it’s just the global index ranging from 0 to ‘self.n_samples’.
labelsNDArray[int]: Indices of the classes, one per waveform. Each one points its respective waveform inside ‘strains’ to its class in ‘classes’. The order is that of the index of ‘self.metadata’, and coincides with the order of the strains inside ‘self.strains’ if unrolled to a flat list of arrays.
metadatapandas.DataFrame: All parameters and data related to the strains. The order is the same as inside ‘strains’ if unrolled to a flat list of strains.
train_sizeint | float: If int, total number of samples to include in the train dataset. If float, fraction of the total samples to include in the train dataset. For more details see ‘sklearn.model_selection.train_test_split’ with the flag stratified=True.
unitsstr: Flag indicating whether the data is in ‘geometrized’ or ‘IS’ units.
Xtrain, Xtestdict {key: strain}: Train and test subsets randomly split using SKLearn train_test_split function with stratified labels. The key corresponds to the strain’s index at ‘self.metadata’.
Ytrain, YtestNDArray[int]: 1D Array containing the labels in the same order as ‘Xtrain’ and ‘Xtest’ respectively.

Methods

`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, with_id, with_index])	Get the filtered test labels.
`get_ytrain_array`([classes, with_id, with_index])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`stack_by_id`(id_list[, length])	Stack an subset of strains by their ID into a Numpy array.
`whiten`([asd_array, pad, highpass, flength, ...])	Whiten the strains.

__init__(*, classes: dict, n_waves_per_class: int, wave_parameters_limits: dict, max_length: int, peak_time_max_length: float, amp_threshold: float, tukey_alpha: float, sample_rate: int, random_seed: int = None)[source]#

Parameters:

n_waves_per_classint

Number of waves per class to produce.

wave_parameters_limitsdict

Min/Max limits of the waveforms’ parameters, 9 in total. Keys:

mf0, Mf0: min/Max central frequency (SG and RD).
mQ, MQ: min/Max quality factor (SG and RD).
mhrss, Mhrss: min/Max sum squared amplitude of the wave.
mT, MT: min/Max duration (only G).

max_lengthint

Maximum length of the waves. This parameter is used to generate the initial time array with which the waveforms are computed.

peak_time_max_lengthfloat

Time of the peak of the envelope of the waves in the initial time array (built with ‘max_length’).

amp_thresholdfloat

Fraction w.r.t. the maximum absolute amplitude of the wave envelope below which to end the wave by shrinking the array and applying a windowing to the edges.

tukey_alphafloat

Alpha parameter (width) of the Tukey window applied to each wave to make sure their values end at the exact duration determined by either the duration parameter or the amplitude threshold.

sample_rateint

random_seedint, optional.

build_train_test_subsets(train_size: int | float, random_seed: int = None)#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

find_class(id)#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

get_strain(*indices, normalize=False) → ndarray#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length=None, classes='all')#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

test_arraynp.ndarray: test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.

get_xtrain_array(length=None, classes='all')#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional: Target length of the ‘train_array’. If None, the longest signal determines the length.
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

train_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_ytest_array(classes='all', with_id=False, with_index=False)#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', with_id=False, with_index=False)#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

resample(sample_rate, verbose=False) → None#

Resample strain and time arrays to a constant rate.

This assumes time tracking either with time arrays or with the sampling rate provided during initialization, which will be used to generate the time arrays previous to the resampling.

This method updates the sample_rate and the max_length.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

stack_by_id(id_list: list, length: int = None)#

Stack an subset of strains by their ID into a Numpy array.

Stack an arbitrary selection of strains by their original ID into a zero-padded 2d-array. The resulting order is the same as the order of that in ‘id_list’.

Parameters:

id_listlist: The IDs of the strains to be stacked.
lengthint, optional: The target length of the stacked array. If None, the longest signal determines the length.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(asd_array: ndarray = None, pad: int = 0, highpass: int = None, flength: float = None, normed: bool = False, verbose=False) → None#

Whiten the strains.

Calling this method performs the whitening of all strains. Optionally, strains are first zero-padded, whitened and then shrunk to their initial size. This is useful to remove the vignetting effect.

NOTE: Original (non-whitened) strains will be stored in the ‘nonwhiten_strains’ attribute.

class gwadama.datasets.UnlabeledWaves(strains_array, strain_limits=None, sample_rate=None, random_seed=None)[source]#

Bases: Base

Dataset class for clean gravitational wave signals without labels.

This class extends Base, modifying its behavior to handle datasets where gravitational wave signals are provided without associated labels. Unlike Base, it does not require a classification structure but retains methods for loading, storing, and managing waveform data.

The dataset consists of nested dictionaries, storing each waveform in an independent array to accommodate variable lengths.

Notes

Unlike Base, this class does not track class labels.
Train/Test split is still supported but is not stratified.

Attributes:

strainsdict: Dictionary of stored waveforms, indexed by unique identifiers.
max_lengthint: Length of the longest waveform in the dataset.
sample_rateint, optional: The constant sampling rate for the waveforms, if provided.
Xtrain, Xtestdict, optional: Train and test subsets randomly split using train_test_split, if required. These are views into strains, without associated labels.

Methods

`build_train_test_subsets`(train_size[, ...])	Generate a random Train and Test subsets.
`find_class`(id)	Find which 'class' corresponds the strain 'id'.
`get_strain`(*indices[, normalize])	Get a single strain from the complete index coordinates.
`get_strains_array`([length])	Get all strains stacked in a zero-padded Numpy 2d-array.
`get_times`(*indices)	Get a single time array from the complete index coordinates.
`get_xtest_array`([length, classes])	Get the test subset stacked in a zero-padded Numpy 2d-array.
`get_xtrain_array`([length, classes])	Get the train subset stacked in a zero-padded Numpy 2d-array.
`get_ytest_array`([classes, with_id, with_index])	Get the filtered test labels.
`get_ytrain_array`([classes, with_id, with_index])	Get the filtered training labels.
`items`()	Return a new view of the dataset's items with unrolled indices.
`keys`([max_depth])	Return the unrolled combinations of all strain identifiers.
`pad_strains`(padding)	Pad strains with zeros on both sides.
`resample`(sample_rate[, verbose])	Resample strain and time arrays to a constant rate.
`shrink_strains`(limits)	Shrink strains to a specific interval.
`stack_by_id`(id_list[, length])	Stack an subset of strains by their ID into a Numpy array.
`whiten`([asd_array, pad, highpass, flength, ...])	Whiten the strains.

__init__(strains_array, strain_limits=None, sample_rate=None, random_seed=None)[source]#

Initialize an UnlabeledWaves dataset.

This constructor processes a NumPy array of gravitational wave signals, storing them in a structured dictionary while optionally discarding unnecessary zero-padding. Unlike Base, this class does not require labeled categories or metadata but retains support for dataset splitting and signal management.

Parameters:

strains_arraynp.ndarray: A 2D array containing gravitational wave signals, where each row represents a separate waveform, possibly zero-padded.
strain_limitslist[tuple[int, int]] | None, optional: A list of (start, end) indices defining the valid range for each waveform in strains_array. If None, waveforms are assumed to contain no unnecessary padding.
sample_rateint, optional: The assumed constant sampling rate for the waveforms. If None, time tracking is disabled.
random_seedint, optional: Seed for random operations such as dataset splitting, ensuring reproducibility.

Notes

A dummy class label (‘unique’: 1) is assigned for compatibility.
Metadata is omitted in this class.
The dataset structure supports train/test splitting, but labels are not relevant.

build_train_test_subsets(train_size: int | float, random_seed: int = None)#

Generate a random Train and Test subsets.

Only indices in the ‘labels’ attribute are considered independent waveforms, any extra key (layer) in the ‘strains’ dict is treated monolithically during the shuffle.

The strain values are just new views into the ‘strains’ attribute. The shuffling is performed by Scikit-Learn’s function ‘train_test_split’, with stratification enabled.

Parameters:

train_sizeint | float

If float, should be between 0.0 and 1.0 and represent the proportion of the dataset to include in the train subset. If int, represents the absolute number of train waves.

Ref: https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html

random_seedint, optional

Passed directly to ‘sklearn.model_selection.train_test_split’. It is also saved in its homonymous attribute.

find_class(id)#

Find which ‘class’ corresponds the strain ‘id’.

Finds the ‘class’ of the strain represented by the unique identifier ‘id’.

Parameters:

idstr: Unique identifier of the string, that which also appears in the metadata.index DataFrame.

Returns:

clasint | str: Class key associated to the strain ‘id’.

get_strain(*indices, normalize=False) → ndarray#

Get a single strain from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘strains’ attribute.

Parameters:

*indicesstr | int: The indices of the strain to retrieve.
normalizebool: If True, the returned strain will be normalized to its maximum amplitude.

Returns:

strainnp.ndarray: The requested strain.

get_strains_array(length: int = None) → ndarray#

Get all strains stacked in a zero-padded Numpy 2d-array.

Stacks all signals into an homogeneous numpy array whose length (axis=1) is determined by either ‘length’ or, if None, by the longest strain in the subset. The remaining space is zeroed.

Parameters:

lengthint, optional: Target length of the ‘strains_array’. If None, the longest signal determines the length.

Returns:

strains_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_times(*indices) → ndarray#

Get a single time array from the complete index coordinates.

This is just a shortcut to avoid having to write several squared brackets.

NOTE: The returned strain is not a copy; if its contents are modified, the changes will be reflected inside the ‘times’ attribute.

get_xtest_array(length=None, classes='all')#

Get the test subset stacked in a zero-padded Numpy 2d-array.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

test_arraynp.ndarray: test subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘test_array’.

get_xtrain_array(length=None, classes='all')#

Get the train subset stacked in a zero-padded Numpy 2d-array.

Optionally, classes can be filtered by specifying which to include with the classes parameter.

Parameters:

lengthint, optional: Target length of the ‘train_array’. If None, the longest signal determines the length.
classesstr | List[str], optional: Specify which classes to include. Include ‘all’ by default.

Returns:

train_arraynp.ndarray: train subset.
lengthslist: Original length of each strain, following the same order as the first axis of ‘train_array’.

get_ytest_array(classes='all', with_id=False, with_index=False)#

Get the filtered test labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtest_array’ WITHOUT filters.

Returns:

np.ndarray: Filtered test labels.
np.ndarray, optional: IDs associated to the filtered test labels.
np.ndarray, optional: Indices associated to the filtered test labels.

get_ytrain_array(classes='all', with_id=False, with_index=False)#

Get the filtered training labels.

Parameters:

classesstr | list[str] | ‘all’: The classes to include in the labels. All classes are included by default.
with_idbool: If True, return also the list of related IDs.
with_indexbool: If True, return also the related GLOBAL indices; w.r.t. the stacked arrays returned by ‘get_xtrain_array’ WITHOUT filters. False by default.

Returns:

np.ndarray: Filtered train labels.
np.ndarray, optional: IDs associated to the filtered train labels.
np.ndarray, optional: Indices associated to the filtered train labels.

items()#

Return a new view of the dataset’s items with unrolled indices.

Each iteration consists on a tuple containing all the nested keys in ‘self.strains’ along with the corresponding strain, (clas, id, *, strain).

It can be thought of as an extension of Python’s dict.items(). Useful to quickly iterate over all items in the dataset.

Example of usage with an arbitrary number of keys in the nested dictionary of strains:

``` for *keys, strain in self.items():

print(f”Number of identifiers: {len(keys)}”) print(f”Length of the strain: {len(strain)}”) do_something(strain)

```

keys(max_depth: int = None) → list#

Return the unrolled combinations of all strain identifiers.

Return the unrolled combinations of all keys of the nested dictionary of strains by a hierarchical recursive search.

It can be thought of as the extended version of Python’s ‘dict().keys()’, although this returns a plain list.

Parameters:

max_depthint, optional: If specified, it is the number of layers to iterate to at most in the nested ‘strains’ dictionary.

Returns:

keyslist: The unrolled combination in a Python list.

pad_strains(padding: int | tuple | dict) → None#

Pad strains with zeros on both sides.

This function pads each strain with a specific number of samples on both sides. It also updates the ‘max_length’ attribute to reflect the new maximum length of the padded strains.

Parameters:

paddingint | tuple | dict: The padding to apply to each strain. If padding is an integer, it will be applied at both sides of all strains. If padding is a tuple, it must be of the form (left_pad, right_pad) in samples. If padding is a dictionary, it must be of the form {id: (left_pad, right_pad)}, where id is the identifier of each strain.

Notes

If time arrays are present, they are also padded accordingly.

resample(sample_rate, verbose=False) → None#

Resample strain and time arrays to a constant rate.

This assumes time tracking either with time arrays or with the sampling rate provided during initialization, which will be used to generate the time arrays previous to the resampling.

This method updates the sample_rate and the max_length.

Parameters:

sample_rateint: The new sampling rate in Hz.
verbosebool: If True, print information about the resampling.

shrink_strains(limits: tuple | dict) → None#

Shrink strains to a specific interval.

Shrink strains (and their associated time arrays if present) to the interval given by ‘limits’.

It also updates the ‘max_length’ attribute.

Parameters:

limitstuple | dict

NOTE: If extra layers below ID are present, they will be shrunk accordingly.

stack_by_id(id_list: list, length: int = None)#

Stack an subset of strains by their ID into a Numpy array.

Stack an arbitrary selection of strains by their original ID into a zero-padded 2d-array. The resulting order is the same as the order of that in ‘id_list’.

Parameters:

id_listlist: The IDs of the strains to be stacked.
lengthint, optional: The target length of the stacked array. If None, the longest signal determines the length.

Returns:

stacked_signalsnp.ndarray: The array containing the stacked strains.
lengthslist: The original lengths of each strain, following the same order as the first axis of ‘stacked_signals’.

Notes

Unlike in ‘get_xtrain_array’ and ‘get_xtest_array’, this method does not filter by ‘classes’ since it would be redundant, as IDs are unique.

whiten(asd_array: ndarray = None, pad: int = 0, highpass: int = None, flength: float = None, normed: bool = False, verbose=False) → None#

Whiten the strains.

Calling this method performs the whitening of all strains. Optionally, strains are first zero-padded, whitened and then shrunk to their initial size. This is useful to remove the vignetting effect.

NOTE: Original (non-whitened) strains will be stored in the ‘nonwhiten_strains’ attribute.