ocetrac.DeepTrack.DeepTracker#

class ocetrac.DeepTrack.DeepTracker(da: DataArray, *, radius: int = 3, min_area_cells: int = 200, min_quantile: float = 0.25, contain_thresh: float = 0.3, alpha: float = 0.5, frac_filter: float = 0.25, connect_z: bool = True, positive: bool = True, n_z: int = 20, wrap_lon: bool = False)[source]#

4-D event tracker

Parameters:

  • da (DataArray (time, z_t, nlat, nlon))

  • radius (int — disk radius for morphological close→open)

  • min_area_cells (int — absolute minimum 2-D blob area in grid cells)

  • min_quantile (float — relative area-filter percentile (combined with) – min_area_cells via max)

  • contain_thresh (float — minimum containment score to link objects across time)

  • alpha (float — voxel vs volume containment weight (0=volume, 1=voxel))

  • frac_filter (float — drop bottom fraction of 3-D objects by voxel count) – before tracking

  • connect_z (bool — vertical connectivity in 3-D labelling)

  • positive (bool — True → warm anomalies, False → cold)

  • n_z (int — number of depth levels to use)

  • wrap_lon (bool - True -> merge objects that straddle the dateline) – Should be True for global grids (nlon spans 360°) and False for regional domains. Default False

__init__(da: DataArray, *, radius: int = 3, min_area_cells: int = 200, min_quantile: float = 0.25, contain_thresh: float = 0.3, alpha: float = 0.5, frac_filter: float = 0.25, connect_z: bool = True, positive: bool = True, n_z: int = 20, wrap_lon: bool = False) → None[source]#

Methods

__init__(da, *[, radius, min_area_cells, ...])

clean()

Binarise and morphologically clean (close→open) the input field.

connect_depth()

Area filter → relabel → 3-D depth connectivity.

event_duration()

Return {event_id: n_timesteps_present} from the final result.

label()

Label each (t, z) slice with 2-D connected components, then apply longitude wrapping so objects that straddle the date line are merged before area filtering

n_events()

Number of unique tracked events in the final result.

postprocess()

Wrap tracked array as an xr.DataArray result.

prefilter()

Drop globally smallest 3-D objects by voxel count.

run([cell_volume])

Execute the full pipeline: clean → label → connect_depth → prefilter → track → postprocess

summary()

Print event count, duration distribution, and parameters.

track([cell_volume])

Containment-based temporal tracking with lineage preservation.