clean
index
/Users/samuelveliveli/Downloads/marine-tracker/src/clean.py

Clean noisy satellite tag fixes: speed filtering, deduplication, optional smoothing.
 
Raw Argos/GPS fixes on marine mammals contain occasional large location errors
that imply impossible travel speeds. This module applies the classic
McConnell et al. (1992) speed-filtering approach used widely in marine
telemetry: a forward pass per individual that drops any fix which would
require traveling faster than a per-species plausible maximum from the last
retained fix.

 
Modules
       
numpy
pandas

 
Functions
       
clean_track(df, max_speed_kmh=None, smooth=False)
Full cleaning pipeline: dedupe -> speed filter -> optional Kalman smoothing.
haversine_km(lat1, lon1, lat2, lon2)
Great-circle distance in km between two (lat, lon) points in decimal degrees.
kalman_smooth(df, process_noise=0.0001, measurement_noise=0.001)
Apply a simple constant-velocity Kalman smoother to each individual's lat/lon track.
 
Returns a copy of df with location_lat/location_long replaced by smoothed
estimates. This is an optional pass -- toggle raw vs. smoothed in the app
rather than always applying it, since smoothing can mask genuine sharp
turns.
remove_duplicates(df, min_time_diff_seconds=60, min_dist_m=1.0)
Drop near-duplicate consecutive fixes for the same individual.
 
A fix is considered a near-duplicate of the previous one if it arrived
within min_time_diff_seconds AND within min_dist_m -- i.e. it adds no new
information about position or timing. Iterates over numpy arrays rather
than DataFrame rows since this forward-dependent pass (each decision
depends on the last *retained* fix) can't be fully vectorized, and
per-row Series construction is the dominant cost on studies with 100k+ fixes.
speed_filter(df, max_speed_kmh=None)
Drop fixes that imply travel speed above a per-species plausible maximum.
 
Forward pass per individual (McConnell et al. speed-filtering approach):
walk fixes in time order, keeping a fix only if its implied speed from the
last *retained* fix is at or below the threshold. max_speed_kmh may be a
single float (applied to all individuals) or None to look up each row's
species in SPECIES_MAX_SPEED_KMH (falling back to DEFAULT_MAX_SPEED_KMH).
Iterates over numpy arrays rather than DataFrame rows for the same reason
as remove_duplicates: the greedy dependency prevents full vectorization,
but avoiding per-row Series construction is still much faster.

 
Data
        DEFAULT_MAX_SPEED_KMH = 15.0
EARTH_RADIUS_KM = 6371.0088
SPECIES_MAX_SPEED_KMH = {'Balaena mysticetus': 15.0, 'Balaenoptera musculus': 20.0, 'Balaenoptera physalus': 20.0, 'Halichoerus grypus': 20.0, 'Megaptera novaeangliae': 15.0, 'Phoca vitulina': 20.0, 'Trichechus manatus': 10.0}