Vs30 refactor

[AndrewRidden-Harper]

Re-opened after history rewrite

This PR is a re-opened version of an earlier one. Between then and now, I used git filter-repo to remove some unused benchmark files from the repo's history. The rewrite worked as intended but changed every commit's SHA, which orphaned the previous branch from master and made the old PR unmergeable, so I closed it and re-targeted the same work against the rewritten history. The content is unchanged; only the underlying SHAs have shifted.

Important

If you have an existing local clone of this repository, delete it and re-clone from scratch before pulling these changes. Your local commits share no history with origin anymore - git pull on top of an old clone will fail or produce a broken state. A fresh git clone is the safe move.

Summary

This PR continues the Vs30 package refactor, addressing prior review feedback, adding two new bundled models and support for custom YAML configurations, and incorporating other improvements.

Addressed review feedback

Several review comments from the previous PR have all been addressed. Most do not warrant a specific call-out but some structural changes are worth flagging:

• Removed CLI access to individual pipeline steps (interested users can still call the functions)
• CLI module (cli.py) is now just a CLI wrapper (without pipeline orchestration code)
• Shared parameters lifted from per-model configs into constants.py. Values that were previously declared in each of the bundled model config files are now defined once in code; the config files are correspondingly leaner.
• Bundled model versions are specified by a StrEnum rather than their config file name. The four valid names live as FixedModelVersion members in vs30/constants.py, giving a single canonical source for the supported set.

Additional development work

• Ensured exact correspondence between points and grid modes. New tests verify identical outputs at tricky locations like geological category boundaries, missing-value edges in the terrain raster, and similar edge cases.
• Tightened grid-bounds semantics to ensure unambiguous pixel-edge interpretation and eliminate the potential for inconsistencies from GDAL tie-breaking behaviour.
• Added the jaehwi_v1p0 model (in addition to the existing modified_foster_2019 and viktor_cpt_clustering), along with the gap-filling functionality it requires.
• Added a near-reproduction of the Foster et al. (2019) model (foster_2019_approx). Exact reproduction wasn't pursued because the published model has known flaws.
• Added support for custom YAML model configurations. Users can pass a YAML config path in place of a bundled model name to define their own model variants without modifying the package.
• Added small end-to-end benchmark tests with reference outputs generated by the legacy code, to verify reproduction.
• Removed the Python multiprocessing option. Testing across a wide range of scenarios showed it was consistently slower than the single-process path, which is already multi-threaded via the BLAS used by NumPy/SciPy.
• Other performance touch-ups — einsum-based MVN distances, gapfill memory optimisation, Float32 coast-distance arrays, etc.
• Added a brief GitHub wiki.

Why points and grid are separate pipelines

A natural design question is why the package maintains two separate pipelines rather than collapsing them into one. Both pipelines produce identical results at every location (verified by the correspondence tests above); they are kept separate purely for performance. Each direction of unification has its own performance problem:

• Have vs30 grid call the points pipeline at each pixel. This loses the bulk array operations that the grid pipeline gets from GDAL: bulk raster reads, bulk sampling, bulk spatial adjustment. At national-grid sizes (millions of pixels) it would be impractically slow.
• Have vs30 points run the grid pipeline and sample the desired sites from it. This would compute Vs30 across an entire grid regardless of how many sites are requested, making typical points-mode queries needlessly slow.

[gemini-code-assist]

Code Review

This pull request executes a comprehensive refactoring of the VS30 package, introducing a modular architecture, a Typer-based CLI, and a YAML-driven configuration system for model versions. Key enhancements include updated dependencies for Python 3.11+, a robust suite of benchmark and consistency tests, and a standardized coordinate system using NZTM2000. Feedback highlights several critical areas for optimization and correction: the MVN spatial adjustment in spatial.py should utilize a spatial index to resolve performance bottlenecks caused by high computational complexity; the Bayesian update logic in category.py must clip the posterior standard deviation to correctly maintain minimum uncertainty; the exponential correlation function should not enforce a minimum distance at zero to avoid incorrect variance calculations; and the gap-filling logic in pipeline.py should be batched to improve efficiency for large point sets.

[AndrewRidden-Harper]

Addressed the comments from the gemini-code-assist bot

[joelridden]

sites_load.py doesn't exist anymore? Not sure where the functions live now

[AndrewRidden-Harper]

Good catch — this README hadn't had a careful pass before the PR, and following up on your comment surfaced enough staleness (and a few inaccuracies) that I rewrote the whole thing (ea74b28). sites_load.py was legacy and removed in the refactor, so those loaders aren't in the package anymore; the CSVs now ship pre-generated, with sites_load.py kept only as a provenance note for where the data came from.