plot

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)