Spoke

calculus

Statistical honesty in the toolbox — / / normal auto-selected, .

Character

A PA professional who actually cares about confidence intervals and method selection. The person on your team who knows that Wilson is the right choice for proportions and gets visibly tense when someone waves a lone engagement uplift figure with no uncertainty band.

Problem

External. People analytics outputs are full of point estimates without intervals. The vendors that DO show intervals usually use normal-CI for everything regardless of sample size or distribution shape. Wilson CI for proportions is in academic stat textbooks; it's never in HR platforms.

Internal. You're seen as pedantic when you bring up method selection. The audience for your rigor is small inside the org, but it's the audience whose opinion matters most.

Philosophical. Every metric should ship with its CI, its sample size, its method, its provenance. Statistical rigor is a platform concern, not an advanced add-on.

Guide

Calculus does the statistical thinking nobody else in your stack does: it picks the right confidence-interval method for the shape of your data and attaches it to every number you ship — so a "4-point lift" never gets shown without its margin of error. calculus — the toolbox's statistical brain. MetricEnvelope shape ( × segmentId × period × value × sampleSize × provenance × enrichment). Auto-selected CI method: Wilson for proportions with denominators, t-interval for small samples (n<30), normal for large. trend classification (rising / stable / falling). Anomaly detection (leave-one-out z / IQR / change-point). Metric × segment × period combinatorial factory. Surrogate models wire into forecasting for uncertainty-aware extrapolation scenarios (PAT-147-C composition).

Abstract

Background. People metrics rarely ship intervals even when denominators swing, cultivating false precision and weakening executive discourse about sampling variability.

Methodology. Every measurement travels as an enriched MetricEnvelope with auto-selected intervals (Wilson, Student-t, normal) plus optional OLS trend slopes, percentile ranks, anomaly probes, and surrogate persistence feeding Monte Carlo linkage.

Scope. Executes statistical transforms only; metricKey legitimacy consults metrics-catalog softly and never replaces specialised psychometrics (reincarnation) or causal pipelines (program-evaluation).

Contribution. Harmonised MCP + HTTP entry points with reproducible surrogates reduce bespoke notebook glue when uncertainty must surface in forecasting workflows.

Evidence / Provenance. Classical CI citations captured in PAT calculus memos; regression harnesses under src/spokes/calculus/tests/.

Plan

01
Wrap your metrics
Build MetricEnvelope objects (Zod-typed). Every measurement carries its key, segment, period, value, sample size, provenance.
02
Enrich
calculus.stats-enrich adds CI, z-score, percentile, change rate — method auto-selected from the data shape.
03
Compose at scale
calculus.factory-build takes a metric × segment × period grid plus a values array, builds envelopes, enriches each, and returns a ranked list (impact / significance / change / recency / sample-size).
04
Trend, impute, anomaly-detect
stats-trend classifies rising/stable/falling; stats-impute fills holes; stats-anomaly flags outliers. Fold enriched outputs into forecasting Monte Carlo drawers when modelling uncertainty end-to-end.

Call to Action

Direct. Try the API. Enrich an envelope free.

Transitional. Read the method-selection methodology (Phase 3). See the live demo at /metric-market.

Spoke I/O (visual language v1)

Every toolbox spoke shares the same abstract choreography: typed inputs on the left, distilled verbs in the center, typed outputs on the right, and (when relevant) cross-spoke HTTP composition along the bottom rail. Source package: @people-analytics-toolbox/spoke-illustrations.

Try it now

Copy this curl. Paste in any terminal. POST endpoint — set TOOLBOX_SERVICE_KEY in your shell first.

calculus.stats-trend

POST

SERVICE KEY REQUIRED

Classify an evenly-spaced periods array as rising / stable / falling with OLS slope and change rate.

curl -sS -X POST "https://people-analytics-toolbox.vercel.app/api/spokes/calculus/stats/trend" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOOLBOX_SERVICE_KEY" \
  -d '{
  "tenantId": "demo-tenant",
  "periods": [
    { "period": "2025-Q1", "value": 70 },
    { "period": "2025-Q2", "value": 75 },
    { "period": "2025-Q3", "value": 80 }
  ]
}'

Vendor the contract

The Zod contract is the source of truth. Vendor a copy into your consumer app — you keep it; we don't break it underneath you. Re-vendor when the version bumps.

// In your consumer app:
import { z } from "zod";

// Vendor a copy of these contracts from the toolbox repo at:
//   src/spokes/calculus/contracts/types.ts

import {
  MetricEnvelopeSchema,
  StatsEnrichRequestSchema,
  StatsEnrichResponseSchema,
  StatsTrendRequestSchema,
  StatsTrendResponseSchema,
  FactoryBuildResponseSchema,
  CONTRACT_VERSION,
} from "./vendored/calculus/types";

// Then call the toolbox over HTTP or MCP.
// See docs/EXTERNAL-CONSUMERS.md for onboarding.

Source path: src/spokes/calculus/contracts/types.ts · GitHub

Try in Dev Console Read the explainer See metric × segment × period grids on /metric-market Live calculus cards on /feed Back to all spokes

Failure

Storytelling passes for analytics—executives green-light the wrong initiative because no one plotted an interval spanning zero on the touted lift.

Success

Every metric carries defensible inference metadata; anomalies cite algorithms; envelopes flow into organisational simulation without rewriting SQL spaghetti.