API Reference

Blast

class lightguide.blast.Blast(data: ndarray, start_time: datetime, sampling_rate: float, start_channel: int = 0, channel_spacing: float = 0.0, unit: Literal['strain rate', 'strain', 'acceleration', 'velocity', 'displacement'] = 'strain rate')

Bases: object

A Blast represents a time-space patch from a DAS recording.

afk_filter(exponent: float = 0.8, window_size: int = 16, overlap: int = 7, normalize_power: bool = False) → None

Apply adaptive frequency filter (AFK) in-place.

The adaptive frequency filter (AFK) can be used to suppress incoherent noise in DAS data and other spatially coherent data sets.

Parameters:

• window_size (int) – Square window size. Defaults to 16.

• overlap (int) – Overlap of neighboring windows. Defaults to 7.

• exponent (float) – Filter strength, between 0.0 and 1.0. Defaults to 0.8.

• normalize_power (bool) – Normalize the power. Defaults to True.

as_traces() → list[pyrocko.trace.Trace]

Converts the data in the Blast object into Pyrocko’s Trace format.

Returns:

A list of Pyrocko Trace instances,

one for each channel in the data.

Return type:

list[Trace]

bandpass(min_freq: float, max_freq: float, order: int = 4, demean: bool = True, zero_phase: bool = False) → None

Apply band-pass filter in-place using a Butterworth filter.

Parameters:

• min_freq (float) – Lower corner of the band pass filter in Hz.

• max_freq (float) – Upper corner of the band pass filter in Hz.

• order (int, optional) – Order of the filter. Defaults to 4.

• demean (bool, optional) – Remove mean before filtering. Defaults to True.

• zero_phase (bool, optional) – Use zero phase filter. Defaults to True.

copy() → Blast

Return a copy of the blast.

Returns:

Copied blast.

Return type:

Blast

decimate(factor: int, demean: bool = True) → None

Decimate in time-domain by a factor, in-place.

Parameters:

• factor (int) – Decimation factor, must be > 1.

• demean (bool) – Demean signal before decimation. Defaults to True

property delta_t: float

Sampling interval in seconds.

detrend(type: Literal['linear', 'constant'] = 'linear') → None

Demean and detrend in time-domain in-place.

Parameters:

• type (Literal["linear", "constant"], optional) – he type of detrending.

• 'linear' (If type ==) –

• 'constant' (to data is subtracted from data. If type ==) –

:param : :param only the mean of data is subtracted.. Defaults to “linear”.:

property duration: float

Duration in seconds.

property end_channel: int

End Channel.

property end_time: datetime

End time of the Blast.

follow_phase(pick_time: datetime, pick_channel: int, window_size: int | tuple[int, int] = 50, threshold: float = 0.5, max_shift: int = 20) → tuple[numpy.ndarray, list[datetime.datetime], numpy.ndarray]

Follow a phase pick through a Blast.

This function leverages the spatial coherency of a DAS data set. Following a phase through iterative cross-correlation of neighboring traces:

1. Get windowed root pick template.

2. Calculate normalized cross correlate with downwards neighbor.

3. Evaluate maximum x-correlation in allowed window (max_shift).

4. Update template trace and go to 2.

5. Repeat for upward neighbors.

Parameters:

• pick_time (datetime) – Initial pick in the data set.

• pick_channel (int) – Corresponding channel for the initial pick.

• window_size (int | tuple[int, int], optional) – Window size around the pick for the correlation template. If an integer is given it is the half-width. A Tuple gives pre- and post-windows. Defaults to 50.

• threshold (float, optional) – Picking threshold for the cross correlation. Defaults to 5e-1.

• max_shift (int, optional) – Maximum allowed shift in samples for neighboring picks. Defaults to 20.

Returns:

Tuple of channel number,

pick time and maximum correlation coefficient.

Return type:

tuple[np.ndarray, list[datetime], np.ndarray]

classmethod from_miniseed(file: Union[Path, str], channel_spacing: float = 4.0) → Blast

Load Blast from miniSEED.

Parameters:

• file (PathStr) – miniSEED file to load from.

• channel_spacing (float, optional) – Channel spacing in meters. Defaults to 4.0.

Returns:

Produced Blast.

Return type:

Blast

classmethod from_pyrocko(traces: list[pyrocko.trace.Trace], channel_spacing: float = 4.0) → Blast

Create Blast from a list of Pyrocko traces.

Parameters:

• traces (list[Trace]) – List of input traces

• channel_spacing (float, optional) – Spatial channel spacing in meter. Defaults to 0.0.

Raises:

ValueError – If input is odd.

