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

Near-term movement projection: two honesty-first tiers.
 
`heading` (default): estimate current bearing and speed from the last N
fixes, project forward linearly, and grow an uncertainty cone whose width is
grounded in that individual's own historical bearing/speed variance -- not an
arbitrary constant. This is the credible baseline.
 
`markov` (optional upgrade): discretize the individual's own historical
bearing changes into direction bins, build a transition model from its own
track, and simulate a small ensemble of forward paths. The output is a
spread of plausible paths, not one line.
 
Neither tier should be read as a forecast of certainty. Both are labeled
"projected range of motion" by the callers in analysis.py/app.py.

 
Modules
       
numpy
pandas

 
Functions
       
bearing_deg(lat1, lon1, lat2, lon2)
Initial great-circle bearing in degrees (0=north, 90=east) from point 1 to point 2.
circular_mean_deg(bearings)
Mean of a list of compass bearings (degrees), handling the 0/360 wraparound.
circular_std_deg(bearings)
Circular standard deviation of compass bearings (degrees), handling wraparound.
destination_point(lat, lon, bearing, distance_km)
Great-circle destination point given a start point, bearing (deg), and distance (km).
predict(individual_df, mode='heading', **kwargs)
Dispatch to predict_heading (default) or predict_markov.
predict_heading(individual_df, window=10, horizon_hours=24, step_hours=1)
Linear heading/speed projection with a variance-grounded expanding uncertainty cone.
 
Uses the last `window` segments to estimate current heading and speed,
and the individual's *entire* track history to estimate bearing/speed
variance (so the cone reflects how erratically this individual actually
moves, not an arbitrary assumption). Returns a dict with:
  - centerline: list of (timestamp, lat, lon) for the projected path
  - cone_left / cone_right: matching boundary lat/lon lists
  - summary: short plain-language description
  - heading_deg, speed_kmh, bearing_std_deg, speed_std_deg (for transparency)
predict_markov( individual_df, n_bins=16, horizon_hours=24, step_hours=1, n_runs=50, random_state=None )
Sample an ensemble of forward paths from a bearing-transition model built on this individual's own history.
 
Returns a dict with `paths`: a list of n_runs paths, each a list of
(timestamp, lat, lon), plus a `summary`. Communicates uncertainty as a
spread of simulated paths rather than a single predicted line.
track_segments(individual_df)
Return per-consecutive-fix bearing (deg) and speed (km/h) for one individual's sorted track.
 
Expects individual_df sorted by timestamp with location_lat/location_long columns.
Returns a DataFrame of len(individual_df) - 1 rows with columns bearing, speed_kmh, dt_hours.

 
Data
        EARTH_RADIUS_KM = 6371.0088