seidart.routines.arraybuild module

class seidart.routines.arraybuild.Array(channel: str, project_file: str, receiver_file: str, single_precision: bool = True, csvfile: str = None)

Bases: object

Container and plotting helper for receiver time-series data.

The class loads a project file, receiver geometry, and modeled receiver traces for one SeidarT output channel. It provides convenience methods for amplitude correction, section plots, wiggle plots, filtering, f-k analysis, and saving the assembled receiver gather.

alpha_attenuation(phase_velocity, direction='z', material_indice=0, fc=None)

Estimate exponential attenuation for a material and propagation direction.

Parameters:

  • phase_velocity (float) – Phase velocity in m/s.

  • direction (str) – Direction suffix used in the attenuation table, such as "x", "y", or "z".

  • material_indice (int) – Material index to read from the attenuation coefficients table.

  • fc (float, optional) – Center frequency in Hz. If omitted, the seismic source frequency is used.

Returns:

Attenuation coefficient for the requested material and direction.

Return type:

float

amplitude_calculation(distance, alpha, A0=1, spreading='spherical')

Compute attenuated amplitude from absorption and geometric spreading.

Parameters:

  • distance (float) – Source-receiver distance in meters.

  • alpha (float) – Exponential attenuation coefficient.

  • A0 (float) – Initial amplitude before attenuation. Defaults to 1.

  • spreading (str) – Geometric spreading model. Supported values are "spherical", "cylindrical", and any other value for no geometric spreading correction.

Returns:

Tuple (At, dA, dG) containing total amplitude, absorption factor, and geometric spreading factor.

Return type:

tuple[float, float, float]

amplitude_correction(dat: ndarray, correction_type: str = None)
Parameters:

amplitude_correction_type (str) – Correct the amplitudes for geometric spreading (‘GS’)or using an auto gain control function (‘AGC’); Default is None

build()

Constructs domain and models based on project file and sets up source and receiver configurations.

butterworth_filter(filter_type: str, lowcut: float = None, highcut: float = None, order: int = 4, taper_duration: float = 0.0, pad_samples: int = 100)

Unified seismic filter with tapering and padding.

