deepSSF 0.2.3__tar.gz → 0.3.1__tar.gz

deepssf-0.3.1/CHANGELOG.md

@@ -0,0 +1,334 @@
+# Changelog
+
+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
+- **Configurable convolutional depth** — `ModelParams` now takes
+  `n_conv_layers_hab` and `n_conv_layers_move`, setting the depth of the two
+  sub-networks independently. The habitat count includes the final convolution
+  that projects to one output channel (so the minimum is 1), and since that
+  block does no pooling, extra layers only deepen the features and widen the
+  receptive field. The movement count is the number of conv → ReLU → max-pool
+  blocks, so it also controls how far the window is reduced before the
+  fully-connected layers. Both keys are optional and default to the paper
+  architecture (4 and 3), so existing params dicts and checkpoints are
+  unaffected — but note that a checkpoint only loads into a model with the same
+  layer counts it was trained with.
+- **`deepssf.model.flattened_conv_dim`** — compute the flattened size of the
+  movement CNN's output, i.e. the value `dense_dim_in_all` must be set to. It
+  changes with `n_conv_layers_move` (every layer pools), so it can no longer be
+  worked out once and hard-coded. It is derived arithmetically rather than by a
+  dummy forward pass, because the answer is needed *before* `ModelParams` is
+  built, and it raises if the stack would pool the window away to nothing
+  instead of failing later inside `MaxPool2d`.
+- **`deepssf.simulate.trajectory_heatmap`** — count simulated locations per cell
+  to give a space-use surface for a simulation. `burn_in` discards the first *n*
+  steps of every trajectory, which otherwise pile up around the release site(s)
+  and describe the starting conditions more than the fitted model; `agg`
+  aggregates *agg* x *agg* raster pixels into one heatmap cell, since at a
+  typical 20 m resolution the counts are spread so thinly that nearly every
+  occupied cell holds a single location. The returned transform keeps the
+  landscape rasters' origin, so the heatmap stays aligned with the layers it was
+  simulated on. Locations that walked off the landscape are dropped and reported.
+- **`deepssf.data.save_raster`** — write a 2-D or 3-D array to a GeoTIFF with a
+  transform, CRS, nodata value and band descriptions, so anything derived from
+  the landscape (a habitat selection surface, a simulation heatmap) opens in
+  QGIS/ArcGIS on top of the layers it came from. `int64` is narrowed to `int32`,
+  which GeoTIFF supports and `int64` does not.
+- **`deepssf.plot.add_heatmap_overlay`** — add a heatmap raster to an existing
+  folium map as its own toggleable layer, log-scaled by default and fully
+  transparent below `vmin` so unvisited cells do not grey out the basemap.
+  Composes with `plot_trajectories_folium`: that function builds its layer
+  control before returning, but folium collects layers at render time, so an
+  overlay added afterwards still gets a checkbox. The counts are warped to
+  EPSG:3857 with rasterio and handed to folium as a **uint8** image rather than
+  using `mercator_project`: folium's own re-projection interpolates the RGBA
+  image and returns float64, which `write_png` then rescales channel by channel
+  — stretching the colours and flattening the alpha channel to fully opaque.
+- **`deepssf.predict.predict_habitat_landscape`** — run the trained habitat
+  filters over an entire raster in one pass, giving a landscape-scale habitat
+  selection surface. The habitat sub-network is fully convolutional (3x3
+  convolutions, stride 1, padding 1, no pooling or dense layer), so it is
+  translation-equivariant: a pixel's value is exactly what the model would
+  produce for a window centred on it. The scalar covariates are broadcast to
+  full-landscape layers, since `Scalar_to_Grid_Block`'s output size is pinned to
+  the training window. Processing is chunked by rows with an `edge_buffer`
+  overlap — bit-identical to a single pass, but without the several-hundred-MB
+  activations that can exhaust a GPU. `habitat_edge_buffer` reports the exact
+  border width that zero-padding contaminates (1 px per conv layer, so 4), which
+  is masked to NaN rather than the -inf earlier scripts multiplied through.
+- **Checkpoints record the architecture they were trained with** — a checkpoint
+  written from a `ConvJointModel` now carries a `model_params` key holding
+  `ModelParams.to_dict()`, alongside the weights. Weights only load into a model
+  built with the *same* architecture, so predicting from a saved model
+  previously meant re-typing every hyper-parameter into the prediction script,
+  where a habitat branch one layer too shallow fails loudly but a mis-set
+  `pixel_size` quietly rescales the movement kernel. The key is optional rather
+  than a checkpoint-format bump: format-2 readers ignore what they do not know,
+  and files written before it existed still load.
+- **`deepssf.train.params_from_checkpoint`** — rebuild the `ModelParams` a
+  checkpoint was trained with, ready to pass to `ConvJointModel`. Reads
+  `model_params` where present, and otherwise recovers the architecture from the
+  layer shapes themselves — a conv weight is `[out_channels, in_channels, k, k]`
+  and a linear weight `[out_features, in_features]`, which between them pin down
+  every hyper-parameter that changes a tensor shape. Either way the result is
+  cross-checked against the saved tensors, so a params dict that contradicts the
+  weights it sits beside raises instead of failing later at `load_state_dict`.
+  `image_dim` and `pixel_size` leave no trace in the weights and must be given
+  for a checkpoint that has no stored params; `image_dim` is then validated
+  against the flattened size the movement MLP expects, which pins it to within
+  the slack that max-pooling's floor division allows. `device` deliberately
+  defaults to this machine rather than to whatever the model was trained on.
+- **`ModelParams.to_dict()`** — a plain-Python copy of the hyper-parameters that
+  round-trips through `ModelParams(...)`. Values are coerced to built-in types
+  (a `torch.device` or NumPy scalar becomes a `str` or `float`) because
+  checkpoints are read back with `torch.load(weights_only=True)`, which accepts
+  tensors and built-in containers only. `ModelParams.FIELDS` lists the fields, so
+  a new hyper-parameter reaches checkpoints as soon as it is added there.
+- **`EarlyStopping(checkpoint_on=...)`** and **`EarlyStopping(head_paths=...)`**
+  — see *Fixed* below.
+- **`load_head_weights`** — copy just one head's weights out of a checkpoint,
+  leaving the other head untouched. `HEAD_MODULE_PREFIXES` records the
+  module-to-head mapping, mirroring the split `set_trainable` freezes on.
+- **`simulate_trajectories`** — simulate many trajectories in one call, returning
+  them stacked in a long-format DataFrame with `trajectory_id` and `step`
+  columns. Three methods: `"batched"` (the default), `"sequential"` (a plain loop
+  over `simulate_trajectory`) and `"parallel"` (that loop over a thread pool).
+- **`simulate_trajectories_batched`** — steps every trajectory together so the
+  model sees a batch of windows per forward pass instead of one. Measured on an
+  Apple M-series GPU at `window_size=75`, 200 steps: 2.2× faster than the
+  sequential loop at 4 trajectories, 6.9× at 16 and 34× at 64, since the cost per
+  step is nearly flat in the number of trajectories. Window extraction is a
+  single advanced-indexing gather over a landscape padded once per month, and
+  sampling uses `torch.multinomial` over the whole batch. The trade-off is a
+  shared clock: `starting_yday`/`starting_hour` must be scalars (start
+  *locations* may still vary per trajectory).
+  Note that the sub-pixel jitter is scaled from the raster resolution implied by
+  the transform, whereas `simulate_next_step` hard-codes a 25 m cell — so batched
+  and sequential runs differ slightly on rasters of any other resolution.
+- **`save_trajectories`** — write simulated trajectories to CSV under a name that
+  records trajectory count, step count and date, appending a run counter rather
+  than ever overwriting an existing file. `split=True` writes one file per
+  trajectory.
+- **`deepssf.plot.plot_trajectories_folium`** — draw simulated and observed
+  trajectories over a satellite (or topographic/OSM) basemap, reprojecting from
+  the data's projected CRS to EPSG:4326 via `rasterio.warp` (no pyproj axis-order
+  trap). Each trajectory is its own toggleable layer. `folium` is an optional
+  dependency: `pip install "deepSSF[maps]"`.
+
+### Fixed
+- **DataLoaders fail with `affine` 3.x** — `MovementDataset` items carried the
+  raster's `Affine` transform as their fifth element, and since `affine` 3.0
+  `Affine` is no longer a tuple, so PyTorch's `default_collate` raised a
+  `TypeError` on the first batch. The fifth element is now a `[6]` float64
+  tensor of the transform's coefficients `(a, b, c, d, e, f)`, which batches on
+  any `affine` version; rebuild the transform with `Affine(*coeffs.tolist())`,
+  or use `dataset.raster_transform`. The training and validation loops ignore
+  this element, so they are unaffected.
+- **Sub-pixel jitter was hard-coded to a 25 m cell.** `simulate_next_step`
+  scattered each sampled location by a truncated normal on [0, 25] m regardless
+  of the raster's actual resolution. On a 20 m raster that put up to 1.25 cells
+  of noise on every simulated step and pushed locations outside the cell the
+  model had sampled; on a 100 m raster it never left the first quarter of the
+  cell. The cell size now comes from the transform, which is the authority on
+  the grid the model was trained against. **Simulated trajectories will differ
+  from previous versions on any raster that is not 25 m.**
+- **A habitat-only training stage saved the wrong epoch.** The combined loss is
+  `habitat + movement + logZ`, and `logZ = logsumexp(habitat + movement)` — the
+  overlap between the habitat surface and the movement kernel — moves with the
+  habitat weights. The combined loss and the habitat loss are the same
+  used-versus-available contrast measured against different availability sets:
+  the combined loss scores habitat against the cells within reach (~109 effective
+  cells of a 75x75 window on a feral-pig model), the habitat loss against the
+  whole window (~5460). So with movement frozen the combined loss can keep
+  falling — habitat discriminating better among near neighbours — while the
+  density it gives the observed location gets *worse*. Since checkpointing keyed
+  on the combined loss unconditionally, every epoch of such a stage looked like an
+  improvement and overwrote the checkpoint, ending on a habitat surface well past
+  its best — in one feral-pig run, habitat bottomed out at epoch 12 of a 10-epoch
+  stage and then gave back three quarters of what it had learned while the
+  combined loss kept falling.
+  `EarlyStopping(checkpoint_on='active')` now keys the checkpoint on whichever
+  head is training during a single-head stage, falling back to the combined loss
+  when both are; `head_paths=` additionally keeps each head's own best epoch in
+  its own file. The default remains `'total'` — for the finished *joint* model,
+  and for a habitat surface intended as a *selection* map, that is still the
+  right criterion; `'active'` is mainly a diagnostic for whether the habitat head
+  is learning at all. `negativeLogLikeLoss`'s docstring now spells out what `logZ`
+  is, gives the gradients of both criteria, and notes that neither is a spatial
+  operation — the habitat CNN has no positional input and is
+  translation-equivariant, so the difference between them is entirely in which
+  covariate values enter the available side of the contrast.
+- **Environmental layers were not scaled to [0, 1].** `load_environmental_layers`
+  divided by the maximum rather than the range — `(data - lo) / hi` instead of
+  `(data - lo) / (hi - lo)` — which only lands in [0, 1] when the minimum happens
+  to be zero. Sentinel-2 indices stored as ×10 000 (`lo=-10000, hi=10000`) came
+  out in [0, 2]; an all-negative layer came out negative *and* axis-flipped,
+  reversing the sign of everything the habitat CNN learned from it; a layer with
+  `hi == 0` divided by zero. A constant layer now maps to a flat 0 instead of
+  raising. **Checkpoints trained on the old scaling will not transfer** — the
+  inputs have changed, so retrain.
+- **`conv_movement` was registered with no optimiser.** `make_optimisers` covered
+  only `fcn_movement_all` and `conv_habitat`, so the movement CNN trunk received
+  gradients on every `backward()` but was never zeroed and never stepped. Its
+  `.grad` accumulated monotonically across the whole run: the trunk stayed at its
+  random initialisation, and once the buffer overflowed `_grads_are_finite` —
+  which iterates over every parameter — began returning `False`, silently
+  skipping *every* subsequent update, habitat's included. `conv_movement` now
+  sits in the movement optimiser alongside `fcn_movement_all`.
+- `train_loop` zeroes gradients with `model.zero_grad(set_to_none=True)` rather
+  than per-optimiser, so no parameter can be left out of the reset however the
+  optimisers are configured. The manual stash-and-restore of habitat gradients
+  around the two optimiser steps has been removed: the optimisers own disjoint
+  parameter sets and `Adam.step()` only reads `.grad` for its own parameters, so
+  it was a no-op.
+- **Both learning-rate schedulers stepped on the combined validation loss.** That
+  loss is `habitat + movement + logZ` and is dominated by the movement component
+  (~1.2 nats of movement against ~0.05 of habitat over a typical run), so the
+  habitat learning rate was being cut whenever the *movement* head plateaued.
+  Each scheduler now steps on its own component, and only while that component is
+  training — stepping a frozen head's scheduler would penalise it for an
+  improvement it was never given the chance to make.
+- **NaN movement probability surfaces during training.** In float32 the von
+  Mises normaliser `I₀(κ)` overflows to `inf` at κ ≈ 89 — reachable from a raw
+  FCN output of only `log(89) ≈ 4.5`. With both mixture components overflowing,
+  the log-sum-exp evaluated `-inf - (-inf)` and the entire surface became NaN;
+  with only one overflowing, the forward pass stayed finite but produced NaN
+  gradients that silently propagated into every weight on the next optimiser
+  step. `Params_to_Grid_Block._vonmises_log` now uses the exponentially-scaled
+  Bessel function, `log I₀(κ) = κ + log(i0e(κ))`, giving
+  `κ·(cos(θ-μ) - 1) - log(2π) - log(i0e(κ))`, whose exponent is ≤ 0 for every κ.
+- Mixture components are combined with `torch.logsumexp` instead of a manual
+  max/exp/log, which returned NaN when both components were `-inf`.
+- Raw FCN outputs are clamped (`Params_to_Grid_Block.raw_clamp`, default 10.0)
+  before exponentiation. Previously `exp` overflowed to `inf` at a raw value of
+  ≈ 88, making `lgamma(inf) - inf` NaN, and scale underflowed to 0 at ≈ -88.
+- `torch.special.i0e` is called on the active device. The previous `.cpu()`
+  round-trip for MPS forced a host sync on every forward pass; `i0`/`i0e` now
+  have CPU, CUDA and MPS kernels registered (verified on torch 2.12).
+- `distance_layer` and `bearing_layer` are registered buffers, so `model.to()`
+  moves them once instead of copying them host→device on every forward pass.
+  They use `persistent=False`: both are constants derived from `image_dim` and
+  `pixel_size`, so they stay out of `state_dict` and checkpoint keys are
+  unchanged.
+- `train_loop` skips batches whose loss or gradients are not finite rather than
+  stepping the optimiser on them, and excludes them from the epoch mean. A
+  single bad batch no longer makes a run unrecoverable.
+- The epoch mean is now averaged over contributing batches, not `num_batches`.
+- Corrected the `Params_to_Grid_Block_ChV` docstring: it subtracts `log(r)` from
+  the log-density (dividing the density by `r`), not "by `log(r)`".
+
+### Changed
+- **Breaking:** `skip_epoch0_training` has been removed from `train_loop`. It had
+  no epoch awareness — it was a per-call switch that `fit` never passed, so its
+  default applied to *every* epoch, and with that default at `True` an entire run
+  executed forward-only under `torch.set_grad_enabled(False)`. It also measured a
+  training-set baseline when the useful number is a validation one. `fit` now runs
+  one validation pass before the first epoch and records it at index 0 of every
+  history list, with `train_losses[0] = nan`.
+- `history` gains a `stage` key recording which stage each epoch belonged to
+  (`-1` for the pre-training baseline row).
+- **Breaking (checkpoints):** mixture weights are now `log_softmax` over the raw
+  FCN outputs. Previously `softmax(exp(raw))` was applied — a double exponential
+  that saturated to exactly `(1, 0)` by a raw value of ≈ 4.75, zeroing the weight
+  gradient and putting `log(0) = -inf` into the surface. Movement parameters
+  2, 5, 8 and 11 therefore have a different meaning, so checkpoints written by
+  ≤ 0.2.3 will be reinterpreted rather than failing to load. The step-length and
+  turning-angle densities themselves are unchanged (agreement to ~6e-6 when the
+  two weights are equal).
+- `negativeLogLikeLoss` raises a `RuntimeWarning` once per non-finite surface
+  instead of printing on every batch, and performs one device sync per batch
+  rather than three.
+- `_expand` uses `expand` rather than `repeat`, returning a view instead of
+  materialising a `[B, H, W]` copy per parameter.
+
+## [0.2.3] - 2026-05-31  
+
+### Added
+- **`EarlyStopping(monitor='both')`.** Keeps a separate patience budget for the
+  habitat and movement components and stops only once every active component has
+  plateaued, so a converged movement head can no longer end a run in which habitat
+  is still improving. Checkpointing still keys on the combined loss — the joint
+  likelihood remains the right model-selection criterion; only the stopping rule
+  changes. `reset()` clears the counters at stage boundaries while leaving the
+  best score and saved checkpoint intact.
+- **`fit(stages=...)`** runs the sub-networks as a coordinate ascent on the same
+  joint likelihood, e.g. movement alone to establish an availability kernel, then
+  habitat alone to its own convergence, then both. A frozen branch keeps
+  contributing its surface to the loss as a fixed offset; only its weights stop
+  moving, so the objective is unchanged rather than reweighted. This is not what
+  `negativeLogLikeLoss(freeze_movement=True)` does — that flag *drops* the movement
+  surface from the loss, which would make the habitat head learn a distance-decay
+  bump in order to explain the movement structure itself. Early stopping ends the
+  current stage and advances to the next. `reset_optimiser_state` (default `True`)
+  clears the Adam moments of a branch when it becomes active again.
+- `set_trainable(model, *, habitat, movement)` toggles `requires_grad` per
+  sub-network. Exported from the package root.
+- See `Habitat_movement_loss_balancing.md` for why the fix for the
+  habitat/movement asymmetry is a monitoring change rather than a loss weight.
+- **Versioned checkpoints.** `EarlyStopping` now writes a dict with
+  `deepssf_checkpoint_format`, `deepssf_version`, `val_loss` and `state_dict`
+  keys instead of a bare `state_dict` (`CHECKPOINT_FORMAT = 2`). Because the
+  `state_dict` keys themselves did not change, a pre-0.3.0 file would otherwise
+  load without error while silently misreading movement parameters 2, 5, 8
+  and 11 — the marker makes that case fail loudly.
+- `load_checkpoint(path, model=None, *, map_location=None, allow_legacy=False,
+  strict=True)` reads a checkpoint, verifies its format, and optionally loads it
+  into a model. Legacy (format 1) files raise `RuntimeError` unless
+  `allow_legacy=True`; files from a future format are refused with an
+  upgrade message. Exported from the package root alongside `CHECKPOINT_FORMAT`.
+- `grad_clip` argument on `fit` and `train_loop` for global gradient-norm
+  clipping (`None` by default, so existing behaviour is unchanged).
+- Regression tests covering forward and backward finiteness at extreme movement
+  parameters, log-normalisation of the surface, and non-vanishing mixture-weight
+  gradients.
+- Initial package scaffold.

