deepSSF 0.3.0__tar.gz → 0.3.1__tar.gz

{deepssf-0.3.0 → deepssf-0.3.1}/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project are documented here.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-23
+
+### Added
+- **Step length and turning angle columns** — `prepare_movement_df` now returns
+  `sl_` (step length, the Euclidean length of `(dx, dy)`, placed after `dx`/`dy`)
+  and `ta_` (turning angle, placed after `bearing_tm1`). `ta_` is
+  `bearing - bearing_tm1` wrapped to [-π, π), so a slight turn across the ±π
+  boundary is not reported as a near-full rotation; positive values are
+  anticlockwise turns, following the `arctan2` bearing convention. It is NaN for
+  each individual's first step, which has no previous bearing. Neither column is
+  a model input.
+- **`tz` argument to `prepare_movement_df`** — the timezone to express
+  timestamps and time-derived columns in, e.g. `"Australia/Darwin"`. When
+  omitted, the timezone of a tz-aware time column is kept; tz-naive times are
+  still treated as UTC.
+- **Timestamps on simulated trajectories** — `simulate_trajectory`,
+  `simulate_trajectories_batched` and `simulate_trajectories` take an optional
+  `start_time` and, when it is given, add a `time` column (before `hour`) rolled
+  forward from it by `time_between_steps`. Rolling forward rather than rebuilding
+  from `yday`/`hour` keeps the year (which `yday` loses when it wraps at 365)
+  and the timezone of `start_time`. It only labels the output — the model still
+  reads `starting_yday`/`starting_hour`, so these should describe the same
+  moment. `simulate_trajectories` accepts one start time per trajectory under
+  `method="sequential"`/`"parallel"`; `"batched"` requires a single value, as it
+  does for the other start-time arguments.
+- **Example notebook `deepssf_train_validate_example_v0_3_1.ipynb`** — adds
+  diagnostic summaries of the observed and simulated data: step length and
+  turning angle histograms, and both by hour of day. Turning angles are
+  summarised per hour by the circular SD and the shortest arc containing 50% of
+  the angles (which may wrap across ±π), since a mean or median sits near zero
+  whatever the spread.
+
+### Fixed
+- **Times were converted to UTC in `prepare_movement_df`.** Timestamps were
+  parsed with `utc=True` and the input's timezone was never restored, so a
+  tz-aware time column (e.g. converted to `Australia/Darwin`) still produced
+  `hour_t1`, `yday_t1` and their sine/cosine encodings in UTC — 9.5 h out for
+  Darwin, misplacing diel patterns such as dawn and dusk activity peaks. These
+  columns are now in local time, and `t1_`/`t2_` are tz-aware timestamps
+  rather than the raw input values. The Sentinel-2 month look-up in
+  `MovementDataset`, which reads `t1_`, now uses the local month too.
+  **Models trained with ≤ 0.3.0 on tz-aware times learned UTC hour encodings**,
+  so retrain them (and re-run any simulations) before comparing against data
+  prepared with this version.
+
 ## [0.3.0] - 2026-10-23
 
 ### Added

{deepssf-0.3.0 → deepssf-0.3.1}/CITATION.cff

@@ -10,4 +10,4 @@ authors:
 repository-code: "https://github.com/swforrest/deepssf"
 url: "https://swforrest.github.io/deepSSF/"
 license: MIT
-version: 0.1.0
+version: 0.3.1

{deepssf-0.3.0 → deepssf-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: deepSSF
-Version: 0.3.0
+Version: 0.3.1
 Summary: Deep learning step selection functions for predicting animal movement.
 Project-URL: Homepage, https://swforrest.github.io/deepSSF/
 Project-URL: Repository, https://github.com/swforrest/deepssf

{deepssf-0.3.0 → deepssf-0.3.1}/examples/deepssf_train_validate_example_v0_3_0.ipynb

@@ -143,11 +143,11 @@
     "# Sort by the individual ID and timestamp to ensure correct temporal order\n",
     "raw_df = raw_df.sort_values(by=[\"id\", \"time\"]).reset_index(drop=True)\n",
     "\n",
-    "# # Convert the 'time' column to the correct timezone (here Australia/Darwin) \n",
-    "raw_df[\"time\"] = (\n",
-    "        pd.to_datetime(raw_df[\"time\"], utc=True)\n",
-    "        .dt.tz_convert(\"Australia/Darwin\")\n",
-    "    )\n",
+    "# # # Convert the 'time' column to the correct timezone (here Australia/Darwin) \n",
+    "# raw_df[\"time\"] = (\n",
+    "#         pd.to_datetime(raw_df[\"time\"], utc=True)\n",
+    "#         .dt.tz_convert(\"Australia/Darwin\")\n",
+    "#     )\n",
     "\n",
     "raw_df.head()"
    ]
