@actuarial-ts/core 0.7.0 → 0.8.0

package/src/classifications.ts

@@ -0,0 +1,231 @@
+import { canonicalJson } from "./canonical.js";
+import type {
+  AnalysisClassificationDefinition,
+  AnalysisClassificationResult,
+  AnalysisClassifiedStatisticResult,
+  AnalysisDimensionDefinition,
+  AnalysisMeasureDefinitionV1,
+  AnalysisObservationSelection,
+  AnalysisPredicate,
+  ClaimStatusTransition,
+  CustomizationCapabilityFinding,
+  HistoricalScalar,
+  PreparedHistoricalObservation,
+} from "./customizationContracts.js";
+import { snapshotDiagnosticJson } from "./diagnosticRuntime.js";
+import { evaluateAnalysisPredicate, validateAnalysisPredicate } from "./populations.js";
+import { DiagnosticValidationError, type DiagnosticValidationIssue } from "./types.js";
+import { calculateAnalysisStatistic } from "./descriptiveStatistics.js";
+
+function observationDimensions(
+  observation: PreparedHistoricalObservation,
+): Readonly<Record<string, HistoricalScalar | readonly HistoricalScalar[]>> {
+  return {
+    ...observation.dimensions,
+    sourceNamespace: observation.sourceNamespace,
+    claimId: observation.claimId,
+    evaluationDate: observation.evaluationDate,
+    ...(observation.status === null ? {} : { status: observation.status }),
+  };
+}
+
+function finding(message: string, code: CustomizationCapabilityFinding["code"]): CustomizationCapabilityFinding {
+  return { code, capability: "typed-populations", path: "$.classification", message };
+}
+
+function numericMatches(
+  value: number,
+  group: Extract<AnalysisClassificationDefinition, { kind: "numeric-bands" }>["groups"][number],
+): boolean {
+  return (group.minimum === undefined || (group.includeMinimum ? value >= group.minimum : value > group.minimum)) &&
+    (group.maximum === undefined || (group.includeMaximum ? value <= group.maximum : value < group.maximum));
+}
+
+function validateClassification(
+  definition: AnalysisClassificationDefinition,
+  dimensions: readonly AnalysisDimensionDefinition[],
+): void {
+  const issues: DiagnosticValidationIssue[] = [];
+  const ids = definition.kind === "lookup" || definition.kind === "hierarchy"
+    ? []
+    : definition.groups.map((group) => group.id);
+  if (new Set(ids).size !== ids.length)
+    issues.push({ domain: "definition", code: "duplicate-id", path: "$.classification.groups", message: "Classification group IDs must be unique" });
+  if (definition.kind !== "rules") {
+    const dimension = dimensions.find((candidate) => candidate.id === definition.dimensionId);
+    if (dimension === undefined)
+      issues.push({ domain: "definition", code: "unknown-reference", path: "$.classification.dimensionId", message: `Unknown classification dimension ${definition.dimensionId}` });
+    if (definition.kind === "numeric-bands" && dimension?.type !== "number")
+      issues.push({ domain: "definition", code: "incompatible-semantics", path: "$.classification.dimensionId", message: "Numeric bands require a numeric dimension" });
+  }
+  if (definition.kind === "numeric-bands")
+    definition.groups.forEach((group, index) => {
+      if (group.minimum !== undefined && group.maximum !== undefined && group.minimum > group.maximum)
+        issues.push({ domain: "definition", code: "invalid-configuration", path: `$.classification.groups[${index}]`, message: "Classification band minimum exceeds maximum" });
+    });
+  if (definition.kind === "rules")
+    definition.groups.forEach((group) => validateAnalysisPredicate(group.predicate, dimensions));
+  if (issues.length > 0) throw new DiagnosticValidationError(issues);
+}
+
+/** Classifies one observation; allowed overlaps stay explicit and never imply an additive portfolio total. */
+export function classifyAnalysisObservation(input: {
+  readonly definition: AnalysisClassificationDefinition;
+  readonly observation: PreparedHistoricalObservation;
+  readonly dimensions: readonly AnalysisDimensionDefinition[];
+}): AnalysisClassificationResult {
+  validateClassification(input.definition, input.dimensions);
+  const values = observationDimensions(input.observation);
+  let groups: string[] = [];
+  let missing = false;
+  const definition = input.definition;
+  if (definition.kind === "numeric-bands") {
+    const value = values[definition.dimensionId];
+    if (typeof value !== "number") missing = true;
+    else groups = definition.groups.filter((group) => numericMatches(value, group)).map((group) => group.id);
+  } else if (definition.kind === "lookup") {
+    const observed = values[definition.dimensionId];
+    if (observed === undefined || observed === null) missing = true;
+    else {
+      const items = Array.isArray(observed) ? observed : [observed as HistoricalScalar];
+      for (const item of items) {
+        const entry = definition.entries.find((candidate) => canonicalJson(candidate.value) === canonicalJson(item));
+        if (entry !== undefined) groups.push(entry.groupId);
+      }
+    }
+  } else if (definition.kind === "hierarchy") {
+    const observed = values[definition.dimensionId];
+    if (observed === undefined || observed === null) missing = true;
+    else {
+      const items = Array.isArray(observed) ? observed : [observed as HistoricalScalar];
+      for (const item of items) {
+        const entry = definition.entries.find((candidate) => canonicalJson(candidate.value) === canonicalJson(item));
+        if (entry !== undefined) groups.push(...entry.groupIds);
+      }
+    }
+  } else {
+    for (const group of definition.groups) {
+      const outcome = evaluateAnalysisPredicate(group.predicate, values, input.dimensions);
+      if (outcome === "match") groups.push(group.id);
+      if (outcome === "unknown") missing = true;
+    }
+  }
+  groups = [...new Set(groups)].sort();
+  const overlapPolicy = definition.kind === "lookup" || definition.kind === "hierarchy" ? "allow" : definition.overlapPolicy;
+  const gapPolicy = definition.kind === "lookup" || definition.kind === "hierarchy" ? definition.unmappedPolicy : definition.gapPolicy;
+  if (groups.length > 1 && overlapPolicy === "reject")
+    return snapshotDiagnosticJson({ classificationId: definition.id, groupIds: groups, status: "unavailable", overlapping: true, findings: [finding("Classification matched overlapping groups under reject policy", "ambiguous-attribution")] });
+  if (groups.length === 0 && gapPolicy === "reject")
+    return snapshotDiagnosticJson({ classificationId: definition.id, groupIds: [], status: "unavailable", overlapping: false, findings: [finding(missing ? "Classification input is missing" : "Classification matched no group under reject policy", "missing-prerequisite")] });
+  return snapshotDiagnosticJson({ classificationId: definition.id, groupIds: groups, status: groups.length === 0 ? "unclassified" : "classified", overlapping: groups.length > 1, findings: [] });
+}
+
+export type AnalysisPopulationPreset = "reported" | "open" | "reopened" | "closed-with-pay" | "closed-no-pay" | "expense-only";
+
+/** Returns a reusable predicate. Callers may replace every field name with their mapped catalog IDs. */
+export function createAnalysisPopulationPreset(
+  preset: AnalysisPopulationPreset,
+  fields: { readonly status?: string; readonly reportDate?: string; readonly paid?: string; readonly expense?: string } = {},
+): AnalysisPredicate {
+  const status = fields.status ?? "status";
+  const reportDate = fields.reportDate ?? "reportDate";
+  const paid = fields.paid ?? "paid";
+  const expense = fields.expense ?? "expense";
+  if (preset === "reported") return { op: "missing", dimensionId: reportDate, isMissing: false };
+  if (preset === "open") return { op: "in", dimensionId: status, values: ["open", "reopened"] };
+  if (preset === "reopened") return { op: "eq", dimensionId: status, value: "reopened" };
+  if (preset === "closed-with-pay") return { op: "and", terms: [{ op: "eq", dimensionId: status, value: "closed" }, { op: "range", dimensionId: paid, minimum: 0, includeMinimum: false, includeMaximum: false }] };
+  if (preset === "closed-no-pay") return { op: "and", terms: [{ op: "eq", dimensionId: status, value: "closed" }, { op: "eq", dimensionId: paid, value: 0 }] };
+  return { op: "and", terms: [{ op: "range", dimensionId: expense, minimum: 0, includeMinimum: false, includeMaximum: false }, { op: "eq", dimensionId: paid, value: 0 }] };
+}
+
+/** Detects only status changes visible between supplied snapshots; it does not invent event dates. */
+export function detectClaimStatusTransitions(
+  observations: readonly PreparedHistoricalObservation[],
+  closedStatuses: readonly string[] = ["closed"],
+): readonly ClaimStatusTransition[] {
+  const byClaim = new Map<string, PreparedHistoricalObservation[]>();
+  for (const observation of observations) {
+    const key = canonicalJson([observation.sourceNamespace, observation.claimId]);
+    const values = byClaim.get(key) ?? [];
+    values.push(observation);
+    byClaim.set(key, values);
+  }
+  const closed = new Set(closedStatuses);
+  const transitions: ClaimStatusTransition[] = [];
+  for (const history of byClaim.values()) {
+    history.sort((a, b) => a.evaluationDate.localeCompare(b.evaluationDate));
+    for (let index = 1; index < history.length; index += 1) {
+      const prior = history[index - 1]!;
+      const current = history[index]!;
+      if (prior.status === current.status) continue;
+      const kind = closed.has(prior.status ?? "") && !closed.has(current.status ?? "")
+        ? "reopened"
+        : !closed.has(prior.status ?? "") && closed.has(current.status ?? "")
+          ? "closed"
+          : prior.status === null
+            ? "opened"
+            : "other";
+      transitions.push({
+        sourceNamespace: current.sourceNamespace,
+        claimId: current.claimId,
+        fromStatus: prior.status,
+        toStatus: current.status,
+        observedAt: current.evaluationDate,
+        kind,
+        observationPrecision: "between-snapshots",
+      });
+    }
+  }
+  return snapshotDiagnosticJson(transitions);
+}
+
+/**
+ * Calculates each possibly overlapping classification group and calculates
+ * the portfolio independently from the underlying observations. Group totals
+ * are never added together when one observation belongs to multiple groups.
+ */
+export function calculateClassifiedAnalysisStatistics(input: {
+  readonly definition: AnalysisClassificationDefinition;
+  readonly observations: readonly PreparedHistoricalObservation[];
+  readonly dimensions: readonly AnalysisDimensionDefinition[];
+  readonly measure: AnalysisMeasureDefinitionV1;
+  readonly selection: AnalysisObservationSelection;
+}): AnalysisClassifiedStatisticResult {
+  const members = new Map<string, PreparedHistoricalObservation[]>();
+  const findings: CustomizationCapabilityFinding[] = [];
+  let overlapDetected = false;
+  for (const observation of input.observations) {
+    const classified = classifyAnalysisObservation({
+      definition: input.definition,
+      observation,
+      dimensions: input.dimensions,
+    });
+    findings.push(...classified.findings);
+    if (classified.status !== "classified") continue;
+    if (classified.groupIds.length > 1) overlapDetected = true;
+    for (const groupId of classified.groupIds) {
+      const group = members.get(groupId);
+      if (group === undefined) members.set(groupId, [observation]);
+      else group.push(observation);
+    }
+  }
+  const groups = [...members]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([groupId, observations]) => ({
+      groupId,
+      result: calculateAnalysisStatistic({ measure: input.measure, observations, selection: input.selection }),
+    }));
+  return snapshotDiagnosticJson({
+    classificationId: input.definition.id,
+    groups,
+    portfolio: calculateAnalysisStatistic({
+      measure: input.measure,
+      observations: input.observations,
+      selection: input.selection,
+    }),
+    overlapDetected,
+    additiveGroupSumValid: !overlapDetected,
+    findings,
+  });
+}