@actuarial-ts/core 0.1.0 → 0.3.0

package/src/mack.ts

@@ -0,0 +1,329 @@
+import type { MackResult, MackRow, Triangle } from "./types.js";
+import { ReservingError } from "./types.js";
+import { isNum, lastObservedIndex } from "./util.js";
+
+export interface MackOptions {
+  /**
+   * Per-column selected LDFs (null = unselected, treated as 1.000 exactly
+   * like the chain ladder does). When omitted the projection uses the
+   * volume-weighted factors, which is Mack (1993) as published.
+   */
+  selected?: (number | null)[];
+  /** Multiplicative tail factor beyond the last observed age (1 = none). */
+  tailFactor?: number;
+}
+
+/**
+ * Mack (1993) distribution-free chain ladder standard errors, alpha = 1,
+ * extended per Mack (1999) to selected development factors and a tail:
+ *
+ * - f_k    = sum(C_{i,k+1}) / sum(C_{i,k}) over rows with both cells observed
+ * - s^2_k  = 1/(n_k - 1) * sum C_{i,k} (F_{ik} - f_k)^2, always estimated
+ *   around the volume-weighted f_k (the data-driven estimator) even when
+ *   the projection uses selected factors
+ * - s^2 for the final column is extrapolated per Mack:
+ *   min(s^4_{K-2}/s^2_{K-3}, min(s^2_{K-3}, s^2_{K-2}))
+ * - se(R_i)^2 = C_ult^2 * sum_k (s^2_k / f*_k^2) (1/C_ik + 1/sum_j C_jk)
+ *   with f* the projection factors and projected C below the diagonal
+ * - a tail step (tailFactor > 1) extends the sum by one column, with s^2
+ *   extrapolated once more by the same rule and the final column's volume
+ *   as its denominator - an approximation, flagged in warnings
+ * - the total includes Mack's cross-covariance term between accident years
+ */
+/**
+ * Mack's base estimators: volume-weighted development factors f_k, their
+ * column volumes (sum of C_{i,k} over the rows used), the per-column pair
+ * counts, and the DATA-ESTIMATED sigma^2_k (null where fewer than two
+ * factors exist — extrapolation is runMack's business, not the estimator's).
+ * Shared by runMack and the residual diagnostics so the two can never drift.
+ */
+export function mackEstimators(tri: Triangle): {
+  f: number[];
+  denomSums: number[];
+  counts: number[];
+  sigma2: (number | null)[];
+} {
+  const n = tri.origins.length;
+  const K = tri.ages.length;
+  if (K < 2) {
+    throw new ReservingError("TOO_SMALL", "Mack requires at least two development ages");
+  }
+  const f: number[] = [];
+  const denomSums: number[] = [];
+  const counts: number[] = [];
+  for (let k = 0; k < K - 1; k++) {
+    let num = 0;
+    let den = 0;
+    let count = 0;
+    for (let i = 0; i < n; i++) {
+      const c0 = tri.values[i]![k] ?? null;
+      const c1 = tri.values[i]![k + 1] ?? null;
+      if (isNum(c0) && isNum(c1) && c0 > 0) {
+        num += c1;
+        den += c0;
+        count++;
+      }
+    }
+    if (den <= 0) {
+      throw new ReservingError(
+        "NO_FACTOR",
+        `Development column ${tri.ages[k]}-${tri.ages[k + 1]} has no usable factors for Mack`,
+      );
+    }
+    f.push(num / den);
+    denomSums.push(den);
+    counts.push(count);
+  }
+  const sigma2: (number | null)[] = new Array(K - 1).fill(null);
+  for (let k = 0; k < K - 1; k++) {
+    let sum = 0;
+    let count = 0;
+    for (let i = 0; i < n; i++) {
+      const c0 = tri.values[i]![k] ?? null;
+      const c1 = tri.values[i]![k + 1] ?? null;
+      if (isNum(c0) && isNum(c1) && c0 > 0) {
+        const F = c1 / c0;
+        sum += c0 * (F - f[k]!) ** 2;
+        count++;
+      }
+    }
+    sigma2[k] = count > 1 ? sum / (count - 1) : null;
+  }
+  return { f, denomSums, counts, sigma2 };
+}
+
+/**
+ * Mack's sigma^2 extrapolation for columns the data cannot estimate (fewer
+ * than two observed factors - usually only the final column):
+ * sigma^2_k = min(sigma^4_{k-1} / sigma^2_{k-2}, sigma^2_{k-2}, sigma^2_{k-1}),
+ * Mack (1993), also eq. (4.1) of Merz-Wuthrich (2008). Shared by runMack and
+ * runMerzWuthrich so the two can never disagree on the final column.
+ *
+ * Takes the raw per-column estimates (null = not estimable) and returns the
+ * completed array; when the min-rule inputs are unavailable it falls back to
+ * the prior column's value, then 0, pushing a warning either way.
+ */
+export function extrapolateSigma2(
+  sigma2Raw: (number | null)[],
+  ages: number[],
+  warnings: string[],
+): number[] {
+  const sigma2: number[] = sigma2Raw.map((s) => (s === null ? NaN : s));
+  for (let k = 0; k < sigma2.length; k++) {
+    if (!Number.isNaN(sigma2[k]!)) continue;
+    const s2a = k >= 2 ? sigma2[k - 2]! : NaN;
+    const s2b = k >= 1 ? sigma2[k - 1]! : NaN;
+    if (isNum(s2a) && isNum(s2b) && s2a > 0) {
+      sigma2[k] = Math.min((s2b * s2b) / s2a, Math.min(s2a, s2b));
+    } else if (isNum(s2b)) {
+      sigma2[k] = s2b;
+      warnings.push(
+        `sigma^2 for the ${ages[k]}-${ages[k + 1]} column could not use Mack's extrapolation; reused the prior column's value`,
+      );
+    } else {
+      sigma2[k] = 0;
+      warnings.push(
+        `sigma^2 for the ${ages[k]}-${ages[k + 1]} column is not estimable; set to 0 (standard errors understated)`,
+      );
+    }
+  }
+  return sigma2;
+}
+
+export function runMack(tri: Triangle, options: MackOptions = {}): MackResult {
+  const n = tri.origins.length;
+  const K = tri.ages.length;
+  const warnings: string[] = [];
+
+  const estimators = mackEstimators(tri);
+  const f = estimators.f;
+  const denomSums = estimators.denomSums;
+
+  // Projection factors: the caller's selections when provided (nulls and
+  // non-positive values become 1.000, mirroring the chain ladder), else the
+  // volume-weighted estimates - which reproduces Mack (1993) exactly.
+  let fEff: number[] = f;
+  if (options.selected !== undefined) {
+    if (options.selected.length !== K - 1) {
+      throw new ReservingError(
+        "SELECTION_SHAPE",
+        `Expected ${K - 1} LDF selections (one per development interval), got ${options.selected.length}`,
+      );
+    }
+    fEff = options.selected.map((s, k) => {
+      if (s === null || s === undefined) return 1;
+      if (!isNum(s) || s <= 0) {
+        warnings.push(
+          `Selected LDF for ${tri.ages[k]}-${tri.ages[k + 1]} months is not positive; treated as 1.000`,
+        );
+        return 1;
+      }
+      return s;
+    });
+    const differs = fEff.some((v, k) => Math.abs(v - f[k]!) > 1e-9);
+    if (differs) {
+      warnings.push(
+        "Standard errors pair the selected development factors with sigma^2 estimated around the volume-weighted factors (Mack 1999)",
+      );
+    }
+  }
+  const tail = options.tailFactor ?? 1;
+  if (!isNum(tail) || tail <= 0) {
+    throw new ReservingError("BAD_TAIL", "Tail factor must be a positive number");
+  }
+
+  // sigma^2_k estimates: data-estimated where possible; Mack's extrapolation
+  // fills columns with a single factor (usually the last).
+  const sigma2 = extrapolateSigma2(estimators.sigma2, tri.ages, warnings);
+
+  // Tail step variance: extrapolate sigma^2 one more column by Mack's rule
+  // and reuse the final column's volume as its denominator (approximation).
+  let sigma2Tail = 0;
+  let denomTail = 0;
+  if (tail !== 1) {
+    const s2a = K >= 3 ? sigma2[K - 3]! : NaN;
+    const s2b = sigma2[K - 2]!;
+    if (isNum(s2a) && isNum(s2b) && s2a > 0) {
+      sigma2Tail = Math.min((s2b * s2b) / s2a, Math.min(s2a, s2b));
+    } else if (isNum(s2b)) {
+      sigma2Tail = s2b;
+    }
+    denomTail = denomSums[K - 2]!;
+    warnings.push(
+      "The tail step's standard-error contribution extrapolates sigma^2 beyond the observed columns and reuses the final column's volume; treat it as approximate (Mack 1999)",
+    );
+  }
+
+  // Project the full rectangle with the projection factors.
+  const projected: number[][] = tri.values.map((row) => {
+    const out: number[] = new Array(K).fill(NaN);
+    const last = lastObservedIndex(row);
+    for (let j = 0; j <= last; j++) out[j] = row[j] ?? NaN;
+    for (let j = last + 1; j < K; j++) out[j] = out[j - 1]! * fEff[j - 1]!;
+    return out;
+  });
+
+  const rows: MackRow[] = [];
+  const mseByRow: number[] = new Array(n).fill(0);
+  for (let i = 0; i < n; i++) {
+    const last = lastObservedIndex(tri.values[i]!);
+    if (last < 0) continue;
+    const latest = tri.values[i]![last]!;
+    const ultimate = projected[i]![K - 1]! * tail;
+    // mse(R_i) accumulated over the projected development range plus tail.
+    let mse = 0;
+    let droppedColumns = 0;
+    for (let k = last; k < K - 1; k++) {
+      const cik = projected[i]![k]!;
+      if (!(cik > 0)) {
+        // Mack's 1/C_ik is undefined for a non-positive cumulative. Skipping
+        // the column is the only defensible arithmetic, but it removes real
+        // variance from the estimate, so the result must not present what
+        // remains as if it were the whole story.
+        droppedColumns++;
+        continue;
+      }
+      mse += (sigma2[k]! / fEff[k]! ** 2) * (1 / cik + 1 / denomSums[k]!);
+    }
+    if (droppedColumns > 0) {
+      warnings.push(
+        `Origin ${tri.origins[i]} has a non-positive projected cumulative at ` +
+          `${droppedColumns} development step(s); those columns are excluded from its ` +
+          `standard error, which is therefore understated`,
+      );
+    }
+    if (tail !== 1 && projected[i]![K - 1]! > 0) {
+      mse += (sigma2Tail / tail ** 2) * (1 / projected[i]![K - 1]! + 1 / denomTail);
+    }
+    mse *= ultimate ** 2;
+    mseByRow[i] = mse;
+    const reserve = ultimate - latest;
+    rows.push({
+      origin: tri.origins[i]!,
+      latest,
+      ultimate,
+      reserve,
+      standardError: Math.sqrt(mse),
+      cv: reserve !== 0 ? Math.sqrt(mse) / reserve : null,
+    });
+  }
+
+  // Total mse: sum of row mse plus the cross-covariance between every PAIR of
+  // accident years (Mack 1993 corollary). The tail step participates like one
+  // more development column.
+  //
+  // Two accident years share estimation error only over the columns they have
+  // BOTH yet to traverse, so each pair's sum starts at the maturity of the more
+  // developed of the two. That floor is per-pair: aggregating the later rows'
+  // ultimates before choosing it would assume maturity falls with row index —
+  // true of a tidy run-off triangle, false of a ragged or unsorted one, and the
+  // resulting total moved by up to 65% purely with row order.
+  let totalMse = 0;
+  for (let i = 0; i < n; i++) totalMse += mseByRow[i]!;
+
+  const maturity = tri.values.map((row) => lastObservedIndex(row));
+  const ultimateOf = (i: number): number => projected[i]![K - 1]! * tail;
+
+  for (let i = 0; i < n; i++) {
+    if (maturity[i]! < 0) continue;
+    // Mack's 1/C terms are undefined for a non-positive ultimate; the row
+    // estimate skips such columns for the same reason (see above).
+    const ui = ultimateOf(i);
+    if (!(ui > 0)) continue;
+
+    // Partners are grouped by the floor their pair uses, and each group's
+    // ultimates are summed BEFORE multiplying. On a triangle whose maturity
+    // falls with row index every partner shares one floor, so this collapses
+    // to a single product in the original operand order — the arithmetic is
+    // then identical to the last bit, which is what keeps the frozen
+    // conformance corpus reproducible.
+    const partnerUltimatesByFloor = new Map<number, number>();
+    for (let j = i + 1; j < n; j++) {
+      if (maturity[j]! < 0) continue;
+      const uj = ultimateOf(j);
+      if (!(uj > 0)) continue;
+      const floor = Math.max(maturity[i]!, maturity[j]!);
+      partnerUltimatesByFloor.set(floor, (partnerUltimatesByFloor.get(floor) ?? 0) + uj);
+    }
+
+    for (const [floor, partnerUltimates] of partnerUltimatesByFloor) {
+      // Both years already run off: no shared development remains.
+      if (tail === 1 && floor >= K - 1) continue;
+
+      let shared = 0;
+      for (let k = floor; k < K - 1; k++) {
+        shared += (2 * sigma2[k]!) / fEff[k]! ** 2 / denomSums[k]!;
+      }
+      if (tail !== 1) {
+        shared += (2 * sigma2Tail) / tail ** 2 / denomTail;
+      }
+
+      totalMse += ui * partnerUltimates * shared;
+    }
+  }
+
+  const totals = rows.reduce(
+    (acc, r) => ({
+      latest: acc.latest + r.latest,
+      ultimate: acc.ultimate + r.ultimate,
+      reserve: acc.reserve + r.reserve,
+    }),
+    { latest: 0, ultimate: 0, reserve: 0 },
+  );
+  const totalSe = Math.sqrt(totalMse);
+
+  return {
+    method: "mack",
+    developmentFactors: fEff,
+    sigmaSquared: sigma2,
+    tailFactor: tail,
+    sigmaSquaredTail: tail !== 1 ? sigma2Tail : undefined,
+    rows,
+    totals: {
+      ...totals,
+      standardError: totalSe,
+      cv: totals.reserve !== 0 ? totalSe / totals.reserve : null,
+    },
+    warnings,
+  };
+}

