API Reference — Statistics and findings engine¶

import { analyzeWaferMap, analyzeWaferLot } from '@wafertools/wafermap/stats';

analyzeWaferMap(input: WaferMapResult | WaferMapInput, options?: AnalyzeWaferMapOptions): StatsSummary

const result  = buildWaferMap({ results, waferConfig, dieConfig, passBins: [1] });
const summary = analyzeWaferMap(result);

// findings is pre-sorted: 'unusual' first, then 'notable', then 'info'
console.log(summary.findings[0]?.summary);
// e.g. "Ring 4 (edge) yield is 18.3 pp lower than the rest of the wafer"

// Pass to renderWaferMap to add a findings panel to the toolbar:
renderWaferMap(container, result, { statsSummary: summary });

const result = buildWaferMap({
  lotStack:    { results: waferResults, method: 'mean' },
  waferConfig, dieConfig, testDefs,
});
const summary = analyzeWaferMap(result);
renderWaferMap(container, result, { statsSummary: summary });
// summary.stats.isLotStack === true
// summary.stats.aggregationMethod === 'mean'

analyzeWaferLot(items: Array<WaferMapResult | WaferMapInput>, options?: AnalyzeWaferMapOptions): LotStatsSummary

const waferResults = waferDataSets.map(d => buildWaferMap(d));
const lotSummary   = analyzeWaferLot(waferResults);

// Per-wafer findings:
console.log(lotSummary.perWafer[0].summary.findings);

// Lot-level findings (regional patterns tested on all wafers combined, repeated
// clusters/edge arcs/spatial patterns, and yield outliers):
console.log(lotSummary.findings);

// Pass to renderWaferGallery to add a lot summary panel to the gallery bar:
renderWaferGallery(container, items, { lotStatsSummary: lotSummary });

{
  // ── Cost switches — every other analysis always runs ──────────────────────
  enableTestValueAnalysis?:       boolean  // default FALSE — expensive regional Welch pass on test values
                                           // (scales with regions × tests × dies). Opt in only when you
                                           // display the regional test-value findings. Implies perTestStats.
                                           // See the Performance guide for measured costs: performance.md
  computePerTestStats?:           boolean  // default false — cheap per-test quartile scan into perTestStats
                                           // (mean/stddev/median/q1/q3) WITHOUT the regional Welch pass.
                                           // Use this for box-plot / histogram panels. Implied by
                                           // enableTestValueAnalysis.

  // ── Test-value scope ──────────────────────────────────────────────────────
  testNumbers?:   number[]  // restrict test-value analysis to these test numbers;
                            // when omitted: all tests up to 250 — beyond that analysis is skipped
                            // and a 'test-count-capped' WaferWarning appears in
                            // summary.stats.warnings[] (§4.2.2) and in the map's
                            // warning indicator

  // ── Angular analysis ──────────────────────────────────────────────────────
  sectorCount?:             number  // sectors for angular analysis: 4 | 8 | 16 (default 8)
}

const estimateMs = waferCount * diesPerWafer * testCount * 0.7 / 1000;