Returns:

Assembled Blast.

Return type:

Blast

get_trace(channel: int) → ndarray

Get data from a singular channel.

Parameters:

channel (int) – Channel number.

Returns:

1D Trace.

Return type:

np.ndarray

highpass(cutoff_freq: float, order: int = 4, demean: bool = True, zero_phase: bool = False) → None

Apply high-pass filter in-place using a Butterworth filter.

Parameters:

• cutoff_freq (float) – cutoff frequency of the highpass filter.

• order (int) – order of the filter. Default is 4.

• demean – (bool, optional) Remove mean before filtering. Default is True.

• zero_phase (bool, optional) – Use zero phase filter. Defaults to True.

lowpass(cutoff_freq: float, order: int = 4, demean: bool = True, zero_phase: bool = False) → None

Apply low-pass filter in-place using a Butterworth filter.

Parameters:

• cutoff_freq (float) – cutoff frequency of the lowpass filter.

• order (int) – order of the filter

• demean – (Optional) Mean is removed before filtering. Default is True.

• zero_phase (bool, optional) – Use zero phase filter. Defaults to True.

mute_median(level: float = 3.0) → None

Mute signals in the data above a threshold in-place.

Parameters:

level (float, optional) – Median level to mute. Defaults to 3.0.

property n_channels: int

Number of channels.

property n_samples: int

Number of Samples.

one_bit_normalization() → None

Apply one-bit normalization on the trace.

plot(axes: plt.Axes | None = None, normalize_traces: bool = True, cmap: str | Colormap = 'seismic', show_date: bool = False, show_channel: bool = False) → image.AxesImage

Plot data of the blast.

Parameters:

• axes (plt.Axes | None, optional) – Optional axis to plot into. If not given, plt.show() is called. Defaults to None.

• normalize_traces (bool, optional) – Normalize traces in time dimension. Defaults to True.

• cmap (str | Colormap, optional) – Matplotlib colormap. Defaults to “seismic”.

• show_date (bool, optional) – Shot absolute dates in UTC. Defaults to False.

• show_channel (bool, optional) – Show channels instead of meters. Defaults to False.

Returns:

Decorated axes.

Return type:

image.AxesImage

save_mseed(filename: Union[Path, str]) → None

Save the Blast as miniSeed.

Parameters:

filename (PathStr) – File to write to.

taper(alpha: float = 0.05) → None

Taper in time-domain and in-place with a Tukey window.

Parameters:

alpha (float, optional) – Shape parameter of the Tukey window, representing the fraction of the window inside the cosine tapered region. If zero, the Tukey window is equivalent to a rectangular window. If one, the Tukey window is equivalent to a Hann window. Defaults to 0.05.

to_relative_displacement(detrend: bool = True) → Blast

Convert the traces to relative displacement.

Parameters:

detrend (bool, optional) – Detrend trace before spatial integration. Defaults to True.

Raises:

TypeError – Raised when the input Blast is not in strain rate.

Returns:

As strain strain.

Return type:

Blast

to_relative_velocity(detrend: bool = True) → Blast

Convert the traces to relative velocity.

Parameters:

detrend (bool, optional) – Detrend trace before spatial differentiation. Defaults to True.

Raises:

TypeError – Raised when the input blast is not in strain rate.

Returns:

As relative velocity.

Return type:

Blast

to_strain(detrend: bool = True) → Blast

Convert the traces to strain.

Parameters:

detrend (bool, optional) – Detrend trace before integration. Defaults to True.

Raises:

TypeError – Raised when the input Blast is not in strain rate.

Returns:

In strain strain.

Return type:

Blast

trim_channels(begin: int = 0, end: int = -1) → Blast

Trim the Blast to channels and return a copy.

Parameters:

• begin (int, optional) – Begin channel. Defaults to 0.

• end (int, optional) – End channel. Defaults to -1.

Returns:

Trimmed Blast.

Return type:

Blast

trim_time(begin: float = 0.0, end: float = -1.0) → Blast

Trim channel to time frame and return a copy.

Parameters:

• begin (float, optional) – Begin time. Defaults to 0.0.

• end (float, optional) – End time. Defaults to -1.0.

Raises:

ValueError – Raised when begin and end are ill behaved.

Returns:

Trimmed Blast.

Return type:

Blast

Pack

class lightguide.blast.Pack(blasts: Optional[Iterable[Blast]] = None)

Bases: object

afk_filter(exponent: float = 0.8, window_size: int = 16, overlap: int = 7, normalize_power: bool = False) → None

Apply adaptive frequency filter (AFK) in-place.

