Skip to content

README.md

Latest commit

 

History

History
286 lines (226 loc) · 13.8 KB

README.md

File metadata and controls

286 lines (226 loc) · 13.8 KB
Raw

voiage: Value of Information Analysis

PyPI Python CI Coverage CodeQL OpenSSF Scorecard Documentation License

voiage provides Value of Information (VOI) methods for comparing decisions under uncertainty and assessing whether additional evidence may be worth collecting. The v2.0 release combines:

  • a Python API and command-line interface (CLI);
  • binding-independent Rust domain, diagnostics, numerical, and serialization crates;
  • selected Rust-backed aggregation kernels exposed to Python through PyO3;
  • an R package and Julia package that call the versioned Rust C application binary interface (ABI) for Expected Value of Perfect Information (EVPI);
  • labelled data structures, diagnostics, plotting, reporting, and provenance-aware interchange.

Python currently retains the broader model orchestration, validation, labelled data, plotting, and reporting paths. The R and Julia packages do not yet expose the full Python method surface. See Architecture and Language support for the precise boundary.

When voiage is useful

VOI analysis asks whether uncertainty could change a decision and whether the expected benefit of resolving some uncertainty justifies further research. voiage supports analyses including:

  • EVPI for the expected cost of current decision uncertainty;
  • Expected Value of Partial Perfect Information (EVPPI) for selected parameters;
  • Expected Value of Sample Information (EVSI) and Expected Net Benefit of Sampling (ENBS) for proposed studies;
  • cost-effectiveness acceptability and frontier analysis;
  • structural, network meta-analysis, subgroup, sequential, adaptive, and portfolio-oriented VOI workflows;
  • fixture-backed experimental work on perspective, equity, implementation, and adjacent VOI questions.

Stable and experimental surfaces are distinguished in the method documentation and frontier roadmap. An implemented method is not, by itself, evidence that it is appropriate for a particular decision problem; users remain responsible for model structure, inputs, assumptions, and interpretation.

Installation

Install the released Python package:

python -m pip install voiage

Python 3.12, 3.13, and 3.14 are supported. Wheels use the CPython 3.12 stable ABI and are published for the platforms listed in the v2.0.0 release.

Optional features are installed explicitly:

python -m pip install "voiage[plotting]"       # Matplotlib and Seaborn
python -m pip install "voiage[jax]"            # experimental JAX backend
python -m pip install "voiage[experimental]"   # experimental serializers

Development installation and complete verification instructions are in CONTRIBUTING.md.

Quick start

import numpy as np

from voiage.analysis import DecisionAnalysis
from voiage.schema import ValueArray

net_benefit = ValueArray.from_numpy(
    np.array(
        [
            [10.0, 12.0],
            [11.0, 9.0],
            [13.0, 14.0],
        ]
    ),
    strategy_names=["Standard care", "New treatment"],
)

analysis = DecisionAnalysis(net_benefit)
print(f"EVPI: {analysis.evpi():.3f}")

The rows are uncertainty draws and the columns are decision strategies. For real analyses, preserve the units, population scaling, time horizon, discount rate, and strategy labels needed to interpret the result.

Command-line interface

The CLI supports batch workflows over CSV inputs:

voiage calculate-evpi examples/cli_samples/evpi_net_benefit.csv

voiage calculate-evpi examples/cli_samples/evpi_net_benefit.csv \
  --population 100000 \
  --time-horizon 10 \
  --discount-rate 0.03 \
  --output evpi-result.txt

voiage calculate-evppi \
  examples/cli_samples/evpi_net_benefit.csv \
  examples/cli_samples/evppi_parameters.csv

voiage --help

See the CLI reference for input schemas, output formats, logging controls, and additional commands.

Capability status

Capability Status Scope
EVPI, EVPPI, ENBS Stable Python API and CLI with Rust-owned numerical policy
EVSI Method-specific The analytical two-arm normal path is stable; the developing two-loop path uses one coherent fitted Gaussian prior or explicit custom sampling and joint-posterior callbacks; compatibility estimators without a complete validated study-model contract are non-stable
Acceptability, frontier, dominance, heterogeneity Stable Analysis and plotting helpers
Structural and network meta-analysis VOI Stable Python method surface
Adaptive, calibration, observational, sequential VOI Stable Python study-design workflows
Portfolio VOI Stable Budget-constrained portfolio analysis
Diagnostics and data interchange Stable Versioned contracts; Arrow/Parquet is the canonical tabular interchange
R and Julia EVPI Released binding source Direct versioned Rust interface; both require the separately supplied voiage-ffi library
Broader R and Julia method parity Partial Advanced R paths retain the documented Python bridge; Julia is EVPI-focused
Perspective and frontier extensions Experimental Fixture-backed contracts; not represented as stable
Mojo binding Not released No publishable Mojo package is claimed
FPGA and ASIC execution Evidence only Simulation and pre-silicon evidence do not establish production hardware support

