das4whales package

Submodules

das4whales.dask_wrap module

dask_wrap.py - Dask wrapper functions for DAS data processing

This module provides functions to wrap up the functions of das4whales in a dask way.

Authors: Léa Bouffaut, Quentin Goestchel Date: 2024

das4whales.dask_wrap.load_das_data(filename, selected_channels, metadata)

Load the DAS data corresponding to the input file name as strain according to the selected channels.

Parameters:

• filename (str) – The full path to the data to load.

• selected_channels (list) – A list containing the start, stop, and step values for selecting channels.

• metadata (dict) – A dictionary filled with metadata (sampling frequency, channel spacing, scale factor, etc.).

Returns:

• np.ndarray – A [channel x sample] numpy array containing the strain data.

• np.ndarray – The corresponding time axis (s).

• np.ndarray – The corresponding distance along the FO cable axis (m).

• datetime.datetime – The beginning time of the file.

Raises:

ValueError – If the file is not found.

das4whales.dask_wrap.raw2strain(tr, metadata, selected_channels)

Convert a daskarray filled of int32 to a

Parameters:

• tr (dask.array.core.Array) – daskarray built on the HDF5 pointer

• metadata (dict) – dictionary of metadata

• selected_channels (list) – list of selected spatial indexes and spatial step

Returns:

daskarray filled with scaled float64

Return type:

dask.array.core.Array

das4whales.data_handle module

data_handle.py - data handling functions for DAS data

This module provides various functions to handle DAS data, including loading, downloading, and conditioning. It aims at having specific functions for each interrogator type.

Authors: Léa Bouffaut, Quentin Goestchel, Erfan Horeh Date: 2023-2024-2025

das4whales.data_handle.calc_dist_to_xidx(x, selected_channels_m, selected_channels, dx)

Calculate the index of the channel closest to the given distance.

Parameters:

• x (float) – The distance along the cable.

• selected_channels_m (List[float]) – The selected channels in meters.

• selected_channels (List[int]) – The selected channels.

• dx (float) – The distance between two channels.

Returns:

The index of the channel closest to the given distance.

Return type:

int

das4whales.data_handle.dl_file(url)

Download the file at the given url

Parameters:

url (str) – url location of the file

Returns:

filepath – local path destination of the file

Return type:

Tuple[str, str]

das4whales.data_handle.extract_timestamp(filename)

Extract timestamp from filename in format YYYY-MM-DDTHHMMSSZ.

Parameters:

filename (str)

Return type:

Optional[datetime]

das4whales.data_handle.generate_file_list(base_url, start_file, duration)

Generate a list of file URLs that correspond to a given time range, starting from a known file.

Parameters:

• base_url (str) – The base URL where the files are hosted.

• start_file (str) – Filename of the first file to use as reference.

• duration (int) – Duration in seconds.

Returns:

List of full file URLs covering the time range.

Return type:

List[str]

das4whales.data_handle.get_acquisition_parameters(filepath, interrogator='optasense')

Retrieve acquisition parameters based on the specified interrogator.

Parameters:

• filepath (str) – The file path to the data file.

• interrogator (str) – The interrogator type, one of {‘optasense’, ‘silixa’, ‘mars’, ‘alcatel’, ‘onyx’, }. Defaults to ‘optasense’.

Returns:

metadata – Metadata related to the acquisition parameters. Returns None if no matching interrogator is found.

Return type:

Optional[Dict[str, Any]]

Raises:

ValueError – If the interrogator name is not in the predefined list.

das4whales.data_handle.get_cable_lat_lon_depth(file, selected_channels)

Extract latitude, longitude, and depth information from a CSV or TXT file for selected cable channels.

Parameters:

• file (str) – The file path to the CSV or TXT file containing latitude, longitude, and depth information.

• selected_channels (Tuple[int, int, int]) – A tuple containing three integers: (start, stop, step) used to slice and select cable channels.

Returns:

position – A dictionary containing the extracted information for the selected channels: - ‘chan_idx_oj’: list of floats, representing the selected cable channel indices. - ‘lat’: list of floats, representing the selected latitude values. - ‘lon’: list of floats, representing the selected longitude values. - ‘depth’: list of floats, representing the selected depth values in absolute magnitude.

Return type:

Dict[str, List[float]]

das4whales.data_handle.get_metadata_asn(filepath)

Gets DAS acquisition parameters for the ASN interrogator e.g., Svalbard data

Parameters:

filepath (str) – a string containing the full path to the data to load

Returns:

metadata – Dictionary filled with metadata, key’s breakdown:

fs: the sampling frequency (Hz)

dx: interval between two virtual sensing points also called channel spacing (m)

nx: the number of spatial samples also called channels

ns: the number of time samples

GL: the gauge length (m)

scale_factor: the value to convert DAS data to strain (strain rate?)

Return type:

Dict[str, Any]

das4whales.data_handle.get_metadata_fosina_dxs(filepath)

Gets DAS acquisition parameters for the Fosina DxS interrogator

Parameters:

filepath (string) – a string containing the full path to the data to load

Returns:

metadata – dictionary filled with metadata, key’s breakdown:

fs: the sampling frequency (Hz)

dx: interval between two virtual sensing points also called channel spacing (m)

nx: the number of spatial samples also called channels

ns: the number of time samples

n: refractive index of the fiber

GL: the gauge length (m)

scale_factor: the value to convert DAS data from strain rate to strain

Return type:

dict

das4whales.data_handle.get_metadata_onyx(filepath)

Gets DAS acquisition parameters for the onyx interrogator

Parameters:

filepath (str) – a string containing the full path to the data to load

Returns:

metadata – dictionary filled with metadata, key’s breakdown:

fs: the sampling frequency (Hz)

dx: interval between two virtual sensing points also called channel spacing (m)

nx: the number of spatial samples also called channels

ns: the number of time samples

n: refractive index of the fiber

GL: the gauge length (m)

scale_factor: the value to convert DAS data from unwrapped optical phase (rad) to strain

Return type:

Dict[str, Any]

das4whales.data_handle.get_metadata_optasense(filepath)

Gets DAS acquisition parameters for the optasense interrogator e.g., OOI South C1 data

Parameters:

filepath (str) – a string containing the full path to the data to load

Returns:

metadata – dictionary filled with metadata, key’s breakdown:

fs: the sampling frequency (Hz)

dx: interval between two virtual sensing points also called channel spacing (m)

nx: the number of spatial samples also called channels

ns: the number of time samples

n: refractive index of the fiber

GL: the gauge length (m)

scale_factor: the value to convert DAS data from unwrapped optical phase (rad) to strain

Return type:

Dict[str, Any]

das4whales.data_handle.get_metadata_silixa(filepath)

Gets DAS acquisition parameters for the silixa interrogator

Parameters:

filepath (str) – a string containing the full path to the data to load

Returns:

metadata – dictionary filled with metadata, key’s breakdown:

fs: the sampling frequency (Hz)

dx: interval between two virtual sensing points also called channel spacing (m)

nx: the number of spatial samples also called channels

ns: the number of time samples

n: refractive index of the fiber

GL: the gauge length (m)

scale_factor: the value to convert DAS data from unwrapped optical phase (rad) to strain

Return type:

Dict[str, Any]

das4whales.data_handle.get_selected_channels(selected_channels_m, dx)

Get the selected channels in channel numbers.

Parameters:

• selected_channels_m (List[float]) – The selected channels in meters. [ChannelStart_m, ChannelStop_m, ChannelStep_m]

• dx (float) – The distance between two channels.

Returns:

The selected channels in channel numbers. [ChannelStart, ChannelStop, ChannelStep]

Return type:

List[int]

das4whales.data_handle.hello_world_das_package()

Print a hello world message for the package.

Return type:

None

das4whales.data_handle.load_annotation_csv(filepath)

