prospicio

Actuarial and risk modeling on a Rust core, exposed to Python and R.

The plan: docs/architecture.md. Design notes for the core abstractions: docs/design/.

Layout

Build and test

Prerequisites

Open a new terminal after installing so cargo, uv and R are on PATH.

Rust

All pure-Rust crates and the parity suite:

cargo test

Python (uv)

cd python
uv sync              # creates .venv, installs dev deps, builds the Rust extension
uv run pytest tests
uv run python        # a Python shell with prospicio installed

uv run rebuilds the extension automatically when Rust sources change.

R

From the repository root (a terminal where cargo --version works). The package's R API is built on S7, so install that first:

Rscript -e 'install.packages("S7")'
R CMD INSTALL R/prospicio
for f in R/prospicio/tests/*.R; do Rscript "$f"; done

Windows PowerShell: R is PowerShell's alias for Invoke-History, so call R.exe CMD INSTALL R\prospicio instead. To put R on PATH for your user (newest installed R; rerun after upgrading R), then open a new window:

$rbin = (Get-ChildItem "C:\Program Files\R" -Directory | Sort-Object Name | Select-Object -Last 1).FullName + "\bin"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$rbin", "User")

On Windows, R builds packages with Rtools' MinGW compiler, so the Rust code is compiled for the x86_64-pc-windows-gnu target (see R/prospicio/src/Makevars.win); the build stops with a message if that target is not installed.

Docs

Building a binding regenerates its docs (see "Documentation" in docs/architecture.md). Use these instead of the plain builds above whenever you change a doc comment or a public API:

Rscript -e 'install.packages(c("S7", "roxygen2", "pkgload", "pkgdown"))'  # once
cargo xtask python   # build + stubs, test, great-docs site in python/great-docs/_site
cargo xtask r        # roxygen2 man/ + NAMESPACE, install, test, pkgdown site in R/prospicio/docs
cargo xtask docs     # both plus rustdoc, collected into target/docs-site

The Python docs need Python 3.11+ (great-docs); cargo xtask python asks uv for one. Commit the regenerated python/prospicio/prospicio_native.pyi, R/prospicio/man/ and R/prospicio/NAMESPACE; never edit them by hand. cargo xtask docs --check fails if they are stale.

The same distribution, driven by the same Rust code, from all three:

import prospicio as ar
d = ar.distributions.Lognormal.from_mean_cv(1000, 0.5)
d.quantile(0.995), d.sample(3, seed=42, stream=0)

library(prospicio)
d <- lognormal_from_mean_cv(1000, 0.5)
quantile(d, 0.995); draws(d, 3, seed = 42, stream = 0)
d@meanlog; d@sdlog   # read-only S7 properties

Errors raised in Rust surface as Python ValueErrors and ordinary R errors.

Reserving

prospicio-reserving holds the four-axis, masked Triangle (docs/design/triangle.md), development factors, ChainLadder, Mack and the ODP bootstrap (OdpBootstrap), whose reserve distribution by origin is a PredictiveDistribution.

use prospicio_reserving::{ChainLadder, DevelopmentColumn, Grain, Long, Mack, Month, Triangle};

let origin = [2020, 2020, 2020, 2020, 2021, 2021, 2021, 2022, 2022, 2023].map(Month::january);
let tri = Triangle::from_long(&Long {
    keys: &[],
    origin: &origin,
    development: DevelopmentColumn::Age(&[12, 24, 36, 48, 12, 24, 36, 12, 24, 12]),
    values: &[(
        "paid",
        &[100.0, 150.0, 165.0, 170.0, 110.0, 170.0, 180.0, 120.0, 175.0, 130.0],
    )],
    origin_grain: Grain::Year,
    development_grain: Grain::Year,
    cumulative: true,
})?;
let cl = ChainLadder::default().fit(&tri, "paid")?;
let mack = Mack::default().fit(&tri, "paid")?;
assert!(cl.total_reserve() > 0.0 && mack.total_standard_error > 0.0);
println!("reserve {} ± {}", cl.total_reserve(), mack.total_standard_error);

Python and R expose the same objects:

from prospicio.reserving import Mack, OdpBootstrap, Triangle
tri = Triangle.from_long(origin, development, {"paid": paid})
Mack().fit(tri, "paid").total_standard_error
boot = OdpBootstrap(n_sims=10_000, seed=1).fit(tri, "paid")
boot.reserves.quantile(0.995)   # a PredictiveDistribution keyed by origin

tri <- triangle(long, "origin", "development", "paid")
mack(tri)@total_standard_error
boot <- odp_bootstrap(tri, n_sims = 10000, seed = 1)
quantile(boot@reserves, 0.995)  # a predictive_distribution keyed by origin

Segments are named by key columns. keys (Rust Long::keys, Python keys=, R keys =) lists them, and the long table comes back with them by name:

tri = Triangle.from_frame(df, "year", "age", ["paid", "incurred"], keys=["lob", "state"])
tri.keys, tri.index   # ['lob', 'state'], [('Auto', 'CA'), ...]
tri.to_frame()        # columns lob, state, origin, development, paid, incurred

tri <- triangle(df, "year", "age", c("paid", "incurred"), keys = c("lob", "state"))
tri@keys; tri@index   # a data.frame with columns lob and state
as.data.frame(tri)    # columns lob, state, origin, development, paid, incurred

Select segments and columns by key name, and sum segments over keys:

let auto = tri.select(&[("lob", &["Auto"]), ("state", &["CA", "NY"])])?;
let paid = tri.select_columns(&["paid"])?;
let by_lob = tri.group_by(&["lob"])?;   // sums states; group_by(&[]) is the total

tri.select(lob="Auto", state=["CA", "NY"], columns="paid")
ChainLadder().fit(tri.group_by(["lob"]).select(lob="Auto"), "paid")

subset(tri, lob = "Auto", state = c("CA", "NY"), columns = "paid")
chain_ladder(subset(aggregate(tri, keep = "lob"), lob = "Auto"), "paid")

R uses base generics (subset(), aggregate() with keep, as for a predictive_distribution) so it does not mask dplyr's filter(), select() or group_by().

Methods fit every segment at once, each on its own, and give long results with the key columns by name: one row per segment and origin, per segment (totals), or per segment and age (development factors). The bootstrap gives one joint PredictiveDistribution with the keys and origin as dimensions, so aggregating over origins keeps the dependence between segments:

let fits = Mack::default().fit_segments(&tri, "paid")?;
let by_origin = fits.to_long();          // keys, origin, latest, ..., standard_error
let totals = fits.totals();              // one row per segment
let factors = fits.development_table();  // keys, age, ldf, cdf, sigma, std_err
let auto_ca = fits.segment(&[("lob", "Auto"), ("state", "CA")])?;
let boot = OdpBootstrap::default().fit_segments(&tri, "paid")?;
let by_lob = boot.reserves.aggregate(&["lob"])?;

fit = Mack().fit(tri, "paid")      # any number of segments
fit.to_frame(); fit.totals_frame(); fit.development_frame()
fit.segment(lob="Auto", state="CA").ldf
OdpBootstrap(seed=1).fit(tri, "paid").reserves.aggregate(["lob"])

fit <- mack(tri, "paid")
as.data.frame(fit); totals_frame(fit); development_frame(fit)
segment(fit, lob = "Auto", state = "CA")@ldf
aggregate(odp_bootstrap(tri, "paid", seed = 1)@reserves, keep = "lob")

Per-origin fields (reserve, standard_error, ...) follow the rows of the long table, so a single-segment fit reads as before. Per-age fields (ldf, cdf, sigma, std_err), Mack's total standard errors and the bootstrap's scale, fitted and residuals need one segment; with several they raise an error that points to the frames or segment().

To read a triangle, view one segment and measure as an origin × development table, or summarise every segment and measure. A triangle with one segment and one measure prints as that table; otherwise it prints the summary, one row per segment and measure with its origins, valuation and latest diagonal total. The text comes from Rust, so both bindings print the same thing:

let grid = tri.view(&[("lob", "Auto"), ("state", "CA")], Some("paid"))?;
let rows = tri.summary().rows;   // n_origins, first/last origin, valuation, latest
println!("{tri}");               // the grid or the summary table

tri.view("paid", lob="Auto", state="CA")   # DataFrame: origins x ages
tri.summary()                              # one row per segment and measure
tri                                        # prints the grid or the summary

as.matrix(tri, lob = "Auto", state = "CA", column = "paid")  # origins x ages
summary(tri)                                                  # a data.frame
tri                                                           # same printout

R uses as.matrix() rather than a view() verb, which would mask tibble::view().

Every Chain Ladder and Mack value is checked against R ChainLadder and chainladder-python on RAA, GenIns and ABC in validation/; the ODP bootstrap is checked against R BootChainLadder.

Licence

Licensed under either of Apache License, Version 2.0 or MIT licence, at your option. Copyright (c) 2026 Ethan Kang.