API reference

The API reference is automatically generated from the function docstrings in the ocetrac package. Refer to the examples in the sidebar for reference on how to use the functions.

---

SurfTrack

Tracker

SurfTracker(da, mask, *[, radius, ...])	End-to-end surface marine heatwave tracker.
SurfTracker.run()	Execute the full pipeline: clean → filter → track → postprocess
SurfTracker.clean()	Binarise the input field, apply morphological close→open per (lat, lon) slice, then apply the ocean mask.
SurfTracker.filter()	Label 2-D slices, make IDs consecutive across time, wrap across the date line, then filter by area using:
SurfTracker.track()	Label connected objects and wrap across the date line.
SurfTracker.postprocess()	Wrap the tracked array as an xr.DataArray with NaN background and attach tracking diagnostics as attributes.
SurfTracker.n_events()	Number of unique tracked events in the final result.
SurfTracker.event_duration()	Return {event_id: n_timesteps_present} from the final result.
SurfTracker.summary()	Print event count, duration distribution, and parameters.

Measures — motion

MotionMeasures([use_decorators])

Calculates motion characteristics of labeled geospatial objects.

Measures — shape

ShapeMeasures([lat_resolution, ...])

Calculates shape characteristics of labeled geospatial objects.

Measures — intensity

calculate_intensity_metrics(anomalies[, ...])

Calculate intensity metrics from anomaly data.

Measures — temporal

get_duration(one_obj)	Gets the duration of the time coordinate in an xarray object.
get_initial_detection_time(one_obj)	Gets the initial detection time from an xarray object.

Measures — plotting

plot_displacement(coordinate_list, ...[, ...])

Plots the displacement of centroids over time on an intensity map.

---

DeepTrack

Tracker

DeepTracker(da, *[, radius, min_area_cells, ...])	4-D event tracker
DeepTracker.run([cell_volume])	Execute the full pipeline: clean → label → connect_depth → prefilter → track → postprocess
DeepTracker.clean()	Binarise and morphologically clean (close→open) the input field.
DeepTracker.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
DeepTracker.connect_depth()	Area filter → relabel → 3-D depth connectivity.
DeepTracker.prefilter()	Drop globally smallest 3-D objects by voxel count.
DeepTracker.track([cell_volume])	Containment-based temporal tracking with lineage preservation.
DeepTracker.postprocess()	Wrap tracked array as an xr.DataArray result.
DeepTracker.n_events()	Number of unique tracked events in the final result.
DeepTracker.event_duration()	Return {event_id: n_timesteps_present} from the final result.
DeepTracker.summary()	Print event count, duration distribution, and parameters.

Grid

compute_dz(z_t)	Convert depth midpoints to layer thicknesses via central differencing; forward/backward differencing at the boundaries.
build_cell_volume(TAREA, z_t[, n_z])	Compute a 3-D cell-volume array (z_t, nlat, nlon) for a POP-style grid.
make_anisotropic_struct([connect_xy, connect_z])	Build a (3, 3, 3) boolean structuring element for 3-D connected-component labelling.

Core algorithms

label_2d_stack(binary)	Connected-component labelling on each (t, z) slice independently.
filter_area_2d_global_depth(arr_4d[, ...])	Remove small 2-D objects per depth level using an area distribution computed across ALL timesteps.
build_3d_objects(filtered_np, structure)	Apply 3-D connected-component labelling across (z, nlat, nlon) for every timestep independently.
filter_preserve_labels_global(tracks[, frac])	Remove the smallest frac fraction of 3-D objects by total voxel count summed across ALL timesteps.
track_objects_with_splitting(depth_connected)	Track objects across time using containment with lineage preservation.