@@ -253,7 +253,8 @@
     "    id_col=\"id\", \n",
     "    time_col=\"time\", \n",
     "    x_col=\"x\", \n",
-    "    y_col=\"y\"\n",
+    "    y_col=\"y\",\n",
+    "    tz=\"Australia/Darwin\"\n",
     ")\n",
     "\n",
     "n_dropped = len(raw_df) - len(step_df)\n",
@@ -261,6 +262,195 @@
     "step_df.head()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Check the timezone"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "step_df[\"t1_\"].dt.tz"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualise some data summaries\n",
+    "\n",
+    "Partly this is diagnostic, to check whether the time is in the correct timezone (we know that buffalo have high movement periods around dawn and dusk, so we can see whether that aligns). We can also check these summaries against summaries of the simulated trajectories to see whether we've captured these behaviours.\n",
+    "\n",
+    "### Distribution of step lengths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Distribution of step lengths, with the median and mean marked\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.hist(step_df[\"sl_\"], bins=250, color=\"tab:blue\", alpha=0.7)\n",
+    "ax.axvline(step_df[\"sl_\"].median(), color=\"black\", lw=2, label=\"Median\")\n",
+    "ax.axvline(step_df[\"sl_\"].mean(), color=\"black\", lw=2, ls=\"--\", label=\"Mean\")\n",
+    "ax.set_xlabel(\"Step length (m)\")\n",
+    "ax.set_ylabel(\"Count\")\n",
+    "ax.set_xlim(0, 2000)\n",
+    "ax.legend()\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Log of step lengths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Distribution of log step lengths, with the median and mean marked\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.hist(np.log(step_df[\"sl_\"]), bins=250, color=\"tab:blue\", alpha=0.7)\n",
+    "ax.axvline(np.log(step_df[\"sl_\"].median()), color=\"black\", lw=2, label=\"Median\")\n",
+    "ax.axvline(np.log(step_df[\"sl_\"].mean()), color=\"black\", lw=2, ls=\"--\", label=\"Mean\")\n",
+    "ax.set_xlabel(\"Log step length (m)\")\n",
+    "ax.set_ylabel(\"Count\")\n",
+    "ax.legend()\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step lengths through time"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Step length by hour of day, with the hourly median and mean overlaid\n",
+    "hourly_sl_median = step_df.groupby(step_df[\"hour_t1\"].round().mod(24))[\"sl_\"].median()\n",
+    "hourly_sl_mean = step_df.groupby(step_df[\"hour_t1\"].round().mod(24))[\"sl_\"].mean()\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.scatter(step_df[\"hour_t1\"], step_df[\"sl_\"], s=4, alpha=0.15, color=\"tab:blue\", label=\"Steps\")\n",
+    "ax.plot(hourly_sl_mean.index, hourly_sl_mean.values, color=\"red\", lw=2, marker=\"s\", ms=4, label=\"Hourly mean\")\n",
+    "ax.plot(hourly_sl_median.index, hourly_sl_median.values, color=\"black\", lw=2, marker=\"o\", ms=4, label=\"Hourly median\")\n",
+    "ax.set_xlabel(\"Hour of day\")\n",
+    "ax.set_ylabel(\"Step length (m)\")\n",
+    "ax.set_xticks(range(0, 25, 3))\n",
+    "ax.set_xlim(0, 24)\n",
+    "ax.set_ylim(0, 1000)\n",
+    "ax.legend()\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Distribution of turning angles"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Distribution of turning angles (NaN for each individual's first step, so dropped)\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.hist(step_df[\"ta_\"].dropna(), bins=72, range=(-np.pi, np.pi), color=\"tab:orange\", alpha=0.7)\n",
+    "ax.set_xlabel(\"Turning angle (radians)\")\n",
+    "ax.set_ylabel(\"Count\")\n",
+    "ax.set_xticks([-np.pi, -np.pi / 2, 0, np.pi / 2, np.pi])\n",
+    "ax.set_xticklabels([\"-π\", \"-π/2\", \"0\", \"π/2\", \"π\"])\n",
+    "ax.set_xlim(-np.pi, np.pi)\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Turning angles through time\n",
+    "\n",
+    "As turning angles are circular, the mean/median sit\n",
+    "near 0 regardless of spread. Instead, we summarise each hour with the circular SD \n",
+    "and the shortest arc containing 50% of the angles (which may wrap across ±π), i.e.,\n",
+    "where are the densest 50% of the turning angles concentrated?\n",
+    "\n",
+    "From this plot, we can see that movements are most directed (mean at 0 and most TAs\n",
+    "near 0) around dawn and dusk, reflecting the longer steps in those periods. \n",
+    "This shows that buffalo appear to be travelling in a directed way during those periods. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create a helper function to summarise turning angles by hour of day \n",
+    "# into circular SD and the shortest arc containing 50% of the angles\n",
+    "def circ_summary(theta, prob=0.5):\n",
+    "    \"\"\"Circular SD and the shortest arc containing `prob` of the angles.\"\"\"\n",
+    "    theta = np.sort(np.asarray(theta))\n",
+    "    n = len(theta)\n",
+    "    circ_sd = np.sqrt(-2 * np.log(np.abs(np.mean(np.exp(1j * theta)))))\n",
+    "    k = int(np.ceil(prob * n))\n",
+    "    ext = np.concatenate([theta, theta + 2 * np.pi])  # unwrap so arcs can cross ±π\n",
+    "    widths = ext[k - 1 : k - 1 + n] - ext[:n]\n",
+    "    i = np.argmin(widths)\n",
+    "    return pd.Series({\"circ_sd\": circ_sd, \"arc_start\": ext[i], \"arc_end\": ext[i + k - 1]})\n",
+    "\n",
+    "ta_df = step_df.dropna(subset=[\"ta_\"])\n",
+    "hourly_ta = ta_df.groupby(ta_df[\"hour_t1\"].round().mod(24))[\"ta_\"].apply(circ_summary).unstack()\n",
+    "\n",
+    "fig, (ax, ax_sd) = plt.subplots(2, 1, figsize=(8, 6), sharex=True, height_ratios=[3, 1])\n",
+    "ax.scatter(ta_df[\"hour_t1\"], ta_df[\"ta_\"], s=4, alpha=0.15, color=\"tab:orange\", label=\"Steps\")\n",
+    "for hour, row in hourly_ta.iterrows():\n",
+    "    # draw the arc as one segment, or two if it wraps past π\n",
+    "    segments = [(row.arc_start, min(row.arc_end, np.pi))]\n",
+    "    if row.arc_end > np.pi:\n",
+    "        segments.append((-np.pi, row.arc_end - 2 * np.pi))\n",
+    "    for lo, hi in segments:\n",
+    "        ax.vlines(hour, lo, hi, color=\"black\", lw=3, label=\"Densest 50%\" if hour == hourly_ta.index[0] and lo == row.arc_start else None)\n",
+    "ax.set_ylabel(\"Turning angle (radians)\")\n",
+    "ax.set_yticks([-np.pi, -np.pi / 2, 0, np.pi / 2, np.pi])\n",
+    "ax.set_yticklabels([\"-π\", \"-π/2\", \"0\", \"π/2\", \"π\"])\n",
+    "ax.set_ylim(-np.pi, np.pi)\n",
+    "ax.legend(loc=\"upper right\")\n",
+    "\n",
+    "ax_sd.plot(hourly_ta.index, hourly_ta[\"circ_sd\"], color=\"black\", lw=2, marker=\"o\", ms=4)\n",
+    "ax_sd.set_ylabel(\"Circular SD\")\n",
+    "ax_sd.set_xlabel(\"Hour of day\")\n",
+    "ax_sd.set_xticks(range(0, 25, 3))\n",
+    "ax_sd.set_xlim(0, 24)\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1552,17 +1742,29 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Where and when the simulations start.  Taking the time from the same observed\n",
-    "# step as the location keeps the two consistent — the diel and seasonal\n",
-    "# covariates then describe a moment the animal really was at that place.\n",
+    "# the starting id of the step (should be 1)\n",
     "START_IDX = 1\n",
+    "\n",
+    "# where should the simulation start?  \n",
+    "# here we use the first step in the observed data, but any valid (x, y) within the\n",
+    "# raster extent could be used. \n",
     "start_x = step_df[\"x1_\"].iloc[START_IDX]\n",
     "start_y = step_df[\"y1_\"].iloc[START_IDX]\n",
-    "START_YDAY = step_df[\"yday_t1\"].iloc[START_IDX]\n",
-    "START_HOUR = step_df[\"hour_t1\"].iloc[START_IDX]\n",
-    "step_interval = 1.0 # hours between simulated steps\n",
-    "print(f\"Starting location: ({start_x:.0f}, {start_y:.0f})\")\n",
-    "print(f\"Starting time    : day {START_YDAY:.0f}, {START_HOUR:.2f} h\")\n"
+    "print(f\"Starting location  : ({start_x:.0f}, {start_y:.0f})\")\n",
+    "\n",
+    "# the timestamp of the first step in the observed data\n",
+    "START_TIME = step_df[\"t1_\"].iloc[START_IDX]\n",
+    "# extract the day of year and hour of day as floats for the simulation inputs\n",
+    "START_YDAY = START_TIME.timetuple().tm_yday\n",
+    "START_HOUR = START_TIME.hour + START_TIME.minute / 60.0\n",
+    "\n",
+    "print(f\"Starting timestamp : {START_TIME}\")\n",
+    "print(f\"Starting time      : day {START_YDAY:.0f}, {START_HOUR:.2f} h\")\n",
+    "\n",
+    "# hours between simulated steps - this should ideally be the same as the observed step interval, \n",
+    "# but the model can be used to simulate at any interval\n",
+    "# (but it may not have learned a meaningful movement kernel for other intervals).\n",
+    "STEP_INTERVAL = 1.0 "
    ]
   },
   {
@@ -1595,6 +1797,8 @@
     "        - starting day-of-year \n",
     "    * `starting_hour`\n",
     "        - starting hour-of-day\n",
+    "    * `start_time`\n",
+    "        - what time should the simulation start\n",
     "    * `time_between_steps`\n",
     "        - time between steps in hours\n",
     "    * `window_size`\n",
@@ -1626,7 +1830,8 @@
     "    n_steps=1000,\n",
     "    starting_yday=START_YDAY,\n",
     "    starting_hour=START_HOUR,\n",
-    "    time_between_steps=step_interval,\n",
+    "    start_time=START_TIME,\n",
+    "    time_between_steps=STEP_INTERVAL,\n",
     "    window_size=WINDOW_SIZE,\n",
     "    month_index_fn=lambda _yday: 0,   # static layers\n",
     ")\n",
@@ -1752,6 +1957,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# set up a directory to hold the CSV files for the simulated trajectories\n",
     "TRAJ_DIR = OUTPUT_DIR / \"deepSSF_trajectories\"\n",
     "\n",
     "# save the simulated trajectory to a CSV file\n",
@@ -1802,6 +2008,7 @@
     "    method=\"batched\",\n",
     "    starting_yday=START_YDAY,\n",
     "    starting_hour=START_HOUR,\n",
+    "    start_time=START_TIME,\n",
     "    time_between_steps=1.0,\n",
     "    window_size=WINDOW_SIZE,\n",
     "    month_index_fn=lambda _yday: 0,   # static layers\n",
@@ -1855,6 +2062,7 @@
     "    method=\"batched\",\n",
     "    starting_yday=START_YDAY,\n",
     "    starting_hour=START_HOUR,\n",
+    "    start_time=START_TIME,\n",
     "    window_size=WINDOW_SIZE,\n",
     "    month_index_fn=lambda _yday: 0,\n",
     ")\n",
@@ -1883,6 +2091,26 @@
     "# save_trajectories(sim_many, TRAJ_DIR, prefix=\"deepSSF_pigs\", split=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### To read in previously saved trajectories"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# # to read previously run simulations from disk, rather than re-running the simulation above\n",
+    "# SIM_PATH = TRAJ_DIR / \"deepSSF_buffalo_scattered_1000traj_1000steps_2026-10-22.csv\"\n",
+    "# sim_scattered = pd.read_csv(SIM_PATH)\n",
+    "# print(f\"Read {len(sim_scattered):,} locations from {SIM_PATH}\")\n",
+    "# sim_scattered.head()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1960,6 +2188,220 @@
     "fmap_traj"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualise some data summaries of the simulated trajectories\n",
+    "\n",
+    "Here we can check the summaries of the observed data against summaries of the simulated trajectories,\n",
+    "to see whether we've captured those behaviours.\n",
+    "\n",
+    "### Calculate step lengths and turning angles from the simulated data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sim_scattered"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "step_df = deepssf.prepare_movement_df(\n",
+    "    sim_scattered, \n",
+    "    id_col=\"trajectory_id\", \n",
+    "    time_col=\"time\", \n",
+    "    x_col=\"x\", \n",
+    "    y_col=\"y\"\n",
+    ")\n",
+    "\n",
+    "n_dropped = len(raw_df) - len(step_df)\n",
+    "print(f\"Movement steps : {len(step_df):,}  ({n_dropped} dropped — last per individual)\")\n",
+    "step_df.head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Distribution of step lengths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Distribution of step lengths, with the median and mean marked\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "# observed step lengths\n",
+    "# ax.hist(step_df[\"sl_\"], bins=250, color=\"tab:blue\", alpha=0.7)\n",
+    "# ax.axvline(step_df[\"sl_\"].median(), color=\"black\", lw=2, label=\"Median\")\n",
+    "# ax.axvline(step_df[\"sl_\"].mean(), color=\"black\", lw=2, ls=\"--\", label=\"Mean\")\n",
+    "# simulated step lengths\n",
+    "ax.hist(sim_scattered[\"sl_\"], bins=250, color=\"tab:blue\", alpha=0.7)\n",
+    "ax.axvline(sim_scattered[\"sl_\"].median(), color=\"black\", lw=2, label=\"Median\")\n",
+    "ax.axvline(sim_scattered[\"sl_\"].mean(), color=\"black\", lw=2, ls=\"--\", label=\"Mean\")\n",
+    "ax.set_xlabel(\"Step length (m)\")\n",
+    "ax.set_ylabel(\"Count\")\n",
+    "ax.set_xlim(0, 2000)\n",
+    "ax.legend()\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Log of step lengths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Distribution of log step lengths, with the median and mean marked\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.hist(np.log(step_df[\"sl_\"]), bins=250, color=\"tab:blue\", alpha=0.7)\n",
+    "ax.axvline(np.log(step_df[\"sl_\"].median()), color=\"black\", lw=2, label=\"Median\")\n",
+    "ax.axvline(np.log(step_df[\"sl_\"].mean()), color=\"black\", lw=2, ls=\"--\", label=\"Mean\")\n",
+    "ax.set_xlabel(\"Log step length (m)\")\n",
+    "ax.set_ylabel(\"Count\")\n",
+    "ax.legend()\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Step lengths through time"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Step length by hour of day, with the hourly median and mean overlaid\n",
+    "hourly_sl_median = step_df.groupby(step_df[\"hour_t1\"].round().mod(24))[\"sl_\"].median()\n",
+    "hourly_sl_mean = step_df.groupby(step_df[\"hour_t1\"].round().mod(24))[\"sl_\"].mean()\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.scatter(step_df[\"hour_t1\"], step_df[\"sl_\"], s=4, alpha=0.15, color=\"tab:blue\", label=\"Steps\")\n",
+    "ax.plot(hourly_sl_mean.index, hourly_sl_mean.values, color=\"red\", lw=2, marker=\"s\", ms=4, label=\"Hourly mean\")\n",
+    "ax.plot(hourly_sl_median.index, hourly_sl_median.values, color=\"black\", lw=2, marker=\"o\", ms=4, label=\"Hourly median\")\n",
+    "ax.set_xlabel(\"Hour of day\")\n",
+    "ax.set_ylabel(\"Step length (m)\")\n",
+    "ax.set_xticks(range(0, 25, 3))\n",
+    "ax.set_xlim(0, 24)\n",
+    "ax.set_ylim(0, 1000)\n",
+    "ax.legend()\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Distribution of turning angles"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Distribution of turning angles (NaN for each individual's first step, so dropped)\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "ax.hist(step_df[\"ta_\"].dropna(), bins=72, range=(-np.pi, np.pi), color=\"tab:orange\", alpha=0.7)\n",
+    "ax.set_xlabel(\"Turning angle (radians)\")\n",
+    "ax.set_ylabel(\"Count\")\n",
+    "ax.set_xticks([-np.pi, -np.pi / 2, 0, np.pi / 2, np.pi])\n",
+    "ax.set_xticklabels([\"-π\", \"-π/2\", \"0\", \"π/2\", \"π\"])\n",
+    "ax.set_xlim(-np.pi, np.pi)\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Turning angles through time\n",
+    "\n",
+    "As turning angles are circular, the mean/median sit\n",
+    "near 0 regardless of spread. Instead, we summarise each hour with the circular SD \n",
+    "and the shortest arc containing 50% of the angles (which may wrap across ±π), i.e.,\n",
+    "where are the densest 50% of the turning angles concentrated?\n",
+    "\n",
+    "From this plot, we can see that movements are most directed (mean at 0 and most TAs\n",
+    "near 0) around dawn and dusk, reflecting the longer steps in those periods. \n",
+    "This shows that buffalo appear to be travelling in a directed way during those periods. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create a helper function to summarise turning angles by hour of day \n",
+    "# into circular SD and the shortest arc containing 50% of the angles\n",
+    "def circ_summary(theta, prob=0.5):\n",
+    "    \"\"\"Circular SD and the shortest arc containing `prob` of the angles.\"\"\"\n",
+    "    theta = np.sort(np.asarray(theta))\n",
+    "    n = len(theta)\n",
+    "    circ_sd = np.sqrt(-2 * np.log(np.abs(np.mean(np.exp(1j * theta)))))\n",
+    "    k = int(np.ceil(prob * n))\n",
+    "    ext = np.concatenate([theta, theta + 2 * np.pi])  # unwrap so arcs can cross ±π\n",
+    "    widths = ext[k - 1 : k - 1 + n] - ext[:n]\n",
+    "    i = np.argmin(widths)\n",
+    "    return pd.Series({\"circ_sd\": circ_sd, \"arc_start\": ext[i], \"arc_end\": ext[i + k - 1]})\n",
+    "\n",
+    "ta_df = step_df.dropna(subset=[\"ta_\"])\n",
+    "hourly_ta = ta_df.groupby(ta_df[\"hour_t1\"].round().mod(24))[\"ta_\"].apply(circ_summary).unstack()\n",
+    "\n",
+    "fig, (ax, ax_sd) = plt.subplots(2, 1, figsize=(8, 6), sharex=True, height_ratios=[3, 1])\n",
+    "ax.scatter(ta_df[\"hour_t1\"], ta_df[\"ta_\"], s=4, alpha=0.15, color=\"tab:orange\", label=\"Steps\")\n",
+    "for hour, row in hourly_ta.iterrows():\n",
+    "    # draw the arc as one segment, or two if it wraps past π\n",
+    "    segments = [(row.arc_start, min(row.arc_end, np.pi))]\n",
+    "    if row.arc_end > np.pi:\n",
+    "        segments.append((-np.pi, row.arc_end - 2 * np.pi))\n",
+    "    for lo, hi in segments:\n",
+    "        ax.vlines(hour, lo, hi, color=\"black\", lw=3, label=\"Densest 50%\" if hour == hourly_ta.index[0] and lo == row.arc_start else None)\n",
+    "ax.set_ylabel(\"Turning angle (radians)\")\n",
+    "ax.set_yticks([-np.pi, -np.pi / 2, 0, np.pi / 2, np.pi])\n",
+    "ax.set_yticklabels([\"-π\", \"-π/2\", \"0\", \"π/2\", \"π\"])\n",
+    "ax.set_ylim(-np.pi, np.pi)\n",
+    "ax.legend(loc=\"upper right\")\n",
+    "\n",
+    "ax_sd.plot(hourly_ta.index, hourly_ta[\"circ_sd\"], color=\"black\", lw=2, marker=\"o\", ms=4)\n",
+    "ax_sd.set_ylabel(\"Circular SD\")\n",
+    "ax_sd.set_xlabel(\"Hour of day\")\n",
+    "ax_sd.set_xticks(range(0, 25, 3))\n",
+    "ax_sd.set_xlim(0, 24)\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1991,19 +2433,6 @@
     "a layer that can be toggled on and off with `add_heatmap_overlay()`."
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# # to read previously run simulations from disk, rather than re-running the simulation above\n",
-    "# SIM_PATH = TRAJ_DIR / \"deepSSF_buffalo_scattered_100traj_1000steps_2026-10-22.csv\"\n",
-    "# sim_scattered = pd.read_csv(SIM_PATH)\n",
-    "# print(f\"Read {len(sim_scattered):,} locations from {SIM_PATH}\")\n",
-    "# sim_scattered.head()"
-   ]
-  },
   {
    "cell_type": "code",
    "execution_count": null,