{
  level: 'wafer'
  hasNotableFindings: boolean          // true when any finding is 'notable' or 'unusual'
  findings: StatsFinding[]             // sorted by severity: 'unusual' first, then 'notable', then 'info'
                                       // findings[0] is always the highest-severity finding; no manual sort needed
  wafer?: Record<string, unknown>      // identity fields from waferConfig.metadata (lot, wafer ID, test date, etc.)
  // Note: this `stats` block is analysis metadata; StatsFinding also has its own
  // nested `stats` object (pValue, sampleSizeLeft, etc.) — two distinct sub-objects.
  stats: {
    totalDies:            number        // all dies on the wafer including partial and edge-excluded
    analyzedDies:         number        // dies included in analysis (excludes partial and, by default, edge dies)
    excludedDies:         number        // edge-excluded dies (see edgeDieYieldMode)
    yieldPercent:         number | null // (passDies / analyzedDies) × 100 ∈ [0, 100]
                                        // null when no die in the wafer has an hbin value at all
    testsConsidered:      number[]     // test numbers (keys from testValues) that had enough data
    hardBinsConsidered:   number[]
    softBinsConsidered:   number[]
    hardBinCounts?:  Record<number, number>  // die count per hard bin, over the yield-eligible population
                                              // (excludes partial/edge-excluded dies) — unlike hardBinsConsidered
                                              // above (which bin codes appear at all), these are the actual
                                              // counts a bin-breakdown display should show
    softBinCounts?:  Record<number, number>  // same, for soft bins
    warnings?:            WaferWarning[]  // structured advisories — §4.2.2. Same shape as
                                          // WaferMapResult.warnings, so a host has ONE warning
                                          // vocabulary. Branch on warning.code, e.g.
                                          // 'test-count-capped'. Was string[] before 0.22.0.
    isLotStack?:          boolean      // true when this summary was produced from lot-aggregated (lotStack) data
    aggregationMethod?:   string       // aggregation method used, e.g. 'mean', 'countBin' (present only when isLotStack is true)
    testSpecYield?: Array<{            // one entry per testDef that has at least one limit; absent when no testDefs with limits
      testNumber:   number
      label:        string            // testDef.name
      passDies:     number            // dies with value within [limitLow, limitHigh]
      failLowDies:  number            // dies with value < limitLow (0 when limitLow absent)
      failHighDies: number            // dies with value > limitHigh (0 when limitHigh absent)
      totalDies:    number            // dies that had a value for this test
      yieldPercent: number | null     // (passDies / totalDies) × 100 ∈ [0, 100]; null when totalDies = 0
    }>
    functionalYield?: Array<{         // one entry per functional (testType 'F') test — "functional yield" in fab terms;
                                      // verdicts read via getTestPassStatus (recorded testPass first, then the
                                      // legacy 0/1 testValues fallback); partial/edge-excluded dies excluded
      testNumber:      number
      label:           string         // testDef.name, starting "† " for a derived test
      derived?:        true           // computed from other tests (TestDef.derived) — see §4.1.9
      expression?:     string         // what it was computed from, verbatim
      passDies:        number
      failDies:        number
      totalDies:       number         // dies with a recorded verdict — never counts untested dies as fails
      passRatePercent: number | null  // (passDies / totalDies) × 100 ∈ [0, 100]; null when totalDies = 0
    }>
    perTestStats?: Array<{            // present only when computePerTestStats or enableTestValueAnalysis is set;
                                      // one entry per active test with enough data
      testNumber: number
      label:      string             // testDef.name, or "Test {N}" when no testDef
      count:      number             // number of dies with a value for this test
      min:        number
      max:        number
      mean:       number
      stddev:     number             // sample standard deviation
      median:     number             // 50th percentile (linear interpolation)
      q1:         number             // 25th percentile
      q3:         number             // 75th percentile
    }>
    capability?:     TestCapability[]   // Cp/Cpk/Pp/Ppk per parametric test, worst first; same gate and tests as
                                         // perTestStats. One wafer is one subgroup, so here Cp equals Pp (§7.4.1)
    testFlagYield?:  TestVerdictYield[] // per-test pass rate by the tester's recorded verdict (die.testPass),
                                         // parametric tests with verdicts; worst first (§7.4.1)
    specVerdictDisagreementDies?: number // dies where the spec-limit judgement and the recorded verdict disagree,
                                         // over tests that have both; absent when none has both, 0 = full agreement
    regionYield?:    RegionYieldFigures // yield by ring and by quadrant — the Summary panel's region yield (§7.4.1)
    spatialPattern?: PatternClassification // the pattern classifier's label, confidence and geometry features
                                         // (globalRdd, edgeRdd, centroidDistNorm, eccentricity, linearScore, …)
                                         // for every wafer it could measure — 'random' and 'none' included, which
                                         // raise no finding. Absent with no bin data or too few failing dies
                                         // (fewer than 5, or 0.3% of the wafer). See Pattern Detection
  }
}

