detect_transient

echopype.clean.detect_transient(ds: Dataset, method: str, params: dict) → DataArray

Dispatch transient-noise detection to a chosen method and return a boolean mask.

This dispatcher forwards ds and params to the selected implementation (e.g. "fielding", "matecho"). Any optional arguments omitted in params are filled by that method’s own defaults.

Parameters:

dsxr.Dataset

Acoustic dataset with Sv and required coordinates. Must contain Sv in dB (default variable name "Sv") and include at least ping_time and a vertical/range coordinate (e.g. range_sample or a depth).

methodstr

Name of the detection method. Supported:

• "fielding" → modified Fielding-style deep transient detector

• "matecho" → Matecho-style column detector using local percentile

• "ryan" → to be implemented TODO

paramsdict

Method-specific keyword arguments (see below). Omitted keys fall back to the method’s defaults.

When method == “fielding”, params can contain:

var_namestr, default “Sv”

Name of the Sv variable (dB).

range_varstr, default “depth”

Name of the vertical coordinate. Can be 1-D (range) or 2-D (time×range).

r0, r1float, default 900, 1000

Upper/lower bounds of the vertical window (m).

nint, default 30

Half-width of the temporal neighbourhood (pings) for the block median.

thr(float, float), default (3, 1)

Two-stage dB thresholds for detection/propagation.

rofffloat, default 20

Stop depth (m) for upward propagation (don’t propagate above this).

jumpsfloat, default 5

Vertical step (m) when iteratively moving the window upward.

maxtsfloat, default -35

Max 75th-percentile Sv (dB) for a ping to be considered “quiet”.

startint, default 0

Number of initial pings treated as uncomputable in the auxiliary mask (note: they are still kept/VALID unless you decide otherwise).

When method == “matecho”, params can contain:

var_namestr, default “Sv”

Name of the Sv variable (dB).

range_varstr, default “depth”

Vertical coordinate; reduced to 1-D per leading dim if 2-D.

time_varstr, default “ping_time”

Time/ping dimension name.

bottom_varstr | None, default None

Optional bottom depth per ping (m). If None/NaN, uses max range.

start_depthfloat, default 220

Top of the vertical detection window (m).

window_meterfloat, default 450

Vertical window thickness (m).

window_pingint, default 100

Temporal window width (pings) for local reference stats.

percentilefloat, default 25

Reference percentile (dB) of the local window.

delta_dbfloat, default 12

Excess over percentile (dB) required to flag a ping column.

extend_pingint, default 0

Optional horizontal dilation (pings) of flagged columns.

min_windowfloat, default 20

Minimum usable window height (m); skip if smaller.

When method == “ryan”, params can contain:

ryan (TODO)

Returns:

xr.DataArray

Boolean mask aligned to ds[var_name] (same dims and order), where True = VALID (keep) and False = transient noise. The name/attrs are set by the called method.

Raises:

ValueError

If method is not supported.

Examples

>>> from echopype.clean import detect_transient
>>> mask_fielding = detect_transient(
...     ds=ds_Sv_trimmed,
...     method="fielding",
...     params={
...         "var_name": "Sv",
...         "range_var": "depth",
...         "r0": 900,
...         "r1": 1000,
...         "n": 10,
...         "thr": (3, 1),
...         "roff": 20,
...         "jumps": 5,
...         "maxts": -35,
...         "start": 0,
...     },
... )

or

>>> from echopype.clean import detect_transient
>>> mask_matecho = detect_transient(
...     ds=ds_Sv,
...     method="matecho",
...     params={
...         "var_name": "Sv",
...         "range_var": "depth",
...         "bottom_var": None,
...         "start_depth": 700,
...         "window_meter": 300,
...         "window_ping": 50,
...         "percentile": 25,
...         "delta_db": 8,
...         "extend_ping": 0,
...         "min_window": 5,
...     },
... )