Load the annotation data from a CSV file. The file must include the following columns: ‘file_name’, ‘apex’, ‘offset’, ‘start_time’, ‘whale_side’, as output from the DAS Source Locator annotation application (https://github.com/leabouffaut/DASSourceLocator).

Parameters:

filepath (str) – The file path to the annotation CSV file to load.

Returns:

annotations – A DataFrame containing the following columns: - ‘file_name’: str, names of files - ‘apex’: int, apex values - ‘offset’: int, offset values - ‘start_time’: float, start times - ‘whale_side’: str, indicating the side of the whale (e.g., ‘left’ or ‘right’).

Return type:

DataFrame

das4whales.data_handle.load_cable_coordinates(filepath, dx)

Load the cable coordinates from a text file.

Parameters:

• filepath (str) – The file path to the cable coordinates file.

• dx (float) – The distance between two channels.

Returns:

df – The cable coordinates dataframe.

Return type:

DataFrame

das4whales.data_handle.load_das_data(filename, selected_channels, metadata, interrogator='optasense')

Load the DAS data corresponding to the input file name as strain according to the selected channels.

Parameters:

• filename (str) – A string containing the full path to the data to load.

• selected_channels (List[int]) – A list containing the selected channels.

• metadata (Dict[str, Any]) – A dictionary filled with metadata (sampling frequency, channel spacing, scale factor…).

• interrogator (str)

Return type:

Tuple[ndarray, ndarray, ndarray, datetime]

Returns:

• trace (np.ndarray) – A [channel x sample] nparray containing the strain data.

• tx (np.ndarray) – The corresponding time axis (s).

• dist (np.ndarray) – The corresponding distance along the FO cable axis (m).

• file_begin_time_utc (datetime.datetime) – The beginning time of the file, can be printed using file_begin_time_utc.strftime(“%Y-%m-%d %H:%M:%S”).

das4whales.data_handle.load_mtpl_das_data(filepaths, selected_channels, metadata, timestamp, time_window)

Load the DAS data corresponding to the input file names as strain according to the selected channels. Takes multiple files as input and concatenates them along the time axis starting from the input timestamp for the input time window.

Parameters:

• filepaths (List[str]) – A list containing the full pathes to the data to load.

• selected_channels (List[int]) – A list containing the selected channels.

• metadata (Dict[str, Any]) – A dictionary filled with metadata (sampling frequency, channel spacing, scale factor…).

• timestamp (str) – The timestamp to extract the data from.

• time_window (float) – The time window duration to extract the data from.

Return type:

Tuple[ndarray, ndarray, ndarray, datetime]

Returns:

• trace (np.ndarray) – A [channel x sample] nparray containing the strain data.

• tx (np.ndarray) – The corresponding time axis (s).

• dist (np.ndarray) – The corresponding distance along the FO cable axis (m).

• file_begin_time_utc (datetime.datetime) – The beginning time of the file, can be printed using file_begin_time_utc.strftime(“%Y-%m-%d %H:%M:%S”).

das4whales.data_handle.raw2strain(trace, metadata)

Transform the amplitude of raw das data from unwrapped optical phase (rad) to strain according to scale factor

Parameters:

• trace (ndarray) – a [channel x time sample] nparray containing the raw data in the spatio-temporal domain

• metadata (Dict[str, Any]) – dictionary filled with metadata (fs, dx, nx, ns, n, GL, scale_factor)

Returns:

trace – a [channel x time sample] nparray containing the strain data in the spatio-temporal domain

Return type:

ndarray

das4whales.detect module

detect.py - Detection module of DAS4Whales package

This module provides functions for detecting whale calls in DAS strain data.

Author: Quentin Goestchel Date: 2023-2024

das4whales.detect.buildkernel(f0, f1, bdwdth, dur, f, t, samp, fmin, fmax, plotflag=False)

Calculate kernel and plot.

Parameters:

• f0 (float) – Starting frequency.

• f1 (float) – Ending frequency.

• bdwdth (float) – Frequency width of call.

• dur (float) – Call length (seconds).

• f (np.array) – Vector of frequencies returned from plotwav.

• t (np.array) – Vector of times returned from plotwav.

• samp (float) – Sample rate.

• plotflag (bool, optional) – If True, plots kernel. If False, no plot. Default is False.

• kernel_lims (tuple, optional) – Tuple of minimum kernel range and maximum kernel range. Default is finKernelLims.

Returns:

• tvec (numpy.array) – Vector of kernel times.

• fvec_sub (numpy.array) – Vector of kernel frequencies.

• BlueKernel (2-d numpy.array) – Matrix of kernel values.

• Key variables

• ————-

• tvec (numpy.array) – Kernel times (seconds).

• fvec (numpy.array) – Kernel frequencies.

• BlueKernel (numpy.array) – Matrix of kernel values.

das4whales.detect.buildkernel_from_template(fmin, fmax, dur, fs, nperseg, nhop, plotflag=False)

Build a kernel from a template.

Parameters:

• fmin (float) – The minimum frequency of interest.

• fmax (float) – The maximum frequency of interest.

• dur (float) – The duration of the kernel in seconds.

• fs (float) – The sampling rate of the kernel in Hz.

• nperseg (int) – The length of each segment for the spectrogram computation.

• nhop (int) – The number of samples to advance between segments.

• plotflag (bool, optional) – Whether to plot the kernel, defaults to False.

Returns:

The computed kernel.

Return type:

numpy.ndarray

das4whales.detect.calc_nmf(data, template)

Calculate the normalized matched filter between the input data and the template.

Parameters:

• data (ndarray) – The input data array.

• template (ndarray) – The template array.

Returns:

The normalized matched filter array (vector).

Return type:

ndarray

das4whales.detect.calc_nmf_correlogram(data, template)

Calculate the normalized matched filter correlogram between the input data and the template.

Parameters:

• data (ndarray) – The input data array.

• template (ndarray) – The template array.

Returns:

The normalized matched filter correlogram array.

Return type:

ndarray

das4whales.detect.compute_cross_correlogram(data, template)

Compute the cross correlogram between the given data and template.

Parameters:

• data (ndarray) – The input data array.

• template (ndarray) – The template array.

Returns:

The cross correlogram array.

Return type:

ndarray

das4whales.detect.compute_cross_correlogram_spectrocorr(data, fs, flims, kernel, win_size, overlap_pct)

Compute the cross-correlogram via spectrogram correlation.

This function computes the cross-correlogram spectrocorr between the input data and a kernel. The cross-correlogram spectrocorr is a measure of similarity between the spectrogram of the input data and the kernel.

Parameters:

• data (ndarray) – Input data array of shape (n, m), where n is the number of samples and m is the number of channels.

• fs (float) – Sampling frequency of the input data.

• flims (tuple) – Frequency limits (fmin, fmax) for the spectrogram computation.

• kernel (dict) – Dictionary containing the kernel parameters (f0, f1, duration, bandwidth).

• win_size (float) – Window size in seconds for the spectrogram computation.

• overlap_pct (float) – Percentage of overlap between consecutive windows for the spectrogram computation.

Returns:

cross_correlogram – Cross-correlogram spectrocorr array of shape (n, p), where n is the number of samples and p is the number of time bins.

Return type:

ndarray

das4whales.detect.convert_pick_times(peaks_indexes_m)

Convert pick times from a list of lists to a numpy array.

Parameters:

peaks_indexes_m (List[ndarray]) – A list of lists containing the pick times. The indexes of each list correspond to the space index. [[t1, t2, t3, …], [t1, t2, t3, …], …]

Returns:

A numpy array containing a tuple (time index, spatial index) of the converted pick times.

Return type:

Tuple[ndarray, ndarray]

das4whales.detect.gen_hyperbolic_chirp(fmin, fmax, duration, sampling_rate)

Generate a hyperbolic chirp signal.

Parameters:

• fmin (float) – The ending frequency of the chirp signal.

• fmax (float) – The starting frequency of the chirp signal.

• duration (float) – The duration of the chirp signal in seconds.

• sampling_rate (int) – The sampling rate of the chirp signal in Hz.

Returns:

The generated hyperbolic chirp signal.

Return type:

ndarray

das4whales.detect.gen_linear_chirp(fmin, fmax, duration, sampling_rate)

Generate a linear chirp signal.

Parameters:

• fmin (float) – The ending frequency of the chirp signal.

• fmax (float) – The starting frequency of the chirp signal.

• duration (float) – The duration of the chirp signal in seconds.

• sampling_rate (int) – The sampling rate of the chirp signal in Hz.

Returns:

The generated linear chirp signal.

Return type:

ndarray

das4whales.detect.gen_template_fincall(time, fs, fmin=15.0, fmax=25.0, duration=1.0, window=True)

generate template of a fin whale call

Parameters:

• time (ndarray) – time vector

• fs (float) – sampling rate in Hz

• fmin (float) – Minimum frequency, by default 15

• fmax (float) – Maximum frequency, by default 25

• duration (float) – Duration of the chirp signal in seconds, by default 1.

• window (bool)

Return type:

ndarray

das4whales.detect.get_sliced_nspectrogram(trace, fs, fmin, fmax, nperseg, nhop, plotflag=False)

Compute the sliced non-stationary spectrogram of a given trace.

Parameters:

• trace (numpy.ndarray) – The input trace signal.

• fs (float) – The sampling rate of the trace signal.

• fmin (float) – The minimum frequency of interest.

• fmax (float) – The maximum frequency of interest.

• nperseg (int) – The length of each segment for the spectrogram computation.

• nhop (int) – The number of samples to advance between segments.

• plotflag (bool, optional) – Whether to plot the spectrogram, defaults to False.

Returns:

• spectrogram (numpy.ndarray) – The computed spectrogram.

• ff (ndarray) – The frequency values of the spectrogram.

• tt (ndarray) – The time values of the spectrogram.

Notes

This function computes the non-stationary spectrogram of a given trace signal. The spectrogram is computed using the Short-Time Fourier Transform (STFT) with a specified segment length and hop size. The resulting spectrogram is then sliced between the specified minimum and maximum frequencies of interest.

Examples

>>> trace = np.random.randn(1000)
>>> fs = 1000
>>> fmin = 10
>>> fmax = 100
>>> nperseg = 256
>>> nhop = 128
>>> spectrogram, ff, tt = get_sliced_nspectrogram(trace, fs, fmin, fmax, nperseg, nhop, plotflag=True)

das4whales.detect.nxcorr2d(spectro, kernel)

Calculate the normalized cross-correlation between a spectrogram and a kernel.

Parameters:

• spectro (numpy.ndarray) – The spectrogram array.

• kernel (numpy.ndarray) – The kernel array.

Returns:

The maximum correlation values along the time axis.

Return type:

numpy.ndarray

Notes

The normalized cross-correlation is calculated using scipy.signal.correlate2d. The correlation values are normalized by dividing by the standard deviation of the spectrogram and the kernel, multiplied by the number of columns in the spectrogram.

Examples

>>> spectro = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> kernel = np.array([[1, 0], [0, 1]])
>>> nxcorr2d(spectro, kernel)
array([0.        , 0.33333333, 0.66666667])

das4whales.detect.pick_times(corr_m, threshold, ipi_idx)

Detects the peak times in a correlation matrix.

This function takes a correlation matrix, computes the Hilbert transform of each correlation, and detects the peak times based on a given threshold.

Parameters:

• corr_m (ndarray) – The correlation matrix.

• threshold (float) – The threshold value for peak detection. Defaults to 0.3.

• ipi_idx (int) – The minimum inter-pulse interval in indexes.

Returns:

A list of arrays, where each array contains the peak indexes for each correlation.

Return type:

List[ndarray]

das4whales.detect.pick_times_env(corr_m, threshold)

Detects the peak times in a correlation matrix. Parallelized version : pick_times_par

This function takes a correlation matrix, computes the Hilbert transform of each correlation, and detects the peak times based on a given threshold.

Parameters:

• corr_m (ndarray) – The correlation matrix.

• threshold (float) – The threshold value for peak detection. Defaults to 0.3.

Returns:

A list of arrays, where each array contains the peak indexes for each correlation.

Return type:

List[ndarray]

das4whales.detect.pick_times_par(corr_m, threshold)

Detects the peak times in a correlation matrix using parallel processing.

This function takes a correlation matrix, computes the Hilbert transform of each correlation, and detects the peak times based on a given threshold using parallel processing.

Parameters:

• corr_m (ndarray) – The correlation matrix.

• threshold (float) – The threshold value for peak detection. Defaults to 0.3.

Returns:

A list of arrays, where each array contains the peak indexes for each correlation.

Return type:

List[ndarray]

das4whales.detect.process_corr(corr, threshold)

Detects the peak times in a correlation serie, kernel for parallelization.

This function takes a correlation serie, computes the Hilbert transform of the correlation, and detects the peak times based on a given threshold.

Parameters:

• corr (ndarray) – The correlogram array.

• threshold (float) – The threshold value for peak detection. Defaults to 0.3.

Returns:

The peak indexes for the given correlation.

Return type:

ndarray

das4whales.detect.resolve_hf_lf_crosstalk(input_peaks, comp_peaks, input_SNR, comp_SNR, dt_tol, dx_tol)

Sort peaks that are at the same distance and time but keep the one with higher SNR to differentiate between HF and LF peaks.

Parameters:

• input_peaks (ndarray) – Array of shape (2, n_peaks) containing [distance_indices, time_indices] of the input peaks.

• comp_peaks (ndarray) – Array of shape (2, n_peaks) containing [distance_indices, time_indices] of the comparison peaks.

• input_SNR (ndarray) – Array of shape (n_peaks_input) containing the SNR values for the input peaks

• comp_SNR (ndarray) – Array of shape (n_peaks_comp) containing the SNR values for the comparison peaks

• dt_tol (int) – Tolerance in time index to consider peaks as matching.

• dx_tol (int) – Tolerance in distance index to consider peaks as matching.

das4whales.detect.select_picked_times(idx_tp, tstart, tend, fs)

Select the picked times within a given time range.

Parameters:

• idx_tp (numpy.ndarray) – The time and spatial indexes of the picked times.

• tstart (float) – The starting time of the time range [s].

• tend (float) – The ending time of the time range [s].

• fs (float) – The sampling rate of the data.

Returns:

The selected picked times within the given time range (time index, spatial index).

Return type:

numpy.ndarray

das4whales.detect.shift_nxcorr(x, y)

Compute the shifted (positive lags only) normalized cross-correlation with standard deviation normalization.

Parameters:

• x (ndarray) – first input signal.

• y (ndarray) – second input signal

Returns:

The normalized cross-correlation between the two signals

Return type:

ndarray

das4whales.detect.shift_xcorr(x, y)

compute the shifted (positive lags only) cross correlation between two 1D arrays

Parameters:

• x (ndarray) – 1D array containing signal

• y (ndarray) – 1D array containing signal

Returns:

1D array cross-correlation betweem x and y, only for positive lags

Return type:

ndarray

das4whales.detect.xcorr(t, f, Sxx, tvec, fvec, BlueKernel)

Cross-correlate kernel with spectrogram

Parameters:

• t (np.array) – Vector of times returned from plotwav

• f (np.array) – Vector of frequencies returned from plotwav

• Sxx (np.array) – 2-D array of spectrogram amplitudes

• tvec (np.array) – Vector of times of kernel

• fvec (np.array) – Vector of frequencies of kernel

• BlueKernel (np.array) – 2-D array of kernel amplitudes

Returns:

• t_scale (numpy.array) – Vector of correlation lags

• CorrVal (numpy.array) – Vector of correlation values

das4whales.detect.xcorr2d(spectro, kernel)

Calculate the 2D cross-correlation between a spectrogram and a kernel.

Parameters:

• spectro (numpy.ndarray) – The input spectrogram array [frequency x time].

• kernel (numpy.ndarray) – The kernel array used for cross-correlation [frequency x time].

Returns:

The resulting cross-correlation array.

Return type:

numpy.ndarray

das4whales.dsp module

dsp.py - Digital Signal Processing module for DAS4Whales

This module provides various functions for digital signal processing of DAS strain data.

Authors: Léa Bouffaut, Quentin Goestchel Date: 2023-2024-2025

das4whales.dsp.bp_filt(data, fs, fmin, fmax)

bp_filt - perform bandpass filtering on an array of DAS data

Parameters:

• data (array-like) – array containing wave signal from DAS data

• fs (float) – sampling frequency

• fmin (float) – minimum frequency for the passband

• fmax (float) – maximum frequency for the passband

Returns:

tr_filt – bandpass filtered data

Return type:

array-like

das4whales.dsp.butterworth_filter(filterspec, fs)

Designs and applies a Butterworth filter.

Parameters:

filterspectuple

A tuple containing the filter order, critical frequency, and filter type.

fsfloat

The sampling frequency.

Returns:

: filter_sos : np.ndarray

The second-order sections (SOS) representation of the Butterworth filter.

das4whales.dsp.calc_snr_median(trace)

Calculate the Signal-to-Noise Ratio (SNR) for a given input trace.

This function computes the SNR for the input trace. The SNR is calculated as the ratio of the square of the envelope of the trace to the square of the median of the trace.

Parameters:

trace (np.ndarray) – The input trace for which the SNR is to be calculated.

Returns:

The Signal-to-Noise Ratio (SNR) value for the input trace.

Return type:

np.ndarray

das4whales.dsp.fk_filt(data, tint, fs, xint, dx, c_min, c_max, display_filter=False)

fk_filt - perform fk filtering on an array of DAS data

Parameters:

• data (array-like) – array containing wave signal from DAS data

• tint (float) – decimation time interval between considered samples

• fs (float) – sampling frequency

• xint (float) – decimation space interval between considered samples

• dx (float) – spatial resolution

• c_min (float) – minimum phase speed for the pass-band filter in f-k domain

• c_max (float) – maximum phase speed for the pass-band filter in f-k domain

Returns:

• f (array-like) – vector of frequencies

• k (array-like) – vector of wavenumbers

• g (array-like) – 2D designed gaussian filter

• data_fft_g (array-like) – 2D Fourier transformed data, filtered by g

• data_g.real (array-like) – Real value of spatiotemporal filtered data

das4whales.dsp.fk_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400, cp_min=1450, cp_max=3400, cs_max=3500, display_filter=False)

