Fix diagnostic report render

.Rbuildignore

@@ -12,3 +12,4 @@
 ^LICENSE\.md$
 ^README\.Rmd$
 ^GeoTwilightR\.Rproj$
+^codemeta\.json$

AGENTS.md

@@ -23,6 +23,7 @@
 
 ## Performance
 
+- Performance is a priority.
 - Prefer vectorised operations, matrix or array operations, `rowSums`, `colSums`, `sweep`, `%*%`, and `outer` where they fit.
 - Prefer efficient primitives over `apply()` when possible. Use `apply()` or `Map()` only when they remain clear and appropriate.
 - Avoid unnecessary copies, repeated computation, and hidden coercions.
@@ -55,6 +56,20 @@
 - Preserve numerical behaviour unless there is a clear risk such as `log(0)`, division by zero, or unstable normalisation.
 - When adding a numerical safeguard, keep it minimal and explain why it is needed.
 
+## Error handling
+
+- Do not introduce `tryCatch()` or defensive error handling.
+- Let errors occur naturally unless they are handled at a public entry point.
+
+## Silent failure risks
+
+Intervene only when there is a clear risk of unintended recycling, dimension dropping, implicit coercion, or invalid numerical operations. Otherwise, assume correct usage.
+
+## Rewriting vs patching
+
+- Default to a minimal patch.
+- If code is clearly inconsistent, inefficient, or unclear, rewriting the function is allowed, but explicitly warn the user.
+
 ## Output invariants
 
 Edits must preserve classes, dimensions, ordering, column names, and attributes. Do not silently change them. Explain any necessary trade-off before making it.
@@ -70,6 +85,13 @@ Edits must preserve classes, dimensions, ordering, column names, and attributes.
 - Do not add or modify tests, roxygen documentation, README files, or vignettes unless requested.
 - Match validation to the change: source changed functions, run focused tests, and avoid long analyses unless needed.
 
+## Generated files
+
+- Edit roxygen comments in `R/`, never `man/*.Rd` or `NAMESPACE`; run `roxygen2::roxygenise()` and commit the regenerated files.
+- Edit `README.Rmd`, never `README.md`; run `devtools::build_readme()` and commit both.
+- After editing the vignette or documentation, rebuild with `pkgdown::build_site()` or render the vignette to confirm it runs.
+- Keep the software title, version, and DOI consistent across `DESCRIPTION`, `CITATION.cff`, `inst/CITATION`, `codemeta.json`, and `README.Rmd`.
+
 ## Mandatory CI checks
 
 Before committing or pushing agent-made changes, run from the repository root:
@@ -81,6 +103,46 @@ air format . --check
 
 Both commands must pass without warnings or errors introduced by the changes. If formatting fails, run `air format .`, review the resulting changes, and rerun both checks. Never defer failures to CI.
 
+## Development, PR, and release workflow
+
+### Branch flow
+
+- Develop on `dev`: make focused commits, run the mandatory checks, and push to `origin/dev`.
+- Open a pull request from `dev` to `main`. Merge `main` into `dev` and resolve conflicts before the PR is merged.
+- Use a draft PR while release metadata or release checks are incomplete. Mark it ready only when the final package version, NEWS entry, and required GitHub checks are complete.
+
+### One canonical release block
+
+- For every release, write one Markdown release block first. It is the source of truth and must be copied **verbatim** to:
+  1. the new top section of `NEWS.md`;
+  2. the pull-request body; and
+  3. the GitHub Release body created for the version tag.
+- Do not shorten, paraphrase, reorder, or add items independently in any of those three places.
+- Use the release version as the PR title (for example, `v0.2.0`) and as the top NEWS heading.
+- Keep the heading, subsection headings, bullet text, Markdown links, and the full-changelog comparison link identical in all three copies.
+
+```md
+# GeoPathSampleR vX.Y.Z
+
+## Main
+
+- [Describe the principal user-facing change](https://github.com/GeoPressure/GeoPathSampleR/commit/<sha>).
+
+## Minor
+
+- [Describe a smaller change or fix](https://github.com/GeoPressure/GeoPathSampleR/commit/<sha>).
+
+**Full Changelog**: <https://github.com/GeoPressure/GeoPathSampleR/compare/vX.Y.(Z-1)...vX.Y.Z>
+```
+
+### Release checklist
+
+- Set `DESCRIPTION`, `CITATION.cff`, and `codemeta.json` to the final `X.Y.Z` version; do not merge a release with `.9000`.
+- Run `cffr::cff_write()` after finalizing `DESCRIPTION`, then review and commit the generated `CITATION.cff` changes. Run `codemetar::write_codemeta()` to update `codemeta.json`.
+- Add the canonical release block to `NEWS.md` before opening the PR, then paste that exact block into the PR body.
+- Resolve all `R CMD check` warnings and release-relevant notes, and confirm the PR's GitHub Actions matrix is green.
+- After merging to `main`, create tag `vX.Y.Z` and paste the unchanged canonical release block into the GitHub Release description. The Zenodo integration archives the release and takes its metadata from `CITATION.cff`.
+
 ## Package constraints
 
 - Never use `:::` in package code.