Parameters:

  • filter_type (str) – ‘lowpass’, ‘highpass’, or ‘bandpass’

  • lowcut (float, optional) – Lower cutoff frequency in Hz (used for ‘highpass’ and ‘bandpass’)

  • highcut (float, optional) – Upper cutoff frequency in Hz (used for ‘lowpass’ and ‘bandpass’)

  • order (int) – Butterworth filter order

  • taper_duration (float) – Duration in seconds for a pre-arrival taper (default = 0.0, no taper)

  • pad_samples (int) – Number of samples to pad symmetrically at top and bottom

  • Result

  • ------

  • self.timeseries) (Sets self.timeseries_filtered (same shape as)

fk_analysis(d_rcx: float, ntfft: int | None = None, nxfft: int | None = None, taper: str | bool = 'time', figure_size: Tuple[float, float] = (10, 8), colormap: str = 'viridis', contour_levels: int = 100, frequency_limits: Tuple[float, float] = None, wavenumber_limits: Tuple[float, float] = None, wavenumber_units: str = 'cycles', use_filtered: bool = True, to_db: str | bool = 'normalized', mode_lines: dict | None = None, mask_db: float = -40)

Compute and plot the frequency–wavenumber (f-k) power spectrum of the time series for a regularly spaced seismic receiver array.

Applies a 2D FFT to the array, with optional tapering, zero-padding, and amplitude-to-dB conversion. Overlays theoretical mode dispersion curves if provided.

Parameters:

  • d_rcx (float) – Receiver spacing in meters.

  • ntfft (int, optional) – Number of FFT points in time. If None, defaults to the number of time samples.

  • nxfft (int, optional) – Number of FFT points in space. If None, defaults to the number of receivers.

  • taper ({'time', 'space', 'both', 'tukey_time', 'tukey_space', 'tukey_both', False}, default='time') – Apply a Hanning taper in the specified direction(s) to suppress spectral leakage.

  • figure_size (tuple of float, default=(10, 8)) – Size of the matplotlib figure in inches.

  • colormap (str, default='viridis') – Colormap used for plotting the contour.

  • contour_levels (int, default=100) – Number of levels in the contour plot.

  • frequency_limits (tuple of float, optional) – y-axis limits for frequency (min, max) in Hz.

  • wavenumber_limits (tuple of float, optional) – x-axis limits for wavenumber (min, max) in cycles/m or rad/m.

  • wavenumber_units ({'cycles', 'radians'}, default='cycles') – Units of the wavenumber axis. Affects velocity overlays.

  • use_filtered (bool, default=True) – Whether to use the filtered time series (self.timeseries_filtered) or raw (self.timeseries).

  • to_db ({'normalized', 'raw', True, False}, default='normalized') – If ‘normalized’, converts to decibel scale with 0 dB peak normalization. If ‘raw’, converts to decibels without normalization. If False, keeps the amplitude linear.

  • mode_lines (dict, optional) – A dictionary of dispersion curves to overlay. Each key is a label (e.g., “Rayleigh”), and each value is either a velocity or a (velocity, color) tuple.

  • Sets

  • ----

  • self.fk_freqs (ndarray) – Frequency axis in Hz.

  • self.fk_wavenumbers (ndarray) – Wavenumber axis in cycles/m or rad/m.

  • self.fk_spectrum (ndarray) – The 2D FFT power spectrum (in dB or linear units depending on to_db).

  • self.fk_velocities (ndarray) – Phase velocity grid (freqs / wavenumbers).

  • self.fk_power_linear (ndarray) – Linear (non-dB) power spectrum.

  • self.fig_fk (matplotlib.figure.Figure) – The matplotlib figure object for the plot.

  • self.ax_fk (matplotlib.axes.Axes) – The matplotlib axes object for the plot.

Raises:

ValueError – If FFT sizes are smaller than the input array dimensions, or if cutoff frequency limits are invalid.

getrcx()

Loads the time series data for all receivers

loadxyz()

Loads and sorts receiver locations from a file and adjusts them according to the domain and CPML layer. If the source_file flag is True, the source file is loaded instead of the receiver file and saved to the object under source.

Parameters:

source_file (bool) – Flag to indicate if the file is a source file.

multichannel_analysis(velocity_limits: Tuple[float, float] = (100, 2000), frequency_limits: Tuple[float, float] | None = None, n_velocity: int = 500, figure_size: Tuple[float, float] = (10, 8), colormap: str = 'viridis', mask_db: float = -40, vmax: float | None = None, smooth_sigma: float = 0.75)

Compute and plot the frequency–velocity (f–c) dispersion image from f–k spectrum.

Parameters:

  • velocity_limits (tuple of float) – Range of phase velocities (min, max) in m/s.

  • frequency_limits (tuple of float, optional) – Frequency range (Hz) to display.

  • n_velocity (int, default=500) – Number of velocity bins.

  • figure_size (tuple of float, default=(10, 8)) – Size of the plot.

  • colormap (str, default='viridis') – Matplotlib colormap.

  • mask_db (float, default=-40) – Threshold below which to mask values (in dB).

  • vmax (float, optional) – Max value for dB color range.

  • smooth_sigma (float, default=0.75) – Gaussian smoothing factor.

save(save_object=True, output_basefile=None)

Save the object as a pickle formatted file and the numpy array of receiver time series to a CSV.

sectionplot(amplitude_correction_type: str = None, colormap: str = 'Greys', figure_size: Tuple[float, float] = (8, 8), use_filtered: bool = False)

Creates a grayscale section plot of the time series data.

Parameters:

  • amplitude_correction_type (str) – Correct the amplitudes for geometric spreading (‘GS’) or using an auto gain control function (‘AGC’); Default is None.

  • colormap (str) – Specify the colormap to be used in the plot. Default is grey.

  • figure_size (Tuple) – Specify the figure size.

sectionwiggleplot(receiver_indices: ndarray, scaling_factor: float = 1.0, plot_vertical=False, positive_fill_color=None, negative_fill_color=None, figure_size: Tuple[float, float] = (5, 8), amplitude_correction_type=None, yaxis_label: str = 'Source-Receiver Distance (m)', gridded: bool = True, use_filtered: bool = False)

Plots a seismic or electromagnetic record section using wiggle traces. This function generates a wiggle plot for the selected receiver traces, with options for vertical plotting, scaling, and amplitude corrections. The positive and negative amplitudes can be filled with custom colors.

Parameters:

  • receiver_indices (np.ndarray) – An array of indices specifying which receiver traces to plot.

  • scaling_factor (float, optional) – A scaling factor for adjusting the amplitude of the traces (default is 1.0).

  • plot_vertical (bool, optional) – If True, plots the traces vertically rather than horizontally (default is False).

  • positive_fill_color (str, optional) – Color to fill the positive amplitudes of the traces. Use any valid matplotlib color (default is None).

  • negative_fill_color (str, optional) – Color to fill the negative amplitudes of the traces. Use any valid matplotlib color (default is None).

  • figure_size (Tuple[float, float], optional) – Size of the figure in inches (default is (5, 8)).

  • amplitude_correction_type (str, optional) – Type of amplitude correction to apply before plotting. This should be a valid correction type recognized by the amplitude_correction method (default is None).

  • yaxis_label (str) – The label corresponding to the y-axis if not using source-receiver distance.

  • gridded – Specify if a gridded plot should be created. Grids will be drawn in vertically for a horizontally oriented graph (default) and drawn horizontally for a vertically oriented graph.

Returns:

None

Return type:

None

Notes:

  • Vertical plotting hasn’t yet been implemented

  • Receiver distances is generically named and is merely a time shift in the time series so that they are layed out as a section plot. The traces can be sorted and plotted according to other inputs.

srcrcx_distance()

Compute the source and receiver(s) distance

wiggleplot(receiver_number: int, plot_background: str = 'none', plot_vertical=True, positive_fill_color=None, negative_fill_color=None, figure_size: Tuple[float, float] = (8, 5), use_filtered: bool = False, **kwargs)

Plot an individual receiver from the list of the receiver files. Use indices in the Python reference frame with the first component being 0.

Parameters:

  • receiver_number (int) – Specify the indice of the reciever from the receiver file to plot.

  • plot_background (str) – Specify the plot background color. Default is transparent.

  • figure_size (Tuple[float, float]) – Specify the figure dimensions in inches. Default is (8,5) width and height, respectively.

  • kwargs (dict) – Additional plotting parameters as defined in matplotlib.pyplot.plot.

seidart.routines.arraybuild.main(project_file: str, receiver_file: str, channel: str, rind: bool, single_precision: bool, exaggeration: float, gain: int, plot: bool = False) → None

The main function creating an Array object and triggering plotting or saving actions based on user inputs.

Parameters:

  • project_file (str) – Path to the project file.

  • receiver_file (str) – Path to the receiver file.

  • channel (str) – Data channel to be analyzed.

  • rind (bool) – Flag for coordinate indices.

  • single_precision (bool) – Flag for single precision data.

  • exaggeration (float) – Aspect ratio between the x and y axes for plotting.

  • gain (int) – Smoothing length for the data.

  • plot (bool) – Flag to enable plotting.