Designs a f-k filter for DAS strain data Keeps by default data with propagation speed [1450-3400] m/s

The transition band is inspired and adapted from Yi Lin’s matlab fk function https://github.com/nicklinyi/seismic_utils/blob/master/fkfilter.m

Parameters:

• trace_shape (tuple) – A tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample].

• selected_channels (list) – A list of the selected channels number [start, end, step].

• dx (float) – Channel spacing (m).

• fs (float) – Sampling frequency (Hz).

• cs_min (float, optional) – Minimum selected sound speeds for the f-k passband filtering (m/s). Default is 1400 m/s.

• cp_min (float, optional) – Minimum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 1450 m/s.

• cp_max (float, optional) – Maximum selected sound speeds for the f-k passband filtering (m/s). Default is 3400 m/s.

• cs_max (float, optional) – Maximum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 3500 m/s.

Returns:

fk_filter_matrix – A [channel x time sample] numpy array containing the f-k-filter.

Return type:

ndarray

das4whales.dsp.fk_filter_design_old(trace_shape, selected_channels, dx, fs, cs_min=1400, cp_min=1450, cp_max=3400, cs_max=3500, display_filter=False)

Designs a f-k filter for DAS strain data Keeps by default data with propagation speed [1450-3400] m/s

The transition band is inspired and adapted from Yi Lin’s matlab fk function https://github.com/nicklinyi/seismic_utils/blob/master/fkfilter.m

Parameters:

• trace_shape (tuple) – A tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample].

• selected_channels (list) – A list of the selected channels number [start, end, step].

• dx (float) – Channel spacing (m).

• fs (float) – Sampling frequency (Hz).

• cs_min (float, optional) – Minimum selected sound speeds for the f-k passband filtering (m/s). Default is 1400 m/s.

• cp_min (float, optional) – Minimum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 1450 m/s.

• cp_max (float, optional) – Maximum selected sound speeds for the f-k passband filtering (m/s). Default is 3400 m/s.

• cs_max (float, optional) – Maximum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 3500 m/s.

Returns:

fk_filter_matrix – A [channel x time sample] numpy array containing the f-k-filter.

Return type:

ndarray