CITATION.cff

@@ -2,11 +2,11 @@ cff-version: 1.2.0
 message: "To cite GeoPathSampleR in publications use:"
 type: software
 license: GPL-3.0-or-later
-title: "GeoPathSampleR: Bayesian reconstruction of animal trajectories from geolocation likelihood maps"
+title: "GeoPathSampleR: Posterior Sampling of Geolocator Paths"
 version: 0.1.0
 date-released: 2026-08-15
 doi: 10.5281/zenodo.21944194
-abstract: "Bayesian reconstruction of animal trajectories from geolocation likelihood maps."
+abstract: "Reconstructs bird migration trajectories from stationary-period likelihood maps built with GeoPressureR. A Gibbs sampler combines residence-dependent departure, a ground-speed distribution conditional on movement, and a prior on cumulative route distance between long periods. Provides posterior stay summaries and sampling diagnostics."
 authors:
   - family-names: Nussbaumer
     given-names: Raphaël

DESCRIPTION

@@ -1,15 +1,16 @@
 Package: GeoPathSampleR
-Title: Bayesian Reconstruction of Animal Trajectories
-Version: 0.1.0
+Title: Posterior Sampling of Geolocator Paths
+Version: 0.1.0.9000
 Authors@R:
     person("Raphaël", "Nussbaumer", , "rafnuss@gmail.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0002-8185-1020"))
 Author: Raphaël Nussbaumer [aut, cre]
 Maintainer: Raphaël Nussbaumer <rafnuss@gmail.com>
-Description: Bayesian reconstruction of animal trajectories from geolocation
-    likelihood maps using a Gibbs sampler with movement priors. Provides
-    prepared sampler inputs, posterior path summaries, and sampling
-    diagnostics for GeoPressureR tag objects.
+Description: Reconstructs bird migration trajectories from stationary-period
+    likelihood maps built with GeoPressureR. A Gibbs sampler combines
+    residence-dependent departure, a ground-speed distribution conditional on
+    movement, and a prior on cumulative route distance between long periods.
+    Provides posterior stay summaries and sampling diagnostics.
 License: GPL (>= 3) + file LICENSE
 URL: https://github.com/GeoPressure/GeoPathSampleR,
     https://geopressure.org/GeoPathSampleR/
@@ -33,11 +34,14 @@ Suggests:
     leaflet,
     knitr,
     pkgdown,
+    plotly,
     quarto,
     rmarkdown,
     rnaturalearth,
     rnaturalearthdata,
-    testthat (>= 3.0.0)
+    scales,
+    testthat (>= 3.0.0),
+    tidyr
 Remotes:
     GeoPressure/GeoPressureR@dev
 Config/testthat/edition: 3

NAMESPACE

@@ -4,6 +4,7 @@ export(path_collapse)
 export(path_summary)
 export(plot_movement)
 export(sampling_path)
+export(sampling_path_default_movement)
 export(sampling_path_diagnostic)
 import(patchwork)
 importFrom(rlang,.data)

NEWS.md