The adaptive frequency filter (AFK) can be used to suppress incoherent noise in DAS data and other spatially coherent data sets.

Parameters:

• window_size (int) – Square window size. Defaults to 16.

• overlap (int) – Overlap of neighboring windows. Defaults to 7.

• exponent (float) – Filter strength, between 0.0 and 1.0. Defaults to 0.8.

• normalize_power (bool) – Normalize the power. Defaults to True.

bandpass(min_freq: float, max_freq: float, order: int = 4, demean: bool = True, zero_phase: bool = False) → None

Apply band-pass filter in-place using a Butterworth filter.

Parameters:

• min_freq (float) – Lower corner of the band pass filter in Hz.

• max_freq (float) – Upper corner of the band pass filter in Hz.

• order (int, optional) – Order of the filter. Defaults to 4.

• demean (bool, optional) – Remove mean before filtering. Defaults to True.

• zero_phase (bool, optional) – Use zero phase filter. Defaults to True.

decimate(factor: int, demean: bool = True) → None

Decimate in time-domain by a factor, in-place.

Parameters:

• factor (int) – Decimation factor, must be > 1.

• demean (bool) – Demean signal before decimation. Defaults to True

detrend(type: Literal['linear', 'constant'] = 'linear') → None

Demean and detrend in time-domain in-place.

Parameters:

• type (Literal["linear", "constant"], optional) – he type of detrending.

• 'linear' (If type ==) –

• 'constant' (to data is subtracted from data. If type ==) –

:param : :param only the mean of data is subtracted.. Defaults to “linear”.:

highpass(cutoff_freq: float, order: int = 4, demean: bool = True, zero_phase: bool = False) → None

Apply high-pass filter in-place using a Butterworth filter.

Parameters:

• cutoff_freq (float) – cutoff frequency of the highpass filter.

• order (int) – order of the filter. Default is 4.

• demean – (bool, optional) Remove mean before filtering. Default is True.

• zero_phase (bool, optional) – Use zero phase filter. Defaults to True.

lowpass(cutoff_freq: float, order: int = 4, demean: bool = True, zero_phase: bool = False) → None

Apply low-pass filter in-place using a Butterworth filter.

Parameters:

• cutoff_freq (float) – cutoff frequency of the lowpass filter.

• order (int) – order of the filter

• demean – (Optional) Mean is removed before filtering. Default is True.

• zero_phase (bool, optional) – Use zero phase filter. Defaults to True.

mute_median(level: float = 3.0) → None

Mute signals in the data above a threshold in-place.

Parameters:

level (float, optional) – Median level to mute. Defaults to 3.0.

one_bit_normalization() → None

Apply one-bit normalization on the trace.

taper(alpha: float = 0.05) → None

Taper in time-domain and in-place with a Tukey window.

Parameters:

alpha (float, optional) – Shape parameter of the Tukey window, representing the fraction of the window inside the cosine tapered region. If zero, the Tukey window is equivalent to a rectangular window. If one, the Tukey window is equivalent to a Hann window. Defaults to 0.05.

to_relative_displacement(detrend: bool = True) → Blast

Convert the traces to relative displacement.

Parameters:

detrend (bool, optional) – Detrend trace before spatial integration. Defaults to True.

Raises:

TypeError – Raised when the input Pack is not in strain rate.

Returns:

As strain strain.

Return type:

Pack

to_relative_velocity(detrend: bool = True) → Blast

Convert the traces to relative velocity.

Parameters:

detrend (bool, optional) – Detrend trace before spatial differentiation. Defaults to True.

Raises:

TypeError – Raised when the input blast is not in strain rate.

Returns:

As relative velocity.

Return type:

Pack

to_strain(detrend: bool = True) → Blast

Convert the traces to strain.

Parameters:

detrend (bool, optional) – Detrend trace before integration. Defaults to True.

Raises:

TypeError – Raised when the input Pack is not in strain rate.

Returns:

In strain strain.

Return type:

Pack

trim_channels(begin: int = 0, end: int = -1) → Blast

Trim the Pack to channels and return a copy.

Parameters:

• begin (int, optional) – Begin channel. Defaults to 0.

• end (int, optional) – End channel. Defaults to -1.

Returns:

Trimmed Pack.

Return type:

Pack

trim_time(begin: float = 0.0, end: float = -1.0) → Blast

Trim channel to time frame and return a copy.

Parameters:

• begin (float, optional) – Begin time. Defaults to 0.0.

• end (float, optional) – End time. Defaults to -1.0.

Raises:

ValueError – Raised when begin and end are ill behaved.

Returns:

Trimmed Pack.

Return type:

Pack