Deprecated since version 0.1.0: This will be removed in 0.2.0. Use hybrid_filter_design instead

das4whales.dsp.fk_filter_filt(trace, fk_filter_matrix, tapering=False)

Applies a pre-calculated f-k filter to DAS strain data.

Parameters:

• trace (np.ndarray) – A [channel x time sample] nparray containing the strain data in the spatio-temporal domain.

• fk_filter_matrix (np.ndarray) – A [channel x time sample] nparray containing the f-k-filter.

• tapering (bool, optional) – Flag indicating whether to apply tapering to the data. Default is False.

Returns:

A [channel x time sample] nparray containing the f-k-filtered strain data in the spatio-temporal domain.

Return type:

np.ndarray

das4whales.dsp.fk_filter_sparsefilt(trace, fk_filter_matrix, tapering=False)

Applies a pre-calculated f-k filter to DAS strain data

Parameters:

• trace (np.ndarray) – A [channel x time sample] nparray containing the strain data in the spatio-temporal domain.

• fk_filter_matrix (np.ndarray) – A [channel x time sample] nparray containing the f-k-filter.

Returns:

A [channel x time sample] nparray containing the f-k-filtered strain data in the spatio-temporal domain.

Return type:

np.ndarray

das4whales.dsp.get_fx(trace, nfft)

Apply a fast Fourier transform (FFT) to each channel of the strain data matrix.

Parameters:

• trace (ndarray) – A 2D array of shape (channel, time sample) containing the strain data in the spatio-temporal domain.

• nfft (int) – Number of time samples used for the FFT.

Returns:

A 2D array of shape (channel, freq. sample) containing the strain data in the spatio-spectral domain.

Return type:

ndarray

das4whales.dsp.get_spectrogram(waveform, fs, nfft=128, overlap_pct=0.8)

Get the spectrogram of a single channel

Parameters:

• waveform (ndarray) – Single channel temporal signal.

• fs (float) – The sampling frequency (Hz).

• nfft (int) – Number of time samples used for the STFT. Default is 128.

• overlap_pct (float) – Percentage of overlap in the spectrogram. Default is 0.8.

Return type:

Tuple[ndarray, ndarray, ndarray]

Returns:

• p (np.ndarray) – Spectrogram in dB scale (normalized by max).

• tt (np.ndarray) – Time vector.

• ff (ndarray) – Frequency vector.

das4whales.dsp.hybrid_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400.0, cp_min=1450.0, fmin=15.0, fmax=25.0, display_filter=False)

Designs an infinite wave speed bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• cs_min (float, optional) – lower minimum selected sound speeds for the f-k highpass filtering (m/s), by default 1400 m/s

• cp_min (float, optional) – higher minimum selected sound speed for the f-k highpass filtering, by default 1450 m/s

• fmin (float, optional) – minimum frequency for the passband, by default 15

• fmax (float, optional) – maximum frequency for the passband, by default 25

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.hybrid_gs_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400.0, cp_min=1450.0, fmin=15.0, fmax=25.0, display_filter=False)

Designs a bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• cs_min (float, optional) – lower minimum selected sound speeds for the f-k highpass filtering (m/s), by default 1400 m/s

• cp_min (float, optional) – higher minimum selected sound speed for the f-k highpass filtering, by default 1450 m/s

• fmin (float, optional) – minimum frequency for the passband, by default 15

• fmax (float, optional) – maximum frequency for the passband, by default 25

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.hybrid_ninf_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400.0, cp_min=1450.0, cp_max=3400, cs_max=3500, fmin=15.0, fmax=25.0, display_filter=False)

Designs a bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• cs_min (float, optional) – lower minimum selected sound speeds for the f-k highpass filtering (m/s), by default 1400 m/s

• cp_min (float, optional) – higher minimum selected sound speed for the f-k highpass filtering, by default 1450 m/s

• fmin (float, optional) – minimum frequency for the passband, by default 15

• fmax (float, optional) – maximum frequency for the passband, by default 25

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.hybrid_ninf_gs_filter_design(trace_shape, selected_channels, dx, fs, fk_params, display_filter=False)

Designs a bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• fk_params (dict) – dictionary containing the parameters for the f-k filter design

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.instant_freq(channel, fs)

Compute the instantaneous frequency

Parameters:

• channel (np.ndarray) – 1D time series channel trace

• fs (float) – sampling frequency

Returns:

instantaneous frequency along time[1:]

Return type:

np.ndarray

das4whales.dsp.moving_average(signal, window_size)

das4whales.dsp.moving_average_matrix(matrix, window_size)

das4whales.dsp.normalize_median(trace)

Normalize the input trace by its median.

Parameters:

trace (np.ndarray) – A 2D array of shape (channel, time sample) containing the strain data in the spatio-temporal domain.

Returns:

A 2D array of shape (channel, time sample) containing the normalized strain data.

Return type:

np.ndarray

das4whales.dsp.normalize_std(trace)

Normalize the input trace by its standard deviation.

Parameters:

trace (np.ndarray) – A 2D array of shape (channel, time sample) containing the strain data in the spatio-temporal domain.

Returns:

A 2D array of shape (channel, time sample) containing the normalized strain data.

Return type:

np.ndarray

das4whales.dsp.resample(tr, fs, desired_fs)

Resample a multi-channel signal to a desired sampling frequency.

Parameters:

• tr (ndarray) – Input signal with shape (n_channels, n_samples), where n_channels is the number of channels and n_samples is the number of time samples.

• fs (int) – Original sampling frequency of the input signal (in Hz).

• desired_fs (int) – Desired sampling frequency after resampling (in Hz).

Returns:

A tuple containing: - tr_downsampled (ndarray): Downsampled signal with shape (n_channels, n_samples_downsampled). - fs_downsampled (int): Sampling frequency after downsampling (equals desired_fs). - tx_downsampled (ndarray): New time vector corresponding to the downsampled signal,

with shape (n_samples_downsampled,).

Return type:

Tuple[ndarray, int, ndarray]

das4whales.dsp.snr_tr_array(trace)

Calculate the 2D Signal-to-Noise Ratio (SNR) array for a given input trace.

This function computes the SNR for each element in the input 2D trace array. The SNR is calculated as the ratio of the square of the trace values to the square of the standard deviation of the trace along the second axis (time).

Parameters:

trace (numpy.ndarray) – The input 2D trace array for which the SNR is to be calculated.

Returns:

A 2D array containing the Signal-to-Noise Ratio (SNR) values for each element in the input trace.

Return type:

numpy.ndarray

das4whales.dsp.taper_data(trace)

Apply a Tukey window to each line (time series) of the input matrix.

Parameters:

trace (np.ndarray) – 2D numpy array, where each column represents a time series.

Returns:

Tapered matrix with the same shape as the input.

Return type:

np.ndarray

das4whales.dsp.taper_data2d(data, taper_type='tukey')

Applies tapering (windowing) to the data in both space (channels) and time (samples) domains.

Parameters:

• data (ndarray) – 2D numpy array representing the spatio-temporal data with dimensions [channels x samples].

• taper_type (str, optional) – Type of tapering window to apply. Options are ‘hanning’, ‘hamming’, or ‘tukey’. Default is ‘tukey’.

Returns:

tapered_data – The tapered data array with the same shape as input data.

Return type:

ndarray

das4whales.improcess module

improcess.py - image processing functions for DAS data

This module contains functions for image processing of DAS data.

Authors: Quentin Goestchel Date: 2023-2024

das4whales.improcess.angle_fromspeed(c0, fs, dx, selected_channels)

Calculate the angle from the speed of sound.

This function calculates the angle from the speed of sound.

Parameters:

• c0 (float) – The speed of sound.

• fs (float) – The sampling frequency.

• dx (float) – The spatial resolution.

• selected_channels (list) – list of the selected channels number [start, end, step].

Returns:

The angle from the speed of sound.

Return type:

float

das4whales.improcess.apply_median_filter_chunk(array_chunk, size)

das4whales.improcess.apply_smooth_mask(array, mask, sigma=1.5)

Apply a smooth mask to an array.

This function applies a smooth mask to an array.

Parameters:

• array (numpy.ndarray) – The input array.

• mask (numpy.ndarray) – The mask to apply.

• sigma (float, optional (default=1.5)) – The standard deviation of the Gaussian filter applied to the mask.

Returns:

The masked array.

Return type:

numpy.ndarray

das4whales.improcess.bilateral_filter(img, diameter, sigma_color, sigma_space)

Apply bilateral filter to an image.

This function applies bilateral filter to an image.

Parameters:

• img (numpy.ndarray) – The input image.

• diameter (int) – Diameter of each pixel neighborhood that is used during filtering.

• sigma_color (float) – Filter sigma in the color space.

• sigma_space (float) – Filter sigma in the coordinate space.

Returns:

The filtered image.

Return type:

numpy.ndarray

das4whales.improcess.binning(image, ft, fx)

Apply binning to an image.

This function applies binning to an image.

Parameters:

• image (numpy.ndarray) – The input image.

• ft (float) – The binning factor along the time axis.

• fx (float) – The binning factor along the spatial axis.

Returns:

The binned image.

Return type:

numpy.ndarray

das4whales.improcess.compute_radon_transform(image, theta=None)

Compute the Radon transform of an image.

This function computes the Radon transform of an image.

Parameters:

• image (numpy.ndarray) – The input image.

• theta (numpy.ndarray, optional (default=None)) – The projection angles (in degrees).

Returns:

The Radon transform of the image.