@@ -1,4 +1,20 @@
-# GeoPathSampleR 0.1.0
+# GeoPathSampleR v0.2.0
+
+## Main
+
+- [Update the default ground-speed and residence-dependent departure parameters](https://github.com/GeoPressure/GeoPathSampleR/commit/d40999d) from the pooled multi-sensor calibration. Results sampled with the previous defaults should be recomputed before comparison.
+- [Replace the route-detour model with a Gamma prior on route excess](https://github.com/GeoPressure/GeoPathSampleR/commit/7d4fb3f) whose scale depends on interval duration and direct endpoint distance ([3798978](https://github.com/GeoPressure/GeoPathSampleR/commit/3798978)). The prior applies to intervals with at least two movement days and endpoints at least 300 km apart, with predictors limited to the empirical calibration support.
+- Export `sampling_path_default_movement()` and document the movement model, `route_detour` and the modular cut of `long_period_light_only` in `sampling_path()`.
+
+## Minor
+
+- [Fix the diagnostic report rendering and browser opening](https://github.com/GeoPressure/GeoPathSampleR/commit/fb0d61f), and [declare its optional report dependencies](https://github.com/GeoPressure/GeoPathSampleR/commit/3ff7a89).
+- [Align the README and vignette with the movement model and sampler controls](https://github.com/GeoPressure/GeoPathSampleR/commit/ae3f0de), and add a provisional citation for the submitted methods manuscript alongside the software citation.
+- [Format the elapsed time compactly in the sampling message](https://github.com/GeoPressure/GeoPathSampleR/commit/38fe161).
+
+**Full Changelog**: <https://github.com/GeoPressure/GeoPathSampleR/compare/v0.1.0...v0.2.0>
+
+# GeoPathSampleR v0.1.0
 
 * Initial public release of the stationary-path Gibbs sampler and its core
   summaries and diagnostics.

R/path_collapse.R

@@ -2,7 +2,9 @@
 #'
 #' Summarise each realised path by merging consecutive stationary periods that
 #' were assigned to the same grid cell. Paths are identified by `j` and, when
-#' present, `chain`.
+#' present, `chain`. Each draw is collapsed separately, so the output keeps
+#' one stay/move sequence per draw and all posterior variability; use
+#' [path_summary()] to summarise across draws.
 #'
 #' @param paths A path data frame containing `stap_id`, `ind`, `lat`, and
 #'   `lon`, and optionally `j`, `chain`, `start`, and `end`.

R/path_summary.R

@@ -1,9 +1,14 @@
 #' Summarise an ensemble of paths
 #'
-#' Compute either one posterior location per stationary period or one path
-#' using the consensus stay/move structure across the ensemble. The function
-#' accepts both [sampling_path()] output and simulation paths with `j` but no
-#' `chain` column.
+#' Summarise an ensemble of draws into a single path. With `by = "stap"`, the
+#' positions of all draws are summarised separately for each stationary period.
+#' With `by = "consensus_stay"`, the move probability of each boundary between
+#' consecutive periods is the proportion of draws whose grid cell changes
+#' there; boundaries above `move_threshold` split the track into consensus
+#' stays, and positions are summarised over all draws and periods of each
+#' stay. The function accepts both [sampling_path()] output and simulation
+#' paths with `j` but no `chain` column. Use [path_collapse()] to keep each
+#' draw instead.
 #'
 #' @param paths A path data frame containing `stap_id`, `ind`, `lat`, and
 #'   `lon`, and optionally `j`, `chain`, `start`, and `end`.

R/plot_movement.R

@@ -3,7 +3,8 @@
 #' Plot the speed kernel and residence-dependent probability of movement for a
 #' `sampling_path()` movement specification.
 #'
-#' @param movement movement list passed to `sampling_path()`.
+#' @param movement movement list passed to `sampling_path()`, such as
+#'   [sampling_path_default_movement()].
 #' @param speed speed values in km/h used to evaluate the movement kernel.
 #' @param stay_duration residence durations in days used to evaluate
 #'   `movement$move_stay`.
@@ -13,21 +14,7 @@
 #'   move/stay panel marks those parameters for the exponential-decay-to-plateau
 #'   model.
 #' @examples
-#' movement <- list(
-#'   method = "gamma",
-#'   shape = 1.26,
-#'   scale = 10.3,
-#'   low_speed_fix = 0.001,
-#'   zero_speed_ratio = 0,
-#'   move_stay_parameters = list(
-#'     p_0 = 0.607,
-#'     p_inf = 0.137,
-#'     tau = 0.932
-#'   ),
-#'   move_stay = function(t) 0.137 +
-#'     (0.607 - 0.137) * exp(-t / 0.932)
-#' )
-#' plot_movement(movement)
+#' plot_movement(sampling_path_default_movement())
 #' @import patchwork
 #' @importFrom rlang .data
 #' @family sampling_path