marine-tracker / src /analysis.py
narniagooooo's picture
Initial commit: marine mammal tracking dashboard and route prediction
27b6a20
Raw History Blame Contribute Delete
3.65 kB
"""Per-individual and per-study movement analysis.
Distance/speed/activity-pattern metrics work for any study in the common
event schema (see ingest.py). Dive metrics only apply to studies whose raw
data includes a depth/pressure sensor column -- none of this project's three
default studies are depth-instrumented (they're Argos/GPS location-only), so
dive_metrics() detects that and returns None rather than fabricating numbers.
"""
import numpy as np
import pandas as pd
from clean import haversine_km
from predict import track_segments
DEPTH_COLUMN_CANDIDATES = ["depth", "pressure", "argos:depth", "eobs:pressure"]
def individual_summary(individual_df):
"""Total distance (km), average speed (km/h), and track span for one individual's fixes."""
df = individual_df.sort_values("timestamp")
segments = track_segments(df)
total_distance_km = float(
haversine_km(
df["location_lat"].values[:-1], df["location_long"].values[:-1],
df["location_lat"].values[1:], df["location_long"].values[1:],
).sum()
) if len(df) > 1 else 0.0
valid_speeds = segments["speed_kmh"].replace([np.inf, -np.inf], np.nan).dropna()
avg_speed_kmh = float(valid_speeds.mean()) if len(valid_speeds) else 0.0
return {
"individual_local_identifier": df["individual_local_identifier"].iloc[0],
"n_fixes": len(df),
"start_time": df["timestamp"].min(),
"end_time": df["timestamp"].max(),
"total_distance_km": round(total_distance_km, 1),
"average_speed_kmh": round(avg_speed_kmh, 2),
}
def study_summary(study_df):
"""Per-individual summary table for every individual in a study's DataFrame."""
rows = [individual_summary(g) for _, g in study_df.groupby("individual_local_identifier", sort=False)]
return pd.DataFrame(rows).sort_values("total_distance_km", ascending=False).reset_index(drop=True)
def activity_pattern(individual_df):
"""Fix count by hour-of-day (0-23, UTC as provided by Movebank), a simple activity proxy.
Not a true diel activity/dive-behavior classification -- just how the
fixes are distributed across the day, which can hint at surfacing
patterns if the tag only reports while at the surface.
"""
df = individual_df.copy()
df["hour"] = pd.to_datetime(df["timestamp"]).dt.hour
return df.groupby("hour").size().reindex(range(24), fill_value=0)
def dive_metrics(individual_df):
"""Dive/surface summary if the raw data includes a depth or pressure column, else None."""
depth_col = next((c for c in DEPTH_COLUMN_CANDIDATES if c in individual_df.columns), None)
if depth_col is None:
return None
depths = individual_df[depth_col].dropna()
if depths.empty:
return None
return {
"depth_column_used": depth_col,
"max_depth": float(depths.max()),
"mean_depth": float(depths.mean()),
"n_dive_records": int(len(depths)),
}
def movement_corridor_bins(study_df, grid_size_deg=0.5):
"""Aggregate all individuals' fixes into a lat/lon grid for a movement-corridor density overlay.
Returns a DataFrame of (lat_bin, lon_bin, count), suitable for a heatmap
showing which areas the study's tracked individuals used most, as a
reasonable "movement corridor" proxy without fitting a formal utilization
distribution model.
"""
df = study_df.copy()
df["lat_bin"] = (df["location_lat"] / grid_size_deg).round() * grid_size_deg
df["lon_bin"] = (df["location_long"] / grid_size_deg).round() * grid_size_deg
return df.groupby(["lat_bin", "lon_bin"]).size().reset_index(name="count")