package/src/merzWuthrich.ts

@@ -0,0 +1,147 @@
+import type { MerzWuthrichResult, MerzWuthrichRow, Triangle } from "./types.js";
+import { ReservingError } from "./types.js";
+import { extrapolateSigma2, mackEstimators, runMack } from "./mack.js";
+import { isNum } from "./util.js";
+
+/**
+ * Merz-Wuthrich (2008) one-year claims development result (CDR) msep.
+ *
+ * Source: Merz, M. & Wuthrich, M.V. (2008), "Modelling the Claims Development
+ * Result for Solvency Purposes", CAS E-Forum Fall 2008, 542-568. Implements
+ * Result 3.5's closed forms: eq. (3.17) per accident year and eq. (3.18) for
+ * the aggregate - the msep of the observable one-year CDR around 0, i.e. the
+ * Solvency II / SST one-year reserve-risk quantity. Everything is computable
+ * at time I from the observed triangle D_I alone: S_j^{I+1} = S_j^I +
+ * C_{I-j,j} adds only the current diagonal element, which is in D_I.
+ *
+ * Estimators are shared with runMack - volume-weighted fhat_j and Mack's
+ * sigma^2_j with the min-rule extrapolation for the final column, which is
+ * exactly the paper's eq. (4.1) - and Mack's full-runoff msep is computed via
+ * runMack so every row carries the one-year vs ultimate-view comparison.
+ *
+ * Constraints (Sec. 2 of the paper): the closed forms assume a regular
+ * run-off triangle with I = J - as many origin periods as development ages,
+ * every cell on or left of the latest diagonal observed and positive, and
+ * nothing observed beyond it. Violations throw ReservingError("SHAPE").
+ *
+ * Caveat: (3.17)/(3.18) are the paper's linear approximations (Appendix A)
+ * of the exact product-form formulas. They are the published, industry-
+ * standard form (the paper's Table 4 is produced by them), accurate when
+ * sigma^2_j / (fhat_j^2 C_{i,j}) << 1, which holds for typical triangles.
+ */
+export function runMerzWuthrich(tri: Triangle): MerzWuthrichResult {
+  const n = tri.origins.length;
+  const K = tri.ages.length;
+  if (n !== K) {
+    throw new ReservingError(
+      "SHAPE",
+      `Merz-Wuthrich requires a square triangle (I = J): got ${n} origin periods by ${K} development ages`,
+    );
+  }
+  // Regularity: every cell on or left of the time-I diagonal must be observed
+  // and positive (the formulas divide by diagonal cells and the variance
+  // assumption needs C > 0); nothing may be observed beyond the diagonal.
+  for (let i = 0; i < n; i++) {
+    const row = tri.values[i] ?? [];
+    const diag = K - 1 - i;
+    for (let j = 0; j <= diag; j++) {
+      const v = row[j] ?? null;
+      if (!isNum(v) || v <= 0) {
+        throw new ReservingError(
+          "SHAPE",
+          `Merz-Wuthrich requires every cell on or left of the latest diagonal to be observed and positive: origin ${tri.origins[i]} at age ${tri.ages[j]} months is ${isNum(v) ? "non-positive" : "missing"}`,
+        );
+      }
+    }
+    for (let j = diag + 1; j < K; j++) {
+      if (isNum(row[j] ?? null)) {
+        throw new ReservingError(
+          "SHAPE",
+          `Merz-Wuthrich assumes a time-I snapshot: origin ${tri.origins[i]} has an observation beyond the latest diagonal at age ${tri.ages[j]} months`,
+        );
+      }
+    }
+  }
+
+  const warnings: string[] = [];
+  const estimators = mackEstimators(tri);
+  const f = estimators.f;
+  // S_j^I (2.9): column-j volume EXCLUDING the diagonal element C_{I-j,j}.
+  const sI = estimators.denomSums;
+  const sigma2 = extrapolateSigma2(estimators.sigma2, tri.ages, warnings);
+  const I = K - 1; // = J; row i's latest observed cell is column I - i.
+
+  // sjr(j) = sigmahat_j^2 / fhat_j^2, the paper's recurring ratio.
+  const sjr = sigma2.map((s2, j) => s2 / f[j]! ** 2);
+  // S_j^{I+1} = S_j^I + C_{I-j,j} (2.10): INCLUDES the diagonal element.
+  const sIPlus1 = sI.map((s, j) => s + tri.values[I - j]![j]!);
+
+  // Chain ladder ultimates Chat_{i,J}^I (2.11).
+  const ultimates: number[] = tri.values.map((row, i) => {
+    let u = row[I - i]!;
+    for (let j = I - i; j < I; j++) u *= f[j]!;
+    return u;
+  });
+
+  // Mack's ultimate-view msep on the identical estimators, for comparison.
+  const mack = runMack(tri);
+
+  const rows: MerzWuthrichRow[] = [];
+  const msepByRow: number[] = new Array(n).fill(0);
+  // Estimation-error piece shared by (3.17) and (3.18)'s cross terms:
+  // sjr(I-i)/S_{I-i}^I + sum_{j=I-i+1}^{J-1} (C_{I-j,j}/S_j^{I+1}) sjr(j)/S_j^I
+  // (FIRST power of C_{I-j,j}/S_j^{I+1} - the Delta and Phi tails merge).
+  const estimationTerm: number[] = new Array(n).fill(0);
+  let totalReserve = 0;
+  for (let i = 0; i < n; i++) {
+    const d = I - i;
+    if (i > 0) {
+      let laterDiagonals = 0;
+      for (let j = d + 1; j <= I - 1; j++) {
+        laterDiagonals += (tri.values[I - j]![j]! / sIPlus1[j]!) * (sjr[j]! / sI[j]!);
+      }
+      estimationTerm[i] = sjr[d]! / sI[d]! + laterDiagonals;
+      // (3.17): process term sjr(I-i)/C_{i,I-i} plus the estimation term.
+      msepByRow[i] = ultimates[i]! ** 2 * (sjr[d]! / tri.values[i]![d]! + estimationTerm[i]!);
+    }
+    // i = 0 is fully developed: its CDR is identically 0 (the paper prints
+    // this row with reserve 0 and blank volatility cells).
+    const cdrMsepRoot = Math.sqrt(msepByRow[i]!);
+    const mackMsepRoot = mack.rows[i]!.standardError;
+    const reserve = ultimates[i]! - tri.values[i]![d]!;
+    totalReserve += reserve;
+    rows.push({
+      origin: tri.origins[i]!,
+      reserve,
+      cdrMsepRoot,
+      mackMsepRoot,
+      oneYearRatio: mackMsepRoot > 0 ? cdrMsepRoot / mackMsepRoot : null,
+    });
+  }
+
+  // (3.18): aggregate = sum of the single-year mseps plus cross terms
+  // 2 * Chat_i * Chat_k over 0 < i < k <= I, each scaled by the estimation
+  // term of the EARLIER accident year i.
+  let totalMsep = msepByRow.reduce((a, b) => a + b, 0);
+  for (let i = 1; i < n; i++) {
+    let laterUltimates = 0;
+    for (let k = i + 1; k < n; k++) laterUltimates += ultimates[k]!;
+    totalMsep += 2 * ultimates[i]! * laterUltimates * estimationTerm[i]!;
+  }
+
+  const totalCdrMsepRoot = Math.sqrt(totalMsep);
+  const totalMackMsepRoot = mack.totals.standardError;
+  return {
+    method: "merzWuthrich",
+    developmentFactors: f,
+    sigmaSquared: sigma2,
+    rows,
+    totals: {
+      reserve: totalReserve,
+      cdrMsepRoot: totalCdrMsepRoot,
+      mackMsepRoot: totalMackMsepRoot,
+      oneYearRatio: totalMackMsepRoot > 0 ? totalCdrMsepRoot / totalMackMsepRoot : null,
+    },
+    warnings,
+  };
+}