obsea package

Submodules

obsea.ais module

AIS module.

Used to read AIS files.

obsea.ais.cls_time_parser(x)

obsea.ais.read_cls(fname, cargo_and_tanker=True)

Read AIS data from CLS format.

Parameters:

• fname (string) – File name.

• cargo_and_tanker (bool, optional) – Whether only to keep cargos and thankers.

Returns:

AIS data as a DataFrame with four columns: mmsi - time - lon - lat

Return type:

pandas.DataFrame

obsea.ais.read_marine_traffic(fname, terrestrial=True)

Read AIS data from Marine Traffic format.

Parameters:

• fname (string) – File name.

• terrestrial (bool, optional) – Whether only to keep terrestrial AIS.

Returns:

AIS data as a DataFrame with four columns: mmsi - lon - lat - time

Return type:

pandas.DataFrame

obsea.ais.select_ships(ais, mmsi_list)

Filter out ship from ais which do not belongs to mmsi_list.

Parameters:

• ais (pandas.DataFrame) – AIS data.

• mmsi_list (list) – List of wanted ships’ MMSI.

Returns:

AIS data containing ship in mmsi_list.

Return type:

pandas.DataFrame

obsea.beamforming module

Beamforming module.

Used to relocalize recoding instruments on the seafloor.

obsea.beamforming.cubic(x, x0, dx, y)

One-dimensional cubic interpolation of evenly spaced data.

Parameters:

• x (float) – Value at which the interpolation in performed

• x0 (Grid starting location) – Grid starting location.

• dx (float) – Grid spacing.

• y (array_like) – Values at each grid location.

Returns:

Interpolated value.

Return type:

float

obsea.beamforming.interp(x, xp, fp, kind='cubic')

One-dimensional interpolation of evenly spaced data.

Returns the one-dimensional piecewise linear interpolant to a function with given discrete data points (xp, fp), evaluated at x.

Parameters:

• x (array_like) – The x-coordinates at which to evaluate the interpolated values.

• xp (1-D sequence of floats) – The x-coordinates of the data points

• fp (1-D sequence of float or complex) – The y-coordinates of the data points, same length as xp.

• kind (str, optional) – Type of interpolation. Default to cubic.

Returns:

The interpolated values, same shape as x.

Return type:

float or complex (corresponding to fp) or ndarray

Raises:

NotImplementedError – For now only kind=’cubic’ is accepted.

obsea.beamforming.linear(x, x0, dx, y)

One-dimensional linear interpolation of evenly spaced data.

Parameters:

• x (float) – Value at which the interpolation in performed

• x0 (Grid starting location) – Grid starting location.

• dx (float) – Grid spacing.

• y (array_like) – Values at each grid location.

Returns:

Interpolated value.

Return type:

float

obsea.beamforming.linear_beamform(a, b, xarr, dims=('b', 'a'))

obsea.beamforming.linear_core(a, b, zp, xp, yp)

obsea.beamforming.make_beamform(x, y, xarr, delay, interpolation='cubic')

Build a beamformer.

Parameters:

• x (array_like) – The x-coordinates.

• y (array_like) – The y-coordinates.

• xarr (xarray.DataArray) – Data from which beamforming is performed.

• delay (function) – Function used to compute delays.

• interpolation (str, optional) – Interpolation scheme used (Default cubic).

Returns:

beamform(*args, enveloppe=True) – Beamform function ready to be run. Given arguments to that function are transmetted to the delay function in order to explore different beamforming parameters. The eveloppe kwarg dictate wether to return the enveloppe of the computed image or not.

Return type:

function

Raises:

NotImplementedError – For now only interpolation=’cubic’ is accepted.

obsea.beamforming.make_delay(track_xarr)

Build a delay function according to a range independent simple model.

Parameters:

track_xarr (xarray.dataArray) – A ship trajectory.

Returns:

delay(r, t, c, d) – Delay function which returns the proper delay according to the a given position r, a time t, a celerity c and a depth d.

Return type:

function

obsea.beamforming.x2imu(x, x0, dx)

Locate a value in a 1D evenly spaced grid as index and remainder.

Parameters:

• x (float) – Value which location must be retreived.

• x0 (float) – Grid starting location.

• dx (float) – Grid spacing.

Returns:

• i (float) – Floor index.

• mu (float) – Remainder (between 0 and 1).

obsea.core module

Core module.

Contains all core processing functions to transform raw signal in usefull 2D representations.

obsea.core.CHANNEL_TO_AXIS

Links channels names to their physical meanings (pressure, velocities)

Type:

dict

obsea.core.analytic_signal(xarr)

Compute the analytic_signal of a one sided cepstrogram (or spectrogram).

Analytic signal can be usefull to compute the envelope and the instantaneous phase. It allows coherent summation or incoherent summation (adding modulus and discarting the phase).

Parameters:

xarr (xarray.DataArray) – One sided cepstrogram (or spectrogram).

Returns:

Analytic signal of the cepstrogram (or spectrogram).

Return type:

xarray.DataArray