// TestCapability
{
  testNumber: number
  label:      string
  unit?:      string
  hasSpec:    boolean        // both limits of one pair defined; when false lsl/usl are absent and every index is null
  lsl?:       number
  usl?:       number
  limitBasis?: 'spec' | 'test' // which pair lsl/usl are: specLow/specHigh when both are given, else limitLow/limitHigh
  mean:       number
  stdOverall: number         // sample stddev (ddof = 1) over every value
  stdWithin:  number         // pooled within-wafer sample stddev; NaN when no wafer contributed ≥ 2 values
  n:          number         // values counted
  cp:  number | null         // use stdWithin; null without a spec or when stdWithin is NaN or 0
  cpk: number | null
  pp:  number | null         // use stdOverall; null without a spec or when stdOverall is 0
  ppk: number | null
}

// TestVerdictYield — same shape as a functionalYield row
{ testNumber: number; label: string; passDies: number; failDies: number; totalDies: number; passRatePercent: number | null }

// RegionYieldFigures
{
  ring?:    RegionYield[]    // absent from a lot whose wafers were built with different ring counts
  quadrant: RegionYield[]
}
// RegionYield
{ key: string; label: string; yieldPercent: number; n: number; passDies: number }   // key is an identity ("ring:2") — do not parse it

{
  level: 'lot'
  hasNotableFindings: boolean
  findings: StatsFinding[]             // lot-level findings (repeated patterns, inter-wafer outliers, and a yield or test-mean trend across the wafers); sorted unusual → notable → info
  lot?: Record<string, unknown>        // identity fields EVERY wafer with identity data agrees on (lot ID, product, etc. —
                                        // wafer-specific keys excluded). A key where wafers disagree (e.g. items pooled
                                        // from more than one lot/program) is omitted here, not silently taken from the
                                        // first wafer — see mixedIdentityFields below.
  mixedIdentityFields?: string[]       // identity keys where the pooled wafers do NOT all agree. Present only when at
                                        // least one such key exists — check this before treating `lot` as describing
                                        // the whole batch.
  stats: {
    waferCount: number
    capability?:      TestCapability[]     // each wafer a subgroup: stdWithin pooled across wafers; absent unless every wafer has it (§7.4.1)
    testSpecYield?:   StatsSummary['stats']['testSpecYield']    // counts summed per test; absent unless every wafer has it
    functionalYield?: StatsSummary['stats']['functionalYield']  // counts summed per test; absent unless every wafer has it
    testFlagYield?:   TestVerdictYield[]   // counts summed per test; absent unless every wafer has it
    specVerdictDisagreementDies?: number   // summed; absent unless every wafer has it
    regionYield?:     RegionYieldFigures   // ring and quadrant counts summed per region; absent unless every wafer has it
  }
  lotYieldSeries: Array<{
    waferIndex:   number
    yieldPercent: number | null        // (passDies / totalDies) × 100 ∈ [0, 100]; null when a wafer had no bin data
  }>
  perWafer: Array<{
    waferIndex: number
    summary: StatsSummary              // per-wafer findings
  }>
  perWaferTestStats?: Array<{          // present only when computePerTestStats or enableTestValueAnalysis is set
                                       // (prefer computePerTestStats — it skips the regional Welch pass)
    waferIndex: number
    tests: Array<{
      testNumber: number
      label:      string
      count:      number
      min:        number
      max:        number
      mean:       number
      stddev:     number
      median:     number
      q1:         number
      q3:         number
    }>
  }>
}

import { renderWaferReportHtml, renderLotReportHtml } from '@wafertools/wafermap/stats';

renderWaferReportHtml(result: ReportMap, summary?: StatsSummary, options?: { title?: string }): string
renderLotReportHtml(results: ReportMap[], options?: { title?: string; analyzeOptions?: AnalyzeWaferMapOptions }): string
// ReportMap: a WaferMapResult (wafer, dies, passBins, ringCount, and optionally hbinDefs/sbinDefs/testDefs),
// plus optional label and statsSummary