Return type:

numpy.ndarray

das4whales.improcess.detect_diagonal_edges(matrix, threshold)

das4whales.improcess.detect_long_lines(img)

das4whales.improcess.diagonal_edge_detection(img, threshold)

Detect diagonal edges in an image. Inspired from https://github.com/Ocean-Data-Lab/das-finwhale-vocalization/

This function detects diagonal edges in an image.

Parameters:

• img (numpy.ndarray) – The input image.

• threshold (float) – The threshold value.

Returns:

The diagonal edges in the image.

Return type:

numpy.ndarray

das4whales.improcess.gabor_filt_design(theta_c0, plot=False)

Design Gabor filters for lines that are oriented along sound speed.

This function designs Gabor filters for lines that are oriented along sound speed.

Parameters:

theta_c0 (float) – The angle from the speed of sound.

Returns:

The Gabor filters.

Return type:

numpy.ndarray

das4whales.improcess.gaussian_filter(img, size, sigma)

Apply Gaussian filter to an image.

This function applies Gaussian filter to an image.

Parameters:

• img (numpy.ndarray) – The input image.

• size (int) – The size of the filter.

• sigma (float) – The standard deviation of the filter.

Returns:

The filtered image.

Return type:

numpy.ndarray

das4whales.improcess.gradient_oriented(image, direction)

Calculate the gradient oriented value of an image.

This function calculates the gradient oriented value of an image based on the given direction.

Parameters:

• image (numpy.ndarray) – The input image.

• direction (tuple) – A tuple containing the direction values (dft, dfx).

Returns:

The gradient oriented value of the image.

Return type:

numpy.ndarray

das4whales.improcess.par_medfilt(array, size, n_jobs=-1)

Apply median filter to an array in parallel.

This function applies median filter to an array in parallel.

Parameters:

• array (numpy.ndarray) – The input array.

• size (int) – The size of the filter.

• n_jobs (int, optional (default=-1)) – The number of jobs to run in parallel.

Returns:

The filtered array.

Return type:

numpy.ndarray

das4whales.improcess.scale_pixels(img, scale_factor=1)

Scale the pixel values of an image.

This function scales the pixel values of an image to the range [0, 1].

Parameters:

• img (numpy.ndarray) – The input image.

• scale_factor (float, optional (default=1)) – The scaling factor.

Returns:

The scaled image.

Return type:

numpy.ndarray

das4whales.improcess.trace2image(trace)

Convert a DAS trace to an image.

This function converts a DAS trace matrix to an image.

Parameters:

trace (numpy.ndarray) – The input trace.

Returns:

The image.

Return type:

numpy.ndarray

das4whales.loc module

loc.py - Localisation module for the das4whales package.

This module provides functions for localizing the source of a sound source recorded by a DAS array.

Author: Quentin Goestchel, Léa Bouffaut Date: 2024-06-18/2025-03-05

class das4whales.loc.LocalizationResult(position: np.ndarray, residuals: np.ndarray, rms: float, weighted_rms: float, covariance: np.ndarray, uncertainties: np.ndarray, weights: np.ndarray, n_iterations: int)

Bases: NamedTuple

Container for localization results with uncertainty information.

Parameters:

• position (ndarray)

• residuals (ndarray)

• rms (float)

• weighted_rms (float)

• covariance (ndarray)

• uncertainties (ndarray)

• weights (ndarray)

• n_iterations (int)

Methods

count(value, /)	Return number of occurrences of value.
index(value[, start, stop])	Return first index of value.

covariance: ndarray

Alias for field number 4

n_iterations: int

Alias for field number 7

position: ndarray

Alias for field number 0

residuals: ndarray

Alias for field number 1

rms: float

Alias for field number 2

uncertainties: ndarray

Alias for field number 5

weighted_rms: float

Alias for field number 3

weights: ndarray

Alias for field number 6

das4whales.loc.cal_variance_residuals(arrtimes, predic_arrtimes, fix_z=False)

Compute the variance of the residuals of the arrival times

Parameters:

• arrtimes (np.ndarray) – array of measured arrival times

• predic_arrtimes (np.ndarray) – array of predicted arrival times

• fix_z (bool, optional) – True if the z coordinate is fixed, by default False

Returns:

var – Variance of the residuals

Return type:

float

das4whales.loc.cal_weighted_variance_residuals(arrtimes, predic_arrtimes, weights, fix_z=False)

Compute the weighted variance of the residuals of the arrival times

Parameters:

• arrtimes (np.ndarray) – array of measured arrival times

• predic_arrtimes (np.ndarray) – array of predicted arrival times

• weights (np.ndarray) – weights for each residual

• fix_z (bool, optional) – True if the z coordinate is fixed, by default False

Returns:

var – Weighted variance of the residuals

Return type:

float

das4whales.loc.calc_arrival_times(t0, cable_pos, pos, c0)

Calculate theoretical arrival times of a whale call at a grid of positions or a single point.

Parameters:

• t0 (Union[float, ndarray]) – Initial time offset. Can be a scalar or an array of time offsets.

• cable_pos (ndarray) – Array of cable positions with shape (N, 3), where N is the number of channels. Each row represents [x, y, z] coordinates of a cable position.

• pos (Union[Tuple[ndarray, ndarray, float], Tuple[float, float, float]]) – If a grid is used, provide a tuple (xg, yg, zg) with xg and yg as 2D arrays. For a single point, provide (x, y, z) as floats or 1D arrays.

• c0 (float) – Speed of sound in water (in meters per second).

Returns:

th_arrtimes – Theoretical arrival times at each grid point or point source. Shape is (M, L, N) for a grid, or (N,) for a single point.

Return type:

ndarray

das4whales.loc.calc_covariance_matrix(cable_pos, whale_pos, c0, var, fix_z=False, weights=None)

Compute the covariance matrix of the estimated whale position

Parameters:

• cable_pos (np.ndarray) – Array of cable positions [channel x 3]

• whale_pos (np.ndarray) – Estimated whale position [x, y, z, t0]

• c0 (float) – Speed of sound in water considered constant

• var (float) – Variance of the residuals (should be weighted variance if weights provided)

• fix_z (bool, optional) – Whether to fix the z coordinate (default: False)

• weights (np.ndarray, optional) – Weight vector for weighted least-squares (default: None for unweighted)

Returns:

cov – Covariance matrix of the estimated whale position

Return type:

np.ndarray

das4whales.loc.calc_dist_weighting(dist, discut, disw1, disw2)

das4whales.loc.calc_distance_matrix(cable_pos, whale_pos)

Compute the distance matrix between the cable and the whale

das4whales.loc.calc_error_ellipse_params(covariance_matrix, confidence_level=0.95)

Calculate error ellipse parameters from covariance matrix.

Parameters:

• covariance_matrix (np.ndarray) – Covariance matrix (at least 2x2 for x,y components)

• confidence_level (float, optional) – Confidence level (default 0.95 for 95% confidence)

Returns:

Dictionary containing ellipse parameters: - semi_major_axis: length of semi-major axis - semi_minor_axis: length of semi-minor axis - rotation_angle: rotation angle in radians - area: ellipse area

Return type:

dict

das4whales.loc.calc_phi_vector(cable_pos, whale_pos)

Compute the azimuthal angle between the cable and the whale for each cable position

das4whales.loc.calc_radii_matrix(cable_pos, whale_pos)

Compute the radii matrix between the cable and the whale

das4whales.loc.calc_res_weighting(res, rmscut, rmsw1, rmsw2)

das4whales.loc.calc_rms(residuals, window_mask=None)

Calculate the root mean square of the residuals.

Parameters:

• residuals (np.ndarray or None) – Array of residuals. If None or empty, returns np.inf.

• window_mask (np.ndarray, optional) – Boolean mask to apply to the residuals, by default None. If provided, only the residuals where the mask is True will be considered.

Returns:

Root mean square of the residuals, or np.inf if residuals are invalid or empty.

Return type:

float

das4whales.loc.calc_theory_toa(das_position, whale_position, dist, c0=1490)

Calculate theoretical Time of Arrival (TOA) for a whale call with known position relative to the cable.

Parameters:

• das_position (dict) – A dictionary containing latitude, longitude, and depth information of the cable (DAS) positions.

• whale_position (dict) – A dictionary containing at least whale apex, offset, side and depth

• dist (numpy.ndarray) – An array containing distances along the cable.

• c0 (float, optional) – The speed of sound in water in meters per second. Defaults to 1490 m/s.

Returns:

An array containing the theoretical TOAs for each position along the cable.

Return type:

numpy.ndarray

das4whales.loc.calc_theta_vector(cable_pos, whale_pos)

Compute the elevation angle between the cable and the whale for each cable position

das4whales.loc.calc_weighted_rms(residuals, weights)

Calculate the weighted root mean square of the residuals.

Parameters:

• residuals (np.ndarray) – Array of residuals.

• weights (np.ndarray) – Array of weights corresponding to each residual.

Returns:

Weighted root mean square of the residuals.

Return type:

float

das4whales.loc.loc_from_picks(associated_list, cable_pos, c0, fs, return_uncertainty=True)

Localize whale calls from associated picks with uncertainty quantification.

Parameters:

• associated_list (list) – List of associated picks

• cable_pos (np.ndarray) – Cable positions

• c0 (float) – Sound speed

• fs (float) – Sampling frequency

• return_uncertainty (bool, optional) – Whether to return uncertainty information (default=True)

Returns:

