[general]
name=Itinera – Least-Cost Pathways
qgisMinimumVersion=3.28
qgisMaximumVersion=4.99
description=Least-Cost Path, Corridor (LCC), FETE, Randomized Shortest Paths, circuit-theory connectivity, multi-criteria cost surfaces, sensitivity analysis and route validation (PDI + buffer overlap) for archaeological movement modelling.
about=Anisotropic cost-surface analysis using scipy.sparse. Provides Processing algorithms (Slope Cost Surface, Friction Cost Surface, Composite friction (multi-criteria), Accessibility / cost catchment, LCP, Stochastic LCP, Corridor, FETE, Randomized Shortest Paths, Circuit current density / pinch points, Connectivity barriers / restoration, Sensitivity Analysis, PDI Validation, Buffer Validation, Resample DEM, DEM error realisation) with ten cost functions (Tobler on/off-path, Herzog, Naismith, Llobera & Sluckin, Irmischer & Clarke, Minetti, load-aware Pandolf, and Wheeled / Pack animal critical-slope presets), plus an interactive map-click tool for point-to-point LCP. RSP adds a theta parameter spanning the least-cost-path and circuit-theory extremes; circuit theory adds current density, pinch points and barrier/restoration maps; the multi-criteria builder combines several penalty rasters into one composite friction; the stochastic DEM-error model uses true variogram (FFT spectral) random fields; accessibility produces cost catchments and isochrones. No external pip dependencies required (uses numpy/scipy bundled with QGIS). Released under the MIT licence.
version=0.14.1
author=Patrick Leiverkus (DAO)
email=patrick.leiverkus@uni-oldenburg.de
homepage=https://github.com/leiverkus/itinera
tracker=https://github.com/leiverkus/itinera/issues
repository=https://github.com/leiverkus/itinera
tags=archaeology,least cost path,corridor,fete,cost surface,movement,tobler,anisotropic
category=Analysis
icon=icon.png
experimental=True
deprecated=False
hasProcessingProvider=yes
changelog=
    0.14.1 - Robustness fixes (no API additions). The stochastic precision stop criterion now uses the Wilson 95% confidence-interval error on the reported fraction - max(p_hat - lower, upper - p_hat) - instead of a standard error, which reduces (to the chosen confidence level, not with certainty) the chance of a rarely-sampled route triggering premature convergence and a falsely deterministic map; repeated interim checks are not a formal confidence sequence, so effective coverage is somewhat looser than the nominal 95% (note: tol is now a CI error bound, stricter than the old standard error). Convergence parameters are validated (tol finite & > 0; min_iter / check_every / patience integer >= 1; check_every=0 no longer divides by zero, patience=0 no longer false-converges). Circuit current density returns a null map when a source is also a grounded target (was near-uniform phantom current). Multi-criteria out_range now requires 0 < lo < hi, finite (a 0 minimum made cells impassable; a negative one broke the geometric mean). Non-finite (NaN / inf) cost-function weights are rejected with a clear message instead of surfacing as NumPy 'Probabilities contain NaN'. The Llobera & Sluckin cost function no longer applies abs() to its linear term: the published quartic (Llobera & Sluckin 2007, Eq. 16) uses a signed slope, so the cost minimum sits on a gentle downhill (~ -0.175) instead of being forced to flat ground - this restores the downhill anisotropy and lowers descent costs (uphill unchanged). Scientific-correctness audit fixes: FETE now computes all n*(n-1) directed routes (was unordered pairs, dropping anisotropic return legs); RSP makes the target absorbing per the cited Saerens/Panzacchi/gdistance process (was a shared non-absorbing matrix, which could reorder passage values); PDI now divides by the straight-line origin-destination distance, snaps the modelled path's endpoints to the reference O/D first (per leastcostpath), and is attributed to Jan, Horowitz & Peng 2000 (was reference-path length, no snapping, Goodchild & Hunter). Docs corrected: the wheeled/pack-animal presets are labelled experimental Itinera heuristics (Herzog's vehicle function is symmetric; no validated pack-animal function exists), the stochastic DEM error is an Itinera variogram-FFT field in the spirit of (not a reproduction of) Hunter & Goodchild / Lewis, the multi-criteria builder is a generic Itinera heuristic with an extent-dependence caveat, and the precision criterion is a pointwise (not simultaneous) 95% interval.
    0.14.0 - Movement-mode cost presets + accessibility surfaces (completes the methods roadmap). Two anisotropic critical-slope cost functions - Wheeled (cart, ~8% critical upward slope) and Pack animal (~25%) - where cost rises quadratically with grade and the uphill limit is tighter than downhill (Herzog 2013, Verhagen 2019); ten cost functions total. A new Accessibility / cost catchment algorithm computes the cost-distance surface from source point(s) plus an optional within-budget catchment mask and isochrone bands (core/accessibility.py).
    0.13.0 - Convergence / stop criterion + progress reporting for the stochastic LCP. The Monte-Carlo loop can stop early once the probabilistic corridor is good enough: stabilisation (the map stops changing, max|dp| < tol) or precision (max binomial standard error < tol). The Stochastic LCP algorithm gains Maximum iterations + convergence tolerance + criterion + minimum iterations, and logs the live metric per checkpoint. (stochastic_lcp gains tol / convergence / return_diagnostics.)
    0.12.0 - Cost-model randomisation in the stochastic LCP (Herzog 2022: no universal best cost model). The Stochastic LCP cost function is now multi-select - each Monte-Carlo realisation samples one cost function from the chosen set (uniform or weighted) - plus a parameter-jitter control that perturbs the Pandolf mass/load/terrain by a fraction each iteration. The probabilistic corridor now integrates cost-model uncertainty alongside DEM error and edge-dropping (stochastic_lcp gains cost_fns / cost_weights / param_jitter).
    0.11.0 - Variogram-based DEM error fields (Hunter & Goodchild 1997). The stochastic DEM-error model is now a true geostatistical Gaussian random field - exponential (new default), spherical or gaussian variogram with an optional nugget - generated by FFT spectral simulation (scipy.fft, no gstat dependency), replacing the Gaussian-filter approximation (kept as a fast option). The Stochastic LCP algorithm gains DEM error model + nugget parameters, and a new standalone DEM error realisation tool outputs one perturbed DEM (core/stochastic.py::simulate_error_field).
    0.10.0 - Multi-criteria composite friction (Herzog 2022, Litvine 2024): a new Cost-surfaces algorithm and core/multicriteria.py that merge several penalty rasters (hydrology, wetness, land cover, viewshed masks) into one friction multiplier - each min-max normalised, optionally inverted and weighted, combined by a weighted arithmetic (sum) or geometric (product) mean into a chosen range (1 neutral, >1 discourages, <1 prefers); NoData is impassable. Plugs into the existing multiplier / friction slots. Completes Tier 2 of the methods roadmap.
    0.9.0 - Circuit-theory connectivity (McRae 2008, 2012): movement as electrical current flow, the random-walk complement to the LCP. Two algorithms in a new Connectivity group plus core/circuit.py (pure numpy/scipy): Circuit current density / pinch points (solve the graph Laplacian Lv=i, source injected / target grounded, for a current-density raster + optional pinch points within the least-cost corridor; the anisotropic conductance is symmetrised, use RSP for the directed current) and Connectivity barriers / restoration (a moving-window improvement map over the corridor surfaces marking the strongest barriers).
    0.8.0 - Randomized Shortest Paths (RSP): a single theta parameter spans the whole optimal-to-random movement axis (large theta = least-cost path, small theta = random-walk / circuit current density; Panzacchi 2015, van Etten 2017). New core/rsp.py (pure numpy/scipy: W = P_ref * exp(-theta*C), one sparse LU of (I-W) over the existing conductance matrix) and a Processing algorithm (one origin to destination(s); a movement-density raster + the RSP free-energy distance; a 'Normalise costs' flag so theta ~ 1 is meaningful across cost functions). Keeps anisotropy throughout.
    0.7.1 - Hardening + docs. Buffer validation now rejects non-positive buffer distances (a 0 distance could previously make the densifier allocate a near-unbounded number of points on long lines); the user docs (README, PyPI description, manual) are brought up to date with the 0.7.0 features (eight cost functions, Buffer Validation, Sensitivity Analysis).
    0.7.0 - Three method additions completing the review's Tier-1 roadmap. (1) Energetics cost functions: Irmischer & Clarke (GPS-calibrated walking speed), Minetti (cost of transport) and load-aware Pandolf with the Santee/Yokota downhill correction; cost functions now accept extra keyword parameters (body mass / load / terrain factor), exposed on every conductance-building algorithm. (2) Buffer-overlap validation (Goodchild & Hunter 1997) as a multi-distance similarity table, beside the PDI. (3) Sensitivity analysis: sweeps the selected cost functions x connectivities for one origin/destination pair and reports an agreement raster, a per-configuration summary table, optional individual paths, and a route-stability scalar.
    0.6.1 - FETE can now optionally output the individual least-cost paths as a line layer (one feature per point pair, with from_id/to_id/cost), alongside the traversal-frequency raster. The paths were already computed internally; they are now exposed via an optional output. No change to the raster result.
    0.6.0 - The pure numpy/scipy core is now also published as the `itinera` PyPI library (pip install itinera), built single-source from core/ via hatchling. No change to the QGIS plugin itself.
    0.5.9 - Dev tooling: flake8 is now a CI check (max-line-length 88); excluded maintainer/dev-only files (CLAUDE.md, setup.cfg, pytest.ini, requirements-dev.txt) from the packaged zip. No runtime change.
    0.5.8 - QGIS 4 / Qt6 runtime fixes: the settings dialog crashed on QDialogButtonBox.Ok (now scoped StandardButton), and the LCP output used QVariant.Int which PyQt6 removed (now QMetaType on Qt6, QVariant on Qt5). Verified on QGIS 3.28 and 4.0.
    0.5.7 - Code hygiene: removed unused imports (flake8 F401) and added a setup.cfg ignoring W503/W504. No behaviour change.
    0.5.6 - Declared QGIS 4 compatibility via qgisMaximumVersion=4.99 (without it QGIS assumed a 3.99 maximum and marked the plugin incompatible on QGIS 4). Verified loading on QGIS 4.0.
    0.5.5 - Documentation: added QGIS 3.28+/4.0 and Qt5/Qt6 compatibility badges to the README.
    0.5.4 - QGIS 4 / Qt6 compatibility: the settings dialog used exec_(), which PyQt6 removed; switched to exec() (works on QGIS 3 and 4). No other changes.
    0.5.3 - The "Interactive LCP settings…" button now has its own gear icon, distinct from the path icon of the LCP tool button.
    0.5.2 - Replaced the blank placeholder plugin icon with a real, visible one, so the two interactive-tool buttons are findable on the Plugins toolbar. Clarified in the docs where those buttons live.
    0.5.1 - Documentation only: README status badges, future-directions wording, and removal of the internal publishing guide from the README and the packaged zip. No code changes.
    0.5.0 - New "Resample DEM (block mean)" algorithm and a memory pre-flight warning for large DEMs; stochastic_lcp guards against n_iter < 1; added a user manual (docs/MANUAL.md) and verified references (docs/REFERENCES.md, references.bib). Corrected stochastic citation to Lewis 2021.
    0.4.0 - Interactive LCP tool is now configurable: an "Interactive LCP settings…" toolbar/menu action picks the cost function and neighbourhood (parity with the Processing algorithms); the graph cache rebuilds only when settings change.
    0.3.0 - New Stochastic least-cost path (Lewis 2023): N Monte-Carlo realisations with spatially-correlated DEM error (RMSE-scaled) and/or random edge dropping, accumulating a probabilistic corridor in [0,1]. Seed for reproducibility; supports the barrier/multiplier raster.
    0.2.2 - Fix: xy_to_rowcol now floors instead of truncating, so points just west/north of the raster are correctly out of bounds (not wrongly snapped to row/col 0).
    0.2.1 - Fixes: point layers are reprojected to the DEM CRS before cell lookup (algorithms + map tool); barrier/friction rasters are validated against the DEM CRS and geotransform (not just pixel count); rotated/non-square rasters are rejected with a clear error. Documented PDI limitations.
    0.2.0 - Optional barrier / multiplier raster on the slope-based algorithms (slope cost surface, LCP, LCC, FETE): edge cost is scaled by the mean of the two cells' values (>1 discourages, <1 prefers, e.g. known roads); NoData or <=0 cells are impassable (cliffs, deep wadis).
    0.1.0 - Initial release: anisotropic LCP, LCC corridor, FETE, PDI validation, slope & friction cost surfaces, interactive two-click LCP map tool. Pure numpy/scipy/GDAL (no external pip dependencies).