const results = files.map(parse).map(buildWaferMap);
fs.writeFileSync('lot-report.html', renderLotReportHtml(results));

import { setReportOpener } from '@wafertools/wafermap/stats';

setReportOpener(opener: (html: string) => void): void

setReportOpener(html => {
  // e.g. write to a host-managed window, invoke an IPC call, etc.
  myApp.showReport(html);
});

{
  id:       string          // stable identifier for this finding
  level:    'wafer' | 'lot' | 'inter-wafer'
  severity: 'unusual' | 'notable' | 'info'
            // ranking (highest → lowest): unusual > notable > info
  variable: {
    kind:   'yield' | 'hardBin' | 'softBin' | 'test' | 'functionalTest' | 'spatialPattern'
    index?: number          // test number — the key from testValues (for 'test' kind)
    bin?:   number          // bin value (for 'hardBin'/'softBin' kind)
    label:  string          // human-readable name; starts "† " for a derived test, as does its name in `summary`
    unit?:  string
    derived?:    true       // the finding is about a derived test (TestDef.derived) — the structured form of the †
    expression?: string     // what that test was computed from, verbatim
  }
  comparison: {
    family: 'ring' | 'quadrant' | 'reticle-position' | 'test-site' | 'wafer'
          | 'sector' | 'cluster' | 'edge-arc' | 'spatial-pattern'
    left:   string          // e.g. "Ring 3 (edge)", "NE", "Rings 1–3", "Reticle cell (1, 0)"
                            // adjacent same-signal regions are merged into one finding (e.g. "Rings 1–3")
    right:  string          // typically "Rest of wafer", or for a yield outlier "Lot median"
                            // (every wafer records one lot) / "Median of all wafers" (otherwise)
  }
  effect: {
    direction:      'higher' | 'lower' | 'different'
    absoluteDelta?: number
    relativeDelta?: number
    effectSize?:    number
  }
  stats: {                   // per-finding test statistics (distinct from StatsSummary.stats)
    method:            string
    pValue?:           number
    adjustedPValue?:   number
    sampleSizeLeft:    number   // dies in the region (left side of comparison)
    sampleSizeRight:   number   // dies in the rest of the wafer (right side)
  }
  summary:   string         // one-sentence human-readable description — a plain string, not an object
                            // e.g. "Ring 4 (edge) yield is 18.3 pp lower than the rest of the wafer"
  highlight: HighlightTarget
  relatedIds?: string[]     // ids of findings this one summarises at a finer level:
                            // a spatial-pattern's supporting regional findings, or the per-region
                            // findings collapsed into a merged band ("Rings 1–3"). Audit/drill-down.
                            // NOTE: these do not all resolve to entries in `findings` — a merged
                            // band names the constituents it REPLACED, and those are gone.
  absorbedIds?: string[]    // ids of findings that state exactly the same fact as this one, hidden
                            // from the Summary panel and the findings report in favour of it.
                            // Unlike relatedIds, everything here IS still in `findings`.
                            // Two cases: a soft-bin finding whose hard-bin twin covers provably the
                            // same dies (merged label reads "Hard and soft bin 3 (same dies)"), and
                            // the single pass bin's row against the yield row restating it.
                            // Merging is on die-set identity, never bin number — hard and soft bins
                            // are independent number spaces.
}

type HighlightTarget =
  | { kind: 'region';  regionFamily: 'ring' | 'quadrant' | 'reticle-position' | 'test-site' | 'sector';
                        regionKeys: string[]; dieKeys?: string[] }
  | { kind: 'bin';     bin: number; regionKeys?: string[]; dieKeys?: string[] }
  | { kind: 'wafer';   waferIndices: number[]; dieKeysByWafer?: Record<number, string[]> }  // a lot regional finding names each counted wafer's region dies
  | { kind: 'dies';    dieKeys: string[] }