List of LocalizationResult objects if return_uncertainty=True, or list of position arrays if return_uncertainty=False

Return type:

list

das4whales.loc.loc_picks_bicable(n_assoc, s_assoc, cable_pos, c0, fs, Nbiter=20, return_uncertainty=True)

Solve the least squares localization problem for bicable data using the picks’ indices.

Parameters:

• n_assoc (array-like) – The north cable association data [indices, times]

• s_assoc (array-like) – The south cable association data [indices, times]

• cable_pos (tuple) – A tuple containing the positions of the north and south cables.

• c0 (float) – The speed of sound for localization.

• fs (float) – The sampling frequency.

• Nbiter (int, optional) – The number of iterations for the least squares solution, default is 20.

• return_uncertainty (bool, optional) – Whether to return uncertainty information (default=True)

Returns:

If return_uncertainty=True: LocalizationResult object If return_uncertainty=False: tuple (position, residuals) for backward compatibility

Return type:

LocalizationResult or tuple

das4whales.loc.loc_picks_bicable_list(n_assoc_list, s_assoc_list, cable_pos, c0, fs, Nbiter=20, return_uncertainty=True)

Localize multiple bicable associations with uncertainty quantification.

Parameters:

• n_assoc_list (list) – List of north cable associations

• s_assoc_list (list) – List of south cable associations

• cable_pos (tuple) – Cable positions for north and south

• c0 (float) – Sound speed

• fs (float) – Sampling frequency

• Nbiter (int, optional) – Number of iterations (default=20)

• return_uncertainty (bool, optional) – Whether to return uncertainty information (default=True)

Returns:

List of LocalizationResult objects if return_uncertainty=True, or list of position arrays if return_uncertainty=False

Return type:

list

das4whales.loc.localization_results_to_dict(results, utc_start=None, sensor='unknown', call_type='unknown')

Convert LocalizationResult objects to dictionary format for CSV export.

Parameters:

• results (list of LocalizationResult) – List of localization results

• utc_start (datetime, optional) – Start time for converting relative times to absolute UTC

• sensor (str, optional) – Sensor identifier (default=’unknown’)

• call_type (str, optional) – Call type identifier (default=’unknown’)

Returns:

List of dictionaries ready for DataFrame conversion

Return type:

list of dict

das4whales.loc.solve_lq(Ti, cable_pos, c0, Nbiter=10, SNR=None, fix_z=False, ninit=None, residuals=False, verbose=False)

Solve the least squares problem to localize the whale with optional SNR weighting

Parameters:

• Ti (np.ndarray) – Array of arrival times at each cable position [channel x 1]

• cable_pos (np.ndarray) – Array of cable positions [channel x 3]

• c0 (float) – Speed of sound in water considered constant

• SNR (np.ndarray, optional) – Array of signal-to-noise ratios in dB for each measurement [channel x 1]

• Nbiter (int, optional (default=10)) – Number of iterations for the least squares algorithm

• fix_z (bool, optional (default=False)) – Whether to fix the z-coordinate

• ninit (np.ndarray, optional) – Initial guess for n

• residuals (bool, optional (default=False)) – Whether to return residuals

• verbose (bool, optional (default=False)) – Whether to print iteration details

Returns:

• n (np.ndarray) – Estimated whale position and time of emission vector [x, y, z, t0]

• res (np.ndarray, optional) – Residuals if residuals=True

das4whales.loc.solve_lq_weight(Ti, cable_pos, c0, Nbiter=10, fix_z=False, ninit=None, return_uncertainty=True, residuals=False, verbose=False)

Solve the least squares problem to localize the whale with distance weighting

Parameters:

• Ti (np.ndarray) – Array of arrival times at each cable position [channel x 1]

• cable_pos (np.ndarray) – Array of cable positions [channel x 3]

• c0 (float) – Speed of sound in water considered constant

• Nbiter (int, optional (default=10)) – Number of iterations for the least squares algorithm

• fix_z (bool, optional (default=False)) – Whether to fix the z-coordinate

• ninit (np.ndarray, optional) – Initial guess for n

• return_uncertainty (bool, optional (default=True)) – Whether to compute and return uncertainty information

• residuals (bool, optional (default=False)) – Whether to return residuals (deprecated, use return_uncertainty)

• verbose (bool, optional (default=False)) – Whether to print iteration details

Returns:

• result (LocalizationResult or np.ndarray) – If return_uncertainty=True: LocalizationResult with comprehensive information If return_uncertainty=False: just the position array [x, y, z, t0]

• res (np.ndarray, optional) – Residuals if residuals=True (for backward compatibility)

das4whales.map module

map.py - Map creation module for the das4whales package.

This module provides functions for coordinates handling and map visualization for DAS data.

Author: Quentin Goestchel Date: 2024-06-26

das4whales.map.flatten_bathy(bathy, threshold)

Flatten the bathymetry above a certain threshold.

Parameters:

• bathy (np.ndarray) – The bathymetry data array. zij = bathy[i,j] is the depth at the point (xlon[j], ylat[i]).

• threshold (float) – The threshold above which the bathymetry is flattened.

Returns:

bathy_flat – The flattened bathymetry data array.

Return type:

np.ndarray

das4whales.map.latlon_to_utm(lon, lat, zone=10)

Convert latitude and longitude to UTM coordinates for a specified zone

Parameters:

• lon (float) – The longitude.

• lat (float) – The latitude.

• zone (int, optional) – The UTM zone (default is 10).

Returns:

• utm_x (float) – The UTM x coordinate.

• utm_y (float) – The UTM y coordinate.

das4whales.map.load_bathymetry(filepath)

Load the bathymetry data from a text file.

Parameters:

filepath (str) – The file path to the bathymetry data file. ‘.grd’ file format is used here and can be found at https://www.gmrt.org/GMRTMapTool/.

Returns:

• bathy (np.ndarray) – The bathymetry data array. zij = bathy[i,j] is the depth at the point (xlon[j], ylat[i]).

• xlon (np.ndarray) – The longitude data vector.

• ylat (np.ndarray) – The latitude data vector.

das4whales.map.load_cable_coordinates(filepath, dx)

Load the cable coordinates from a text file.

Parameters:

• filepath (str) – The file path to the cable coordinates file.

• dx (float) – The distance between two channels.

Returns:

df – The cable coordinates dataframe.

Return type:

pandas.DataFrame

das4whales.map.plot_cables2D(df_north, df_south, bathy, xlon, ylat)

Plot the cables on the bathymetry map.

Parameters:

• df_north (pandas.DataFrame) – The dataframe containing the north cable coordinates.

• df_south (pandas.DataFrame) – The dataframe containing the south cable coordinates.

• bathy (np.ndarray) – The bathymetry data array. zij = bathy[i,j] is the depth at the point (xlon[j], ylat[i]).

• xlon (np.ndarray) – The longitude data vector.

• ylat (np.ndarray) – The latitude data vector.

das4whales.map.plot_cables2D_m(df_north, df_south, bathy, xm, ym)

Plot the cables on the bathymetry map.

Parameters:

• df_north (pandas.DataFrame) – The dataframe containing the north cable coordinates.

• df_south (pandas.DataFrame) – The dataframe containing the south cable coordinates.

• bathy (np.ndarray) – The bathymetry data array. zij = bathy[i,j] is the depth at the point (xlon[j], ylat[i]).

• xm (np.ndarray) – The x data vector in meters.

• ym (np.ndarray) – The y data vector in meters.

das4whales.map.plot_cables3D(df_north, df_south, bathy, xlon, ylat)

Plot the cables on the bathymetry map in 3D.

Parameters:

• df_north (pandas.DataFrame) – The dataframe containing the north cable coordinates.

• df_south (pandas.DataFrame) – The dataframe containing the south cable coordinates.

• bathy (np.ndarray) – The bathymetry data array. zij = bathy[i,j] is the depth at the point (xlon[j], ylat[i]).

• xlon (np.ndarray) – The longitude data vector.

• ylat (np.ndarray) – The latitude data vector.

das4whales.map.plot_cables3D_m(df_north, df_south, bathy, x, y)

Plot the cables on the bathymetry map in 3D.

Parameters:

• df_north (pandas.DataFrame) – The dataframe containing the north cable coordinates.

• df_south (pandas.DataFrame) – The dataframe containing the south cable coordinates in meters.

• bathy (np.ndarray) – The bathymetry data array. zij = bathy[i,j] is the depth at the point (xlon[j], ylat[i]).

• x (np.ndarray) – The x data vector.

• y (np.ndarray) – The y data vector.

das4whales.map.utm_to_latlon(utm_x, utm_y, zone=10)

Convert UTM coordinates to latitude and longitude for a specified zone.

Parameters:

• utm_x (float) – The UTM x coordinate.

• utm_y (float) – The UTM y coordinate.

• zone (int, optional) – The UTM zone (default is 10).

Returns:

• lon (float) – The longitude.

• lat (float) – The latitude.

das4whales.plot module

plot.py - Plotting module for DAS4Whales

This module provides functions for plotting das data and data products in various formats.

Authors: Léa Bouffaut, Quentin Goestchel Date: 2023-2024

das4whales.plot.design_mf(trace, hnote, lnote, th, tl, time, fs)

Plot to design the matched filter

Parameters:

• trace (numpy.ndarray) – 1D time series channel trace

• hnote (numpy.ndarray) – 1D time series high frequency note template

• lnote (numpy.ndarray) – 1D time series low frequency note template

• th (float) – start time of the high frequency note

