@crewhaus/tool-table 0.7.0

package/dist/lib/drift.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Has the data moved since the baseline?
+ *
+ * Four things go wrong between yesterday's export and today's, and only one
+ * of them is visible in a row count: the schema changes, a column's
+ * distribution shifts, a column starts arriving empty, or a categorical
+ * column grows a value nothing downstream has ever seen. This compares a
+ * stored profile against today's and answers all four.
+ *
+ * THE RULE THAT MAKES ANY OF IT MEAN ANYTHING. A Population Stability Index
+ * is a comparison of two histograms over the SAME bins, and the bins have to
+ * be the reference's. Bin each side against its own quantiles and every
+ * column comes back with ten bins of ten percent on both sides — PSI near
+ * zero, however far the distribution actually moved. So the reference profile
+ * carries its edges, the current data is binned against those stored edges,
+ * and `compareDrift` REFUSES a column whose two sides were not binned
+ * identically rather than returning the plausible number.
+ *
+ * The statistics come from `@crewhaus/tool-math`'s kernel, which is where
+ * Mann-Whitney, PSI and the normal tail live for the whole repository. The
+ * chi-square below is the one piece that was not already there.
+ */
+import { statsKernel } from "@crewhaus/tool-math";
+import type { ColumnType, TableProfile } from "./profile";
+/** A refusal: the data cannot answer the question asked of it. */
+export declare class DriftError extends Error {
+    readonly name = "DriftError";
+}
+/**
+ * P(X > x) for a chi-square variate with `df` degrees of freedom — the upper
+ * tail, which is the p-value of every chi-square test.
+ *
+ * This is Q(df/2, x/2) of the regularized incomplete gamma function, split at
+ * `x < a + 1` between the series and the continued fraction because each one
+ * loses its digits in the other's region (Press et al., *Numerical Recipes*,
+ * §6.2). The kernel in `@crewhaus/tool-math` has the normal tail but not this
+ * one; `lib.test.ts` cross-checks the df=1 case against that normal tail,
+ * since Q(1/2, x/2) is exactly erfc(sqrt(x/2)) = 2 * P(Z > sqrt(x)).
+ */
+export declare function chiSquareUpperTail(x: number, df: number): number;
+export type ChiSquareResult = {
+    readonly chiSquare: number;
+    readonly df: number;
+    /** `null` when the table has nothing to test — see `note`. */
+    readonly p: number | null;
+    readonly categories: number;
+    /** Cells whose EXPECTED count is under 5, and under 1. Where it frays. */
+    readonly cellsBelowFive: number;
+    readonly cellsBelowOne: number;
+    readonly cells: number;
+    /** Cochran's condition: no expected cell under 1, at most a fifth under 5. */
+    readonly approximationValid: boolean;
+    readonly note: string;
+};
+/**
+ * Chi-square test of homogeneity on the 2 x k table of (reference, current)
+ * against category — "are these two samples drawn from the same distribution
+ * over these labels?".
+ *
+ * A category present on only one side stays in the table. It is the single
+ * most informative cell there is, and dropping it to avoid a zero is how a
+ * column that gained a whole new value tests as unchanged.
+ *
+ * `approximationValid` is Cochran's rule, and it is NOT advisory: the
+ * chi-square statistic's null distribution is only approximately chi-square,
+ * and with a handful of rare categories the approximation is off by enough to
+ * move a verdict. A caller gating on `p` should gate on this first.
+ */
+export declare function chiSquareHomogeneity(reference: Readonly<Record<string, number>>, current: Readonly<Record<string, number>>): ChiSquareResult;
+export type DriftThresholds = {
+    /** Fail when a column's PSI is at or above this. 0.25 is the usual line. */
+    readonly psi?: number;
+    /** Fail when a VALID distribution p is at or below this. */
+    readonly pValue?: number;
+    /** Fail when a column's null fraction rose by at least this much, absolute. */
+    readonly nullRateIncrease?: number;
+    /** Fail when distinct-count ratio leaves [1/r, r]. Must be >= 1. */
+    readonly cardinalityRatio?: number;
+    /** Fail when row-count ratio leaves [1/r, r]. Must be >= 1. */
+    readonly rowCountRatio?: number;
+    /** Fail when a column gains more than this many categories. */
+    readonly newCategories?: number;
+    /** Fail on any added, removed or retyped column. */
+    readonly schemaDrift?: boolean;
+};
+export type DriftCompareOptions = {
+    /**
+     * The share substituted for a bin empty on one side. No default, here or
+     * anywhere below: it decides the verdict. A reference bin that empties out
+     * reads as PSI 0.466 at 1e-3, 0.218 at 1e-2 and 0.045 at 0.05 — significant,
+     * moderate and stable, from one dataset. It belongs in the same config as
+     * the threshold it is compared against.
+     */
+    readonly epsilon: number;
+    readonly thresholds?: DriftThresholds;
+    /** Return every PSI bin rather than the three heaviest contributors. */
+    readonly includeBins?: boolean;
+};
+export type PsiReport = {
+    readonly value: number | null;
+    readonly band: "stable" | "moderate" | "significant" | null;
+    readonly epsilon: number;
+    /** True when a one-sided empty bin took the floor, i.e. PSI depends on it. */
+    readonly epsilonApplied: boolean;
+    /** Bins actually compared, INCLUDING the two out-of-range bins. */
+    readonly binCount: number;
+    /** Current values that fell outside the reference's range, by side. */
+    readonly outOfRange: {
+        readonly below: number;
+        readonly above: number;
+    };
+    readonly bins: ReadonlyArray<statsKernel.PsiBin>;
+    readonly note: string;
+};
+export type ColumnDriftResult = {
+    readonly column: string;
+    readonly kind: "numeric" | "categorical" | "incomparable";
+    readonly nulls: {
+        readonly reference: number;
+        readonly current: number;
+        readonly increase: number;
+    };
+    readonly distinct: {
+        readonly reference: number;
+        readonly current: number;
+        readonly ratio: number | null;
+    };
+    readonly psi: PsiReport | null;
+    readonly mannWhitney: statsKernel.MannWhitneyResult | null;
+    readonly chiSquare: ChiSquareResult | null;
+    /** Categories in today's data and not the reference's. `null` = cannot say. */
+    readonly newCategories: ReadonlyArray<string> | null;
+    readonly droppedCategories: ReadonlyArray<string> | null;
+    readonly notes: ReadonlyArray<string>;
+};
+export type SchemaDriftReport = {
+    readonly added: ReadonlyArray<string>;
+    readonly removed: ReadonlyArray<string>;
+    readonly retyped: ReadonlyArray<{
+        readonly column: string;
+        readonly reference: ColumnType;
+        readonly current: ColumnType;
+    }>;
+    /**
+     * A column that flipped between being compared as numbers and as labels.
+     * Worth separating from `retyped`: `integer` to `decimal` is a retype that
+     * still compares fine, and numeric to categorical is one that cannot.
+     */
+    readonly kindChanged: ReadonlyArray<{
+        readonly column: string;
+        readonly reference: string;
+        readonly current: string;
+    }>;
+};
+export type DriftReport = {
+    readonly rows: {
+        readonly reference: number;
+        readonly current: number;
+        readonly ratio: number | null;
+    };
+    readonly schema: SchemaDriftReport;
+    readonly columns: ReadonlyArray<ColumnDriftResult>;
+    readonly gate: {
+        readonly configured: boolean;
+        readonly ok: boolean;
+        readonly failures: ReadonlyArray<string>;
+        /**
+         * Configured thresholds that could not be evaluated at all — the column
+         * produced no such measurement. `ok` is false while this is non-empty:
+         * a gate that did not get to look is not a gate that passed.
+         */
+        readonly unchecked: ReadonlyArray<string>;
+        readonly note: string;
+    };
+    readonly notes: ReadonlyArray<string>;
+};
+/**
+ * Compare a stored reference profile against today's.
+ *
+ * Both must carry a drift capture, and today's must have been captured
+ * against the reference's edges — `profileTable`'s `drift.edges` option is
+ * what does that. A column captured any other way is reported without a PSI
+ * and with the reason, which is the only honest thing to return.
+ */
+export declare function compareDrift(reference: TableProfile, current: TableProfile, options: DriftCompareOptions): DriftReport;