import { buildWaferMap } from '@wafertools/wafermap';
import { renderWaferMap } from '@wafertools/wafermap/render';
import { analyzeWaferMap, analyzeWaferLot } from '@wafertools/wafermap/stats';

// Single wafer with summary panel toggle:
const result  = buildWaferMap({ results, waferConfig, dieConfig, passBins: [1] });
const summary = analyzeWaferMap(result);
renderWaferMap(container, result, { statsSummary: summary });

// Lot gallery with lot-level summary panel toggle:
const waferResults = waferDataSets.map(d => buildWaferMap(d));
const items = waferResults.map((r, i) => ({
  ...r,
  label:        `Wafer ${i + 1}`,
  statsSummary: analyzeWaferMap(r),
}));
const lotSummary = analyzeWaferLot(waferResults);
renderWaferGallery(container, items, { lotStatsSummary: lotSummary });

filterFindings(source: StatsSummary | LotStatsSummary, filter: FindingsFilter): StatsFinding[]

import { filterFindings } from '@wafertools/wafermap/stats';

// Unusual ring or quadrant findings only:
const critical = filterFindings(summary, {
  severity: 'unusual',
  family: ['ring', 'quadrant'],
});

// All yield findings across the lot:
const yieldFindings = filterFindings(lotSummary, { kind: 'yield' });

interface FindingsFilter {
  severity?: StatsSeverity | StatsSeverity[]
  kind?:     StatsVariableKind | StatsVariableKind[]
  family?:   StatsComparisonFamily | StatsComparisonFamily[]
  level?:    StatsLevel | StatsLevel[]
}

visibleFindings<T extends { id: string; absorbedIds?: string[] }>(findings: T[]): T[]

import { visibleFindings } from '@wafertools/wafermap/stats';

for (const f of visibleFindings(summary.findings)) { /* … */ }

const summary = analyzeWaferMap(result);
const c = summary.stats.spatialPattern;
if (c) {
  console.log(c.pattern);     // 'edge-ring' | 'center' | 'scratch' | ...
  console.log(c.confidence);  // 'high' | 'medium' | 'low'
  console.log(c.note);        // advisory string when classification may be imprecise
  console.log(c.features);    // raw geometry numbers — usable as input to your own classifier
}

interface PatternClassification {
  pattern:    PatternLabel           // detected pattern
  confidence: 'high' | 'medium' | 'low'
  features:   PatternFeatures        // raw geometry numbers
  note?:      string                 // advisory when classification may be imprecise
}

type PatternLabel =
  | 'center' | 'donut' | 'edge-ring' | 'edge-local'
  | 'scratch' | 'near-full' | 'random' | 'none'

interface PatternFeatures {
  globalRdd:         number  // failing / total eligible dies
  edgeRdd:           number  // failing in outermost ring / total outermost-ring dies
  centroidDistNorm:  number  // distance from wafer centre to salient-region centroid, / radius
  minDistNorm:       number  // min radial distance of salient-region dies, / radius
  maxDistNorm:       number  // max radial distance of salient-region dies, / radius
  p25DistNorm:       number  // 25th-percentile radial distance of all failing dies, / radius
  eccentricity:      number  // 0 = circle, 1 = line (from covariance of top-5 components)
  linearScore:       number  // fraction of top-5 component dies on the best row/col/diagonal
  salienceSize:      number  // die count of the largest connected component
  salienceFraction:  number  // salienceSize / total failing dies
  edgeAngularSpread: number  // fraction of 16 circumference sectors covered by edge-zone fails
  innerOuterRatio:   number  // fail rate inner half / fail rate outer half
}

import { buildFacetTable, facetValueOf, attributeLabel, FACET_NONE_VALUE, mergeTestDefs } from '@wafertools/wafermap/stats';

readPlotsFile(text: string): { plots: PlotSpec[]; warnings: string[]; error?: string }
writePlotsFile(plots: readonly PlotSpec[]): string        // { "format": "wafermap-plots", "version": 1, "plots": [...] }