• tl (float) – start time of the low frequency note

• time (numpy.ndarray) – 1D vector of time values

• fs (float) – sampling frequency

das4whales.plot.detection_grad(trace, peaks_idx, time, dist, fs, dx, selected_channels, title_time_info=None)

Plot the strain trace matrix [dist x time] with call detection above it

Parameters:

• trace (numpy.ndarray) – [channel x time sample] array containing the strain data in the spatio-temporal domain

• peaks_idx_HF (tuple) – tuple of lists containing the detected call indexes coordinates (first list: channel idx, second list: time idx) for the high frequency call

• peaks_idx_LF (tuple) – tuple of lists containing the detected call indexes coordinates (first list: channel idx, second list: time idx) for the low frequency call

• time (numpy.ndarray) – time vector

• dist (numpy.ndarray) – distance vector along the cable

• fs (float) – sampling frequency

• dx (float) – spatial step

• selected_channels (list) – list of selected channels indexes [start, stop, step]

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

das4whales.plot.detection_mf(trace, peaks_idx_HF, peaks_idx_LF, time, dist, fs, dx, selected_channels, title_time_info=None)

Plot the strain trace matrix [dist x time] with call detection above it

Parameters:

• trace (numpy.ndarray) – [channel x time sample] array containing the strain data in the spatio-temporal domain

• peaks_idx_HF (tuple) – tuple of lists containing the detected call indexes coordinates (first list: channel idx, second list: time idx) for the high frequency call

• peaks_idx_LF (tuple) – tuple of lists containing the detected call indexes coordinates (first list: channel idx, second list: time idx) for the low frequency call

• time (numpy.ndarray) – time vector

• dist (numpy.ndarray) – distance vector along the cable

• fs (float) – sampling frequency

• dx (float) – spatial step

• selected_channels (list) – list of selected channels indexes [start, stop, step]

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

das4whales.plot.detection_spectcorr(trace, peaks_idx_HF, peaks_idx_LF, time, dist, spectro_fs, dx, selected_channels, title_time_info=None)

Plot the strain trace matrix [dist x time] with call detection above it

Parameters:

• trace (numpy.ndarray) – [channel x time sample] array containing the strain data in the spatio-temporal domain

• peaks_idx_HF (tuple) – tuple of lists containing the detected call indexes coordinates (first list: channel idx, second list: time idx) for the high frequency call

• peaks_idx_LF (tuple) – tuple of lists containing the detected call indexes coordinates (first list: channel idx, second list: time idx) for the low frequency call

• time (numpy.ndarray) – time vector

• dist (numpy.ndarray) – distance vector along the cable

• spectro_fs (float) – sampling frequency of the spectrograms

• dx (float) – spatial step

• selected_channels (list) – list of selected channels indexes [start, stop, step]

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

das4whales.plot.import_parula()

Import the colormap parula from matlab

Returns:

colormap

Return type:

ListedColormap

das4whales.plot.import_roseus()

Import the colormap from the colormap/roseus_matplotlib.py file

Returns:

colormap

Return type:

ListedColormap

das4whales.plot.plot_3calls(channel, time, t1, t2, t3)

Plot the strain channel with 3 calls highlighted.

Parameters:

• channel (np.ndarray) – The strain channel.

• time (np.ndarray) – The time values.

• t1 (float) – The time of the first call.

• t2 (float) – The time of the second call.

• t3 (float) – The time of the third call.

Return type:

None

das4whales.plot.plot_associated(peaks, longi_offset, associated_list, localizations, cable_pos, dist, dx, c0, fs)

das4whales.plot.plot_cross_correlogram(corr_m, time, dist, maxv, minv=0, title_time_info=None)

Plot the cross-correlogram between HF and LF notes.

Parameters:

• corr_m (numpy.ndarray) – The cross-correlation matrix

• time (numpy.ndarray) – The time values.

• dist (numpy.ndarray) – The distance values.

• maxv (float) – The maximum value for the colorbar.

• minv (int, optional) – The minimum value for the colorbar. Default is 0.

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

Return type:

None

das4whales.plot.plot_cross_correlogramHL(corr_m_HF, corr_m_LF, time, dist, maxv, minv=0, title_time_info=None)

Plot the cross-correlogram between HF and LF notes.

Parameters:

• corr_m_HF (numpy.ndarray) – The cross-correlation matrix of the HF notes.

• corr_m_LF (numpy.ndarray) – The cross-correlation matrix of the LF notes.

• time (numpy.ndarray) – The time values.

• dist (numpy.ndarray) – The distance values.

• maxv (float) – The maximum value for the colorbar.

• minv (int, optional) – The minimum value for the colorbar. Default is 0.

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

Return type:

None

das4whales.plot.plot_fk_domain(trace, fs, dx, selected_channels, title_time_info=0, fig_size=(12, 10), v_min=None, v_max=None, fk_params=None, ax_lims=None)

Spatio-spectral representation (f-k plot) of the strain data

Parameters:

• trace (np.ndarray) – A [channel x time sample] nparray containing the strain data in the spatio-temporal domain

• fs (float) – The sampling frequency (Hz)

• dx (float) – The spatial step (m)

• selected_channels (list) – List of selected channels indexes [start, stop, step]

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

• fig_size (tuple, optional) – Tuple of the figure dimensions, by default (12, 10)

• v_min (float, optional) – Sets the min nano strain amplitudes of the colorbar, by default None

• v_max (float, optional) – Sets the max nano strain amplitudes of the colorbar, by default None

• fk_params (dict, optional) – Dictionary containing the fmin, fmax, c_min, and c_max parameters, by default None

• ax_lims (list, optional) – List of the form [f_min, f_max, k_min, k_max] for zoomed plots, by default None

Return type:

None

Notes

This function plots the spatio-spectral representation (f-k plot) of the strain data.

• The frequency axis is created using the FFT.

• The strain data is processed and plotted.

Examples

>>> plot_fk_domain(trace, time, dist, title_time_info=0, fig_size=(12, 10), v_min=None, v_max=None)

das4whales.plot.plot_fx(trace, dist, fs, title_time_info=0, win_s=2, nfft=4096, fig_size=(12, 10), f_min=0, f_max=100, v_min=None, v_max=None)

Spatio-spectral (f-x plot) of the strain data

Parameters:

• trace (np.ndarray) – A [channel x time sample] nparray containing the strain data in the spatio-temporal domain

• dist (np.ndarray) – The corresponding distance along the FO cable vector

• fs (float) – The sampling frequency (Hz)

• title_time_info (int, str, or datetime.datetime, optional) – A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

• win_s (int, optional) – The duration of each f-k plot (s), by default 2

• nfft (int, optional) – Number of time samples used for the FFT, by default 4096

• fig_size (tuple, optional) – Tuple of the figure dimensions, by default (12, 10)

• f_min (int, optional) – Displayed minimum frequency interval (Hz), by default 0

• f_max (int, optional) – Displayed maximum frequency interval (Hz), by default 100

• v_min (float, optional) – Set the min nano strain amplitudes of the colorbar, by default None

• v_max (float, optional) – Set the max nano strain amplitudes of the colorbar, by default None

Return type:

None

Notes

This function plots the spatio-spectral (f-x plot) of the strain data.

• The number of subplots is evaluated based on the duration of each f-x plot.

• The frequency axis is created using the FFT.

• The strain data is processed and plotted for each subplot.

Examples

>>> plot_fx(trace, dist, fs, title_time_info=0, win_s=2, nfft=4096, fig_size=(12, 10), f_min=0,
            f_max=100, v_min=None, v_max=None)

das4whales.plot.plot_pick_analysis(associated_list, fs, dx, longi_offset, cable_pos, dist, window_size=5, mu_ref=None, sigma_ref=None)

Create detailed plots of seismic picks with continuity analysis and a normalized curvature score.

das4whales.plot.plot_rawdata(trace, time, dist, fig_size=(12, 10))

Plot the raw DAS data.

Parameters:

• trace (ndarray) – The DAS trace data.

• time (ndarray) – The time values corresponding to the trace data.

• dist (ndarray) – The distance values corresponding to the trace data.

• fig_size (Tuple[int, int]) – The size of the figure in inches, by default (12, 10).

Return type:

None

das4whales.plot.plot_reject_pick(peaks, longi_offset, dist, dx, associated_list, rejected_list, rejected_hyperbolas, fs)

das4whales.plot.plot_spectrogram(p, tt, ff, fig_size=(20, 6), v_min=None, v_max=None, f_min=None, f_max=None)

Plot a spectrogram.

Parameters:

• p (ndarray) – Spectrogram values in dB.

• tt (ndarray) – Associated time vector (s).

• ff (ndarray) – Associated frequency vector (Hz).

• fig_size (tuple, optional) – Tuple of the figure dimensions. Default is (17, 5).

• v_min (float, optional) – Minimum dB strain amplitudes of the colorbar.

• v_max (float, optional) – Maximum dB strain amplitudes of the colorbar.

• f_min (float, optional) – Minimum frequency for the spectrogram display.

• f_max (float, optional) – Maximum frequency for the spectrogram display.

Return type:

None

das4whales.plot.plot_tx(trace, time, dist, title_time_info=0, fig_size=(12, 10), v_min=None, v_max=None, cbar_label='Strain Envelope (x$10^{-9}$)')

Spatio-temporal representation (t-x plot) of the strain data

Return type:

None

Parameters:

tracenp.ndarray

A [channel x time sample] nparray containing the strain data in the spatio-temporal domain