obsea.core.azigram(z, nperseg, step, method='intensity', mode='net', dim='time', iid=1)

Compute azigram.

Parameters:

• z (xarray.DataSet) – Must contain a time-frequency representation for horizontal velocities (‘vx’ and ‘vy’) and for the pressure channel (‘p’) is method is ‘intensity’

• nperseg (int) – Length of each segment in samples used in the mean direction of arrival (DOA) and mean running length (MRL) computation.

• step (int) – Number of point between segments.

• method (str, optional) – Method used to compute DOA. Either ‘intensity’ or ‘polarization’. If polarization is chosen angles are doubled so that the full 360 degree range is used (polarization suffers from 180 degree amgiguity)

• mode (str, optional) – Mode used to compute DOA. Either ‘net’ or ‘instantaneous’.

• dim (str, optional) – Dimension along which to compute the mean running length. Choose ‘time’ for tonal signals and ‘frequency’ for impulsive signals.

• iid (int, optional) – TODO

Returns:

Azigram of horizontal DOA. DOA is given as a complex values so that the real part point toward East and the imaginary part point toward North. Modulus of those values are MRL. The DataArray as a attrs.double_angle attribute which states if values represent the DOA or its double.

Return type:

xarray.DataArray

obsea.core.cepstrogram(xarr, analytic=False)

Compute the cepstrogram of a time-frequency representation.

Cepstrogram can be usefull to compute time difference between different arrivals or to study the harmonic structure of a signal.

Parameters:

• xarr (xarray.DataArray) – Time-frequency representation.

• analytic (bool, optional) – Whether to return the analytical signal of the cepstrogram.

Returns:

Computed Cepstrogram.

Return type:

xarray.DataArray

obsea.core.intensity(z, method='intensity', mode='net')

Compute acoustic intensity.

Parameters:

• z (xarray.DataSet) – Must contain a time-frequency representation for horizontal velocities (‘vx’ and ‘vy’) and for the pressure channel (‘p’) if method is ‘intensity’

• method (str, optional) – Method used to compute DOA. Either ‘intensity’ or ‘polarization’. If polarization is chosen angles are doubled so that the full 360 degree range is used (polarization suffers from 180 degree amgiguity)

• mode (str, optional) – Mode used to compute DOA. Either ‘net’ or ‘instantaneous’.

Returns:

Acoustic intensity as a Dataset with components ‘vx’ and ‘vy’.

Return type:

xarray.DataSet

obsea.core.orientation_frequency(r, track, bins, sigma=None, fmin=None, fmax=None)

Compute orientation-frequency representation of an azigram.

from an azigram and a track of an acoustic source. Approximate pseudo kernel density estimation is performed by smoothing an weighted histogram with a Gaussian kernel on each frequency.

Parameters:

• r (xarray.DataArray) – Azigram. Values are complex number which argument are the DOAs and modulus are the MRL or any other wanted weight.

• track (shapely.LineString) – Acoustic source trajectory

• bins (int) – Number of bins used to computes histograms on 360 degrees.

• sigma (float, optional) – Standard deviation for Gaussian kernel in degrees. If None, no smoothing is applied (default).

• fmin (float, optional) – Values which frequencies are below fmin are not used in the density estimation. If None no restriction is applied (default).

• fmax (float, optional) – Values which frequencies are above fmax are not used in the density estimation. If None no restriction is applied (default).

Returns:

Orientation-frequency representation.

Return type:

xarray.DataArray

obsea.core.remove_response(tf, response, water_level)

Remove instrumental response.

obsea.core.spectrogram(xarr)

obsea.core.stft(da, nperseg, step)

Compute the Short Time Fourrier Transform (STFT) of a trace.

obsea.core.time_azimuth(r, nperseg, step, bins, sigma=None, fmin=None, fmax=None)

Compute time-azimuth representation of an azigram.

Approximate pseudo kernel density estimation is performed by smoothing an weighted histogram with a Gaussian kernel on temporal windows.

Parameters:

• r (xarray.DataArray) – Azigram. Values are complex number which argument are the DOAs and modulus are the MRL or any other wanted weight.

• nperseg (int) – Lenght of each segment in samples used in the density estimation.

• step (int) – Number of points between segments.

• bins (int) – Number of bins used to computes histograms on 360 degrees.

• sigma (float, optional) – Standard deviation for Gaussian kernel in degrees. If None, no smoothing is applied (default).

• fmin (float, optional) – Values which frequencies are below fmin are not used in the density estimation. If None no restriction is applied (default).

• fmax (float, optional) – Values which frequencies are above fmax are not used in the density estimation. If None no restriction is applied (default).

Returns:

Time-azimuth representation.

Return type:

xarray.DataArray

obsea.core.time_frequency(st, nperseg, step, water_level=None, inventory=None)

Compute time-frequency representations of trace in stream.

Instrumental response can be remove by water level deconvolution if an inventory is provided.

Parameters:

• st (obspy.Stream) – List like object of multiple traces.

• nperseg (int) – Length of each segment in samples used in the FFT computation.