{deepssf-0.2.3 → 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.1/Habitat_movement_loss_balancing.md

@@ -0,0 +1,237 @@
+# Balancing the habitat and movement components of the deepSSF loss
+
+A design record for the training changes introduced after 0.3.0. It explains why
+the habitat sub-network appeared not to learn, why the fix is not a loss weight,
+and what the `stages` / `monitor="both"` machinery is for.
+
+## The symptom
+
+In a joint model trained on feral pig GPS data, the movement component of the
+validation loss fell by roughly 1.2 nats over a run while the habitat component
+moved by about 0.05 and sometimes drifted upward. On a 75×75 window a uniform
+surface scores `log(75 × 75) = 8.635` nats; the habitat head finished at ≈ 8.25,
+i.e. it had extracted about 0.4 nats of structure in total. Scoring the observed
+next step on held-out data told the same story: mean habitat probability 0.000206
+against a uniform 1/5625 = 0.000178, versus a mean movement probability of 0.054.
+
+The natural reading is that the two components are summed into one loss and the
+larger one drowns out the smaller, so the fix must be a weight on the habitat
+term. That reading is wrong in an instructive way.
+
+## What the loss actually is
+
+`ConvJointModel` returns a `[B, H, W, 2]` stack in which **both** slices are
+already log-normalised over the window — the habitat head subtracts its own
+`logsumexp` (`Conv2d_block_spatial.forward`), and so does the movement head
+(`Params_to_Grid_Block.forward`). `negativeLogLikeLoss` then sums them and
+renormalises the sum:
+
+```python
+pred_prod = hab_surface + move_surface
+pred_prod = pred_prod - torch.logsumexp(pred_prod, dim=(1, 2), keepdim=True)
+nll = -pred_prod[batch_idx, py2, px2]
+```
+
+The `habitat_loss` and `movement_loss` it also returns are **diagnostics**:
+`train_loop` and `test_loop` discard them (`total_loss, _, _ = loss_fn(...)`), and
+only the epoch summary in `fit` reports them. There is no weighted sum anywhere,
+and therefore no λ to turn.
+
+Because both surfaces arrive normalised, the total decomposes exactly:
+
+```
+total = habitat_nll + movement_nll + logZ,    logZ = logsumexp(hab + mov) ≤ 0
+```
+
+So the *magnitudes* really are dominated by movement. But the gradient tells a
+different story. Differentiating the total with respect to the habitat
+parameters gives
+
+```
+∂total/∂θ_hab = -∇hab(y) + E_{p_combined}[∇hab]
+```
+
+— the standard conditional-logistic form: observed minus its expectation under
+the combined surface. That is exactly the right step-selection gradient, with the
+movement kernel playing the role of the availability distribution. **The habitat
+head was never starved of gradient.** Adam normalises by gradient RMS on top of
+that, so the raw scale difference between the components does not translate into
+a proportional difference in step size either.
+
+### Why weighting the habitat term would be wrong
+
+The obvious intervention — minimise `total + λ · habitat_nll` — has a specific
+failure mode. `habitat_nll` is the NLL of the habitat surface *on its own*, over
+the whole window, and it is minimised by putting probability mass where animals
+actually end up, which is overwhelmingly near the centre pixel. A habitat head
+trained against it learns a distance-decay bump centred on the previous location:
+it absorbs the movement structure instead of describing resource selection. The
+same objection applies to `negativeLogLikeLoss(freeze_movement=True)`, which drops
+the movement surface from the combined loss entirely — despite its name, it is not
+a way to hold movement fixed while habitat trains. **Do not use it for that.**
+
+## Where the asymmetry actually bites: model selection
+
+The damage is downstream of the gradient. Before this change, both
+`ReduceLROnPlateau` schedulers and `EarlyStopping` stepped on the combined
+validation loss. Since that loss moves ~1.2 nats on movement and ~0.05 on
+habitat, habitat's genuine improvement sits *inside* movement's epoch-to-epoch
+noise band. The consequences:
+
+- The run early-stops on movement's schedule. Habitat is still improving, but the
+  combined loss has stopped moving by more than noise, so the patience counter
+  climbs and training ends.
+- The habitat learning rate is cut when the *movement* head plateaus.
+
+Neither is fixed by changing the objective. Both are fixed by changing what is
+monitored.
+
+## Two bugs found alongside it
+
+Neither is about loss balance, but no balancing scheme could be evaluated while
+they stood.
+
+**`conv_movement` belonged to no optimiser.** `make_optimisers` registered only
+`fcn_movement_all` and `conv_habitat`. The movement CNN trunk received gradients
+on every `backward()` but was never zeroed and never stepped, so its `.grad`
+accumulated monotonically across the entire run. Two consequences: the trunk
+stayed at its random initialisation forever, so the movement head was reading
+fixed random features; and once the accumulating buffer overflowed,
+`_grads_are_finite(model)` — which iterates over *every* parameter — began
+returning `False`, at which point **every** subsequent update was silently
+skipped, habitat's included, with only a `non-finite gradients at batch N`
+warning to show for it.
+
+**`skip_epoch0_training` disabled training.** The flag had no epoch awareness: it
+was a per-call switch, and `fit` never passed it, so whatever its default was
+applied to every epoch. With the default at `True`, the entire run executed
+forward-only under `torch.set_grad_enabled(False)`. It also measured a
+*training-set* baseline, when the number worth having is a validation one.
+
+## The changes
+
+### 1. Correct parameter ownership
+
+`make_optimisers` now puts `conv_movement` and `fcn_movement_all` in the movement
+optimiser as two param groups. `train_loop` zeroes gradients with
+`model.zero_grad(set_to_none=True)` rather than per-optimiser, so no parameter can
+fall outside the reset regardless of how the optimisers are configured.
+
+The manual stash-and-restore of habitat gradients that used to bracket the two
+optimiser steps has been deleted. The two optimisers own disjoint parameter sets
+and `Adam.step()` only reads `.grad` for its own parameters, so clearing habitat
+gradients before the movement step and putting them back afterwards was a no-op.
+
+A regression test asserts that every parameter in `model.parameters()` is owned by
+exactly one optimiser.
+
+### 2. Per-head monitoring
+
+Each `ReduceLROnPlateau` now steps on its own component of the validation loss,
+and only while that component is training — stepping a frozen head's scheduler
+would cut its learning rate for a lack of improvement it was never given the
+chance to make.
+
+`EarlyStopping` gains `monitor="both"`, which keeps a separate patience budget per
+component and stops only once *every active* component has plateaued. Checkpointing
+is deliberately unchanged: it still keys on the combined validation loss, because
+the joint likelihood remains the correct model-selection criterion. Only the
+stopping rule changes. `reset()` clears the counters at stage boundaries while
+leaving the best score and saved checkpoint intact.
+
+Note that with `delta=0.0` an exactly-unchanged loss counts as an improvement.
+This is pre-existing behaviour, retained; real losses fluctuate, so a genuine
+plateau still accumulates patience.
+
+### 3. Staged (coordinate) training
+
+`fit(stages=[...])` runs the sub-networks in turn:
+
+```python
+stages=[
+    {"epochs": 10, "train": ("movement",)},
+    {"epochs": 40, "train": ("habitat",)},
+    {"epochs": 20, "train": ("habitat", "movement")},
+]
+```
+
+Movement goes first so that a sensible availability kernel is in place before
+habitat is fitted conditional on it. Habitat then runs to its own convergence on
+its own early-stopping clock. A joint stage settles both.
+
+A frozen branch is frozen through `set_trainable` (`requires_grad=False`) *and* by
+withholding its optimiser. Crucially, **its surface stays in the likelihood as a
+fixed offset** — only its weights stop moving. That is what makes this coordinate
+ascent on the true joint objective rather than a reweighting of it, and it is the
+difference between this mechanism and `freeze_movement=True`.
+
+`reset_optimiser_state` (default `True`) clears the Adam moments of a branch when
+it becomes active in a new stage, so a head frozen for forty epochs does not
+resume on momentum pointing in a long-outdated direction.
+
+Early stopping ends the current *stage* and advances to the next; for the final
+stage that ends the run, so the behaviour is uniform.
+
+### 4. A pre-training baseline
+
+`skip_epoch0_training` is removed. `fit` instead runs one validation pass before
+the first epoch and records it at index 0 of every history list, with
+`train_losses[0] = nan` and `stage[0] = -1`. An untrained habitat surface is
+uniform, so the baseline should land near `log(H × W)`; the gap between that and
+the final `val_habitat_losses` is a direct, unambiguous read on how much the
+habitat head actually learned. `history` also gains a `stage` key recording which
+stage each epoch belonged to.
+
+## Verifying it on a run
+
+- The baseline line should print before epoch 1 with `hab ≈ log(H × W)`.
+- No `non-finite gradients at batch N` warnings should appear — those were the
+  signature of the accumulating `conv_movement` gradients.
+- In a movement-only stage `val_habitat_losses` must be exactly flat, and in a
+  habitat-only stage `val_movement_losses` must be exactly flat. If either moves,
+  the freeze is not working.
+- `val_habitat_losses` should fall materially below `log(H × W)` and flatten
+  *before* the run ends, rather than the run ending first.
+
+### 5. Correct covariate scaling
+
+Found while investigating the flat habitat surface and fixed alongside it, since
+it feeds the habitat CNN directly. `load_environmental_layers` divided by the
+maximum rather than the range:
+
+```python
+data = (data - lo) / hi          # only correct when lo == 0
+```
+
+The failure is sign-dependent, which is why it went unnoticed:
+
+| layer range | old result | correct |
+|---|---|---|
+| `lo=0, hi=100` | `[0, 1]` | `[0, 1]` — right by accident |
+| `lo=-10000, hi=10000` (S2 indices ×10 000) | `[0, 2]` | `[0, 1]` |
+| `lo=-100, hi=-10` (all negative) | `[0, -9]` — negative *and* axis-flipped | `[0, 1]` |
+| `hi = 0` | `ZeroDivisionError` | `[0, 1]` |
+
+The axis flip is the serious one: it reverses the sign of everything the habitat
+CNN learns from that layer. The denominator is now `hi - lo`, with a constant
+layer mapping to a flat 0 rather than dividing by zero.
+
+Out-of-window padding stays at `-1.0`. With inputs correctly in `[0, 1]` that is
+one full data range below the minimum, so padding remains cleanly distinguishable
+from real values — which is what `image_trim_pixels` exists to keep out of the
+snapshot visualisations.
+
+**Checkpoints trained on the old scaling will not transfer.** The inputs have
+changed; retrain.
+
+## Still open
+
+Found while investigating this, not addressed by it.
+
+- **Habitat capacity.** Four conv layers at `output_channels=4` is ~27k parameters
+  for the entire model, which may simply be too little to express much spatial
+  structure. Worth revisiting now that the scaling is right and the training
+  dynamics are trustworthy.
+- **Per-band vs joint scaling.** A multi-band TIFF is scaled by its global min and
+  max, so relative magnitudes between bands survive. That is right for bands
+  sharing a natural range (NDVI/NDWI/NDMI) and wrong for bands in unrelated units.

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: deepSSF
-Version: 0.2.3
+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
@@ -35,6 +35,8 @@ Requires-Dist: twine>=5.0; extra == 'dev'
 Provides-Extra: examples
 Requires-Dist: ipykernel>=6.0; extra == 'examples'
 Requires-Dist: jupyterlab>=4.0; extra == 'examples'
+Provides-Extra: maps
+Requires-Dist: folium>=0.15; extra == 'maps'
 Description-Content-Type: text/markdown
 
 # deepSSF