Architecture

The repository is moving towards a binding-independent Rust core, but v2.0 is still a hybrid implementation:

Python API / CLI / orchestration / labelled data / plots / reports
                              |
                         PyO3 adapter
                              |
Rust domain + diagnostics + selected numerical kernels + serialization
                              |
                    versioned C ABI adapter
                         /             \
                  R package        Julia package

The publishable Rust workspace crates live under rust/crates/:

  • voiage-domain: validated binding-independent domain contracts;
  • voiage-diagnostics: structured diagnostics and error contracts;
  • voiage-numerics: binding-independent numerical kernels;
  • voiage-serialization: canonical serialization adapters.

The voiage-ffi, voiage-python, and voiage-test-support crates are private adapters or test infrastructure. Python remains responsible for wider method orchestration and user-facing analytical features not yet migrated to Rust. The polyglot release documentation records the supported boundary and migration policy.

Language support

Surface Source Current use Distribution status
Python voiage/ Primary API, CLI, orchestration, plots, reports PyPI v2.0.0 and TestPyPI
Rust rust/ Domain contracts, diagnostics, selected kernels, serialization Crates are package-ready; consult the release checklist for verified registry state
R r-package/voiageR/ Direct C-ABI EVPI; documented bridge for wider Python methods r-universe; CRAN review remains external
Julia bindings/julia/ Direct C-ABI EVPI Prepared for Julia General; registry entry is not yet verified

Registry readiness and actual registry publication are reported separately. The binding submission checklist is the maintained evidence record for conda-forge, CRAN, Julia General, crates.io, and other external channels.

Documentation and examples

Example plots generated by the maintained documentation fixtures:

Acceptability curve EVSI and ENBS EVPI by threshold
Cost-effectiveness acceptability curve EVSI and ENBS by sample size EVPI by willingness-to-pay threshold

Quality, testing, and security

The repository applies different forms of evidence to different failure modes:

Area Repository controls
Style and prose Ruff formatting/linting, Vale, ChkTeX, LaCheck
Static analysis ty, BasedPyright, Bandit, Vulture, Clippy, CodeQL
Unit and contract testing Pytest and Cargo tests across APIs, schemas, versions, provenance, and registries
Integration and end-to-end testing CLI, package, clean-install, workflow, FFI, and cross-language paths
Generative testing Hypothesis, proptest, metamorphic, differential, and parity checks
Mutation testing Ratcheted Python mutation cohorts and critical-kernel policy
Coverage Branch coverage, changed-line policy, critical-module checks, Codecov, and a 90% Python threshold
Rust-specific assurance MSRV, Clippy, Miri, fuzzing, sanitizer jobs, advisory and license policy
Supply chain Pinned Actions, Dependency Review, OpenSSF Scorecard, Zizmor, SBOMs, checksums, provenance attestations, and release signatures
Platform assurance Linux, macOS, Windows, UTF-8/LF, Python 3.12–3.14, minimum and maximum dependencies
Documentation and papers Astro/Starlight builds, link/semantic checks, arXiv source and PDF audits, deterministic readability evidence

Renovate manages Python/uv, Cargo, npm, and GitHub Actions updates. Dependabot version-update configuration is intentionally absent so the repository has one dependency-update bot and does not create duplicate pull requests. Full commands and control boundaries are in the quality and security guide and SECURITY.md.

Releases, citation, and archival

The canonical preprint source is paper/main.tex. Repository automation builds, lints, audits, and packages the manuscript. Authenticated arXiv submission 7861466 is verified as submitted, but a permanent arXiv identifier and announcement have not yet been assigned. The separate paper.md adaptation passes repository-owned JOSS preflight; no JOSS submission, review, or acceptance is claimed.

Project status and roadmap

The repository-owned v1 programme is implemented and archived. That does not mean every proposed extension or external publication is complete. Current boundaries include:

  • migration of wider Python orchestration into the Rust core;
  • broader native R and Julia API parity;
  • experimental frontier-method validation and promotion;
  • external registry review or indexing where not yet evidenced;
  • SciCrunch registration was submitted on 27 July 2026 after a no-match duplicate check and account confirmation; curation and RRID assignment remain external, alongside later arXiv/JOSS author-led submissions;
  • physical FPGA or fabricated-silicon evidence.

See roadmap.md, todo.md, and the Conductor registry for evidence-backed status.

Contributing and support

This is currently a solo-maintainer repository. Pull requests remain the auditable change boundary, with automated quality and security checks required but no independent approval requirement. See:

Use GitHub Issues for reproducible bugs and feature requests, and GitHub Discussions for design or usage questions.

License

voiage is licensed under the Apache License 2.0.