• step (int) – Number of point between segments.

• water_level (int, optional) – Water level (in dB) used in water level deconvolution. If None, no instrumental removal is perform (Defaults).

• inventory (obspy.Inventory, optional) – Inventory used to retrieve the instrumental responses. Required if water_level is not None.

Returns:

Dataset made of one DataArray per trace with appropriate ‘time’ and ‘frequency’ coordinates.

Return type:

xarray.Dataset

obsea.core.to_dataset(st)

Convert a stream to a dataset.

obsea.datasets module

Dataset module.

Used to retrieve the absolut path of toys datasets shiped with obsea.

obsea.datasets.data_path

directory where datasets are stored.

Type:

string

obsea.datasets.get_dataset_path(dataset)

Give absolute path of toys datasets.

Parameters:

dataset (string) – Dataset name. Can be ‘ais_cls’, ‘ais_marine_traffic’, ‘mmsi_list’, ‘station_list’ or ‘ais_week_cls’.

Returns:

Absolute path.

Return type:

string

obsea.detection module

Detection module.

Used to perform azimuthal and radial detection.

obsea.detection.R2gamma(R)

obsea.detection.abs2(z)

obsea.detection.build_model(mu, sigma, tdoa, dtau, fs)

Build propagative model.

Parameters:

• mu (DataArray) – Expected mean of the cepstrum as a function of quefrency and distance.

• sigma (DataArray) – Expected std of the cepstrum as a function of quefrency.

• tdoa (DataArray) – Time difference of arrival as a function of the interference and distance.

• dtau (float) – Cepstral pulse width in seconds. Can be chosen as the inverse of the signal bandwidth.

• fs (float) – Sampling rate

obsea.detection.cepstral_detection(ceps, model, grid, nsigma, t_step=None, t=None)

Compute the radial log likelihood ratio.

Parameters:

• ceps (DataArray) – The cepstrogram from which the detection with be performed. Dimensions must be (quefrency, time).

• model (DataArray) – The propagative model. Give the expected cepstram mean for each interference, distance and quefrency dimensions.

• grid (dict) – Parameters of the grid over which probabilities are computed. Must include dt the lenght of the sliding window (seconds), dr and rmax the radial step and max value (meters), and, dv and `vmax the speed step and max value (m/s).

• nsigma (float) – Smoothing value along the quefrency dimension in number of samples.

• t_step (float) – Temporal stepping (seconds) at which compute probabilities.

• t (1d array) – Time (seconds) at wich probabilties must be computed. Usefull to synchronize with another detector. If provided t_step is ignored.

obsea.detection.compute_logell(x, thresh, weight, index, halfwidth)

obsea.detection.compute_zeta(mu, gamma)

obsea.detection.impulsive_detection(u, n, orientation, R, dt, df, pd, endpoint=True, t_step=None, t=None)

Compute the azimuthal likelihood ratio for impulsive sources.

Parameters:

• u (DataArray) – Time-frequency azimuthal measurements as polar unitary complex values. Dimenions must be “time” and “frequency”.

• n (int) – Number of azimuthal bins from 0 to 360 degrees.

• orientation (float) – Sensor azimuthal orientation in degrees.

• gamma (float) – Wrapped Cauchy parameter. R = exp(-gamma).

• dt (Float) – Time window duration in seconds used for likelihood computation.

• df (Float) – Source frequency bandwidth in Hertz.

• pd (Float) – Source probability of detection during one time sample.

• endpoint (bool, optional) – Weather to include 360 as the last sample. Default is True

• t_step (float, optional) – Time increment at which compute values. Default to dt/2.

Returns:

Likelihood ratio with dimensions “time” and “azimuth”.

Return type:

DataArray

obsea.detection.ms2tw(mu, sigma)

obsea.detection.t_range(t, dt, t_step=None)

obsea.detection.tonal_detection(u, n, orientation, R, dt, endpoint=True, t_step=None, t=None)

Compute the azimuthal likelihood ratio for tonal sources.

Parameters:

• u (DataArray) – Time-frequency azimuthal measurements as polar unitary complex values. Dimenions must be “time” and “frequency”.

• n (int) – Number of azimuthal bins from 0 to 360 degrees.

• orientation (float) – Sensor azimuthal orientation in degrees.

• gamma (float) – Wrapped Cauchy parameter. R = exp(-gamma).

• dt (Float) – Time window duration in seconds used for likelihood computation.

• endpoint (bool, optional) – Weather to include 360 as the last sample. Default is True

• t_step (float, optional) – Time increment at which compute values. Default to dt/2.

Returns:

Likelihood ratio with dimensions “time” and “azimuth”.

Return type:

DataArray

obsea.detection.v2i(x, dx)

obsea.detection.wrapcauchy(z, zeta)

obsea.detection.zeta_range(n, orientation, gamma, endpoint=True)

obsea.gis module

obsea.io module

obsea.plot module

obsea.processing module

obsea.raytracing module

obsea.station module

obsea.tracking module

Module contents