timenp.ndarray

The corresponding time vector

distnp.ndarray

The corresponding distance along the FO cable vector

title_time_infoint, str, or datetime.datetime, optional

A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

fig_sizetuple, optional

Tuple of the figure dimensions (default is (12, 10))

v_minfloat, optional

Sets the min nano strain amplitudes of the colorbar (default is None)

v_maxfloat, optional

Sets the max nano strain amplitudes of the colorbar (default is None)

Returns:

: None

das4whales.plot.plot_tx_env(trace, time, dist, title_time_info=0, fig_size=(12, 10), v_min=None, v_max=None, cbar_label='Strain Envelope (x$10^{-9}$)')

Spatio-temporal representation (t-x plot) of the strain data envelope

Parameters:

tracenp.ndarray

A [channel x time sample] nparray containing the strain data in the spatio-temporal domain

timenp.ndarray

The corresponding time vector

distnp.ndarray

The corresponding distance along the FO cable vector

title_time_infoint, str, or datetime.datetime, optional

A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

fig_sizetuple, optional

Tuple of the figure dimensions (default is (12, 10))

v_minfloat, optional

Sets the min nano strain amplitudes of the colorbar (default is None)

v_maxfloat, optional

Sets the max nano strain amplitudes of the colorbar (default is None)

Returns:

: None

das4whales.plot.plot_tx_lined(trace, ln_idx, time, dist, title_time_info=0, fig_size=(12, 10), v_min=None, v_max=None)

Spatio-temporal representation (t-x plot) of the strain data

Parameters:

tracenp.ndarray

A [channel x time sample] nparray containing the strain data in the spatio-temporal domain

ln_idxint

The index of the line to be plotted

timenp.ndarray

The corresponding time vector

distnp.ndarray

The corresponding distance along the FO cable vector

title_time_infoint, str, or datetime.datetime, optional

A time reference to display or the plot title. Can be a UTC timestamp (int), a formatted string, or a datetime.datetime object (default is 0).

fig_sizetuple, optional

Tuple of the figure dimensions (default is (12, 10))

v_minfloat, optional

Sets the min nano strain amplitudes of the colorbar (default is None)

v_maxfloat, optional

Sets the max nano strain amplitudes of the colorbar (default is None)

Returns:

: None

das4whales.plot.snr_matrix(snr_m, time, dist, vmax, title_time_info=None)

Matrix plot of the local signal to noise ratio (SNR)

Parameters:

• snr_m (numpy.ndarray) – [channel x time sample] array containing the SNR in the spatio-temporal domain

• time (nummpy.ndarray) – time vector

• dist (numpy.ndarray) – distance vector along the cable

• vmax (float) – maximun value of the plot (dB)

das4whales.spatial module

spatial.py - Spatial calculations for DAS data analysis in DAS4Whales.

Authors: Léa Bouffaut Date: 2025

das4whales.spatial.calc_cumulative_dist(position)

Calculate the cumulative distance along a path defined by latitude and longitude coordinates using the Haversine formula.

Parameters:

position (pandas.DataFrame) – A DataFrame containing at least ‘lat’ and ‘lon’ columns, representing latitude and longitude coordinates respectively. Typically, this data is loaded from a CSV file with position data.

Returns:

dist – An array of cumulative distances (in meters), where each element represents the total distance traveled up to that point along the path.

Return type:

numpy.ndarray

das4whales.spatial.calc_das_section_bearing(lat1, lon1, lat2, lon2)

Calculate the bearing between two geographic points on the Earth’s surface. This is used to calculate the orientation (bearing) of a section of the DAS cable.

Parameters:

• lat1 (float) – The latitude of the first point in degrees.

• lon1 (float) – The longitude of the first point in degrees.

• lat2 (float) – The latitude of the second point in degrees.

• lon2 (float) – The longitude of the second point in degrees.

Returns:

das_bearing – The bearing in degrees from the first point to the second point, relative to true north. The bearing is normalized to a range of 0 to 360 degrees.

Return type:

float

das4whales.spatial.calc_dist_lat_lon(position_1, position_2)

Calculate the distance between two sets of latitude and longitude positions using the Haversine formula.

Parameters:

• position_1 (dict) – A dictionary containing latitude and longitude values for the first position. Keys: - ‘lat’: float, the latitude (in degrees). - ‘lon’: float, the longitude (in degrees).

• position_2 (dict) – A dictionary containing latitude and longitude values for the second position. It may contain either single values (float) or lists/numpy arrays for multiple positions. Keys: - ‘lat’: float, list, or numpy.ndarray, the latitude(s) (in degrees). - ‘lon’: float, list, or numpy.ndarray, the longitude(s) (in degrees).

Returns:

distance – The distance(s) between the positions in meters: - If position_2[‘lat’] and position_2[‘lon’] are lists or numpy arrays,

returns a numpy array of distances for each corresponding position.

• Otherwise, returns a single float distance in meters for the two positions.

Return type:

numpy.ndarray or float

das4whales.spatial.calc_source_position_lat_lon(lat_ref, lon_ref, distance_m, bearing, side)

Calculate the latitude and longitude of a point that lies perpendicular to a given bearing at a specified distance, relative to a reference point.

Parameters:

• lat_ref (float) – Latitude of the reference point in degrees.

• lon_ref (float) – Longitude of the reference point in degrees.

• distance_m (float) – Distance to the perpendicular point in meters.

• bearing (float) – The bearing of the line in degrees (relative to true north).

• side (str) – Indicates the side of the bearing where the perpendicular point lies (‘right’ or ‘left’).

Returns:

lat_lon – A tuple containing: - lat (float): The latitude of the perpendicular point in degrees. - lon (float): The longitude of the perpendicular point in degrees.

Return type:

tuple

das4whales.spatial.degree_to_km_at_latitude(latitude)

Convert degrees of longitude to kilometers at a specific latitude.

Parameters:

latitude (float) – The latitude in degrees where the conversion is calculated.

Returns:

distance_km – The distance in kilometers corresponding to one degree of longitude at the specified latitude.

Return type:

float

das4whales.spatial.km_to_degree_at_latitude(km, latitude)

Convert distance in kilometers to degrees of longitude at a specific latitude.

Parameters:

• km (float) – The distance in kilometers to convert.

• latitude (float) – The latitude in degrees where the conversion is calculated.

Returns:

degrees – The equivalent distance in degrees of longitude at the specified latitude.

Return type:

float

das4whales.spatial.to_rad(degree)

Convert angle from degrees to radians.

Parameters:

degree (float) – The angle value in degrees to be converted.

Returns:

radian – The corresponding angle value in radians.

Return type:

float

das4whales.tools module

das4whales.tools.disp_comprate(fk_filter)

Display the sizes of the f-k filter matrix (sparse and dense version) and print the compression ratio

Parameters:

fk_filter (Any) – f-k filter sparse matrix designed by function dsp.hybrid_filter_design()

Return type:

None

das4whales.tools.energy_TimeDomain(da, time_dim='time')

energy_TimeDomain - calculate energy in time domain using parsevals theorem

energy is calculated for each chunk in time_dim

Parameters:

• da (DataArray) – DataArray containing DAS data

• time_dim (str) – time dimension of da

Returns:

da_energy – DataArray containing energy in time domain. Units are V^2 (where V is units of da)

Return type:

DataArray

das4whales.tools.filtfilt(da, dim, **kwargs)

filtfilt - this is an implentation of [scipy.signal.fitlfilt](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.filtfilt.html) This will filter the DAS data in time for each chunk. This process maps chunks and will therefore have error at the end of chunks in time.

By default, this does not compute, but generates the task graph

Parameters:

• da (DataArray) – DataArray containing DAS data that you want to filter.

• dim (str) – dimension to filter in (should be dimension in da)

• **kwargs (various types) – passed to [scipy.signal.filtfilt](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.filtfilt.html) as per docs, [‘x’, ‘b’, and ‘a’] are required

Returns:

da_filt – filtered data array in time. This does not compute the result, but just the task map in dask

Return type:

DataArray

das4whales.tools.filtfilt_chunk(da, dim='time', **kwargs)

converts dataarray to numpy, sends it to signal.filtfilt and then reinhereits all coordinates

Parameters:

• da (DataArray)

• dim (str) – dimension to filter over (should be dimension in da)

• **kwargs (various types) – passed to scipy.signal.filtfilt

Return type:

DataArray

das4whales.tools.fk_filt(data, tint, fs, xint, dx, c_min, c_max)

fk_filt - perform fk filtering on DAS data

Parameters:

• data (DataArray) – DataArray containing DAS data

• tint (float) – interval in time between samples

• fs (float) – sampling frequency

• xint (float) – interval in space between samples

• dx (float) – distance between samples

• c_min (float)

• c_max (float)

Return type:

DataArray

das4whales.tools.fk_filt_chunk(data, tint, fs, xint, dx, c_min, c_max)

fk_filt_chunk - perform fk filtering on single chunk of DAS data

Parameters:

• data (DataArray) – DataArray containing single chunk

• tint (float) – interval in time between samples

• fs (float) – sampling frequency

• xint (float) – interval in space between samples

• dx (float) – distance between samples

• c_min (float)

• c_max (float)

Return type:

DataArray

das4whales.tools.spec(da)

Return type:

DataArray

very quick implementation to calculate spectrogram

PSD is calculated for every chunk

Currently hardcoded for chunk size of 3000 in time :param da: das data to compute spectrogram for :type da: DataArray