Skip to content

Upgrading

What to change in your code when a release removes or changes something you use, newest release first. Each release's full list of changes is in the changelog. The reasons for each removal, and whether it could come back, are in API_REMOVALS.md.

0.38.0

The Summary panel docks right or left

summaryPanel: { placement } takes 'right' (the default) or 'left'. 'top' and 'bottom' are removed; a value other than 'left' now docks the panel on the right. If you passed 'top' or 'bottom', pass 'right' or 'left' instead.

0.36.0

Test-value analysis runs by default when it fits a budget

enableTestValueAnalysis defaults to 'auto' (it was false). Within 1,500,000 test values (dies × tests, summed over a lot's wafers) analyzeWaferMap and analyzeWaferLot now return the regional test-value findings and per-test statistics without being asked; above it they skip them, record it in stats.testValueAnalysis, and the renderers offer the analysis to the reader. To keep the old behaviour, pass enableTestValueAnalysis: false. true is no longer capped at 250 tests.

Rotation, mirroring, compact layout and log scale are not preferences

rotation, flipX, flipY, compact and logScale moved from WaferPreferences to WaferDisplayState (WaferViewOptions still has them all), and a change to them is reported as 'state'. If you saved them as preferences, stop: each describes the data on screen. Save the keys in WAFER_PREFERENCE_KEYS instead.

test-count-capped is not raised

Code that looked for that warning should read summary.stats.testValueAnalysis?.state === 'skipped'. If you passed a findingsNotice to offer the analysis yourself, remove it: the renderers show their own offer (a notice you pass still replaces it), and onStatsSummaryChange gives you the summary after the reader runs it. For a big lot in a browser, analyzeWaferLotAsync keeps the page responsive while it analyses.

0.34.0

Pass bins and ring count have no defaults after the build

Bin 1 passes, and there are four rings, only when an input to buildWaferMap states neither. buildWaferMap applies those defaults once and carries the result on the map (result.passBins, result.ringCount); every view, chart, table and report reads the map's own and refuses to state a yield or draw rings without them, instead of falling back to a guess. A map you built with buildWaferMap needs nothing. You are affected only if you call the report or view functions with hand-made data:

  • renderSummaryReport({ ... }) needs passBins and ringCount (a built map has both).
  • renderLotReportHtml takes them per item (a built map carries its own) or as the top-level passBins / ringCount for items that have none; an item with neither is refused with an error naming what is missing.
  • buildView's passBins option is required, and ringCount is required when showRingBoundaries is on.
// before: relied on bin 1 passing
renderSummaryReport({ wafer, dies, yieldSummary, dataCoverage });

// after: state them, or pass the built map's own
renderSummaryReport({ wafer, dies, yieldSummary, dataCoverage, passBins: result.passBins, ringCount: result.ringCount });

If you state pass bins such as [3, 5], a chart or table opened on a selection, a wafer or a gallery card now judges yield by them too, as the map does.

The gallery's stacked modes (stacked values and stacked bins) judge by the pass bins and ring count the wafers share. For wafers built with different ones they are not offered, because a stack of them has no single verdict.

Standard deviation is the sample standard deviation

Every σ the library shows (the Test Values table, per-test statistics, the lot trend, lot drift and the report) divides by n−1, as the capability indices already did. A σ you read from the library is √(n/(n−1)) times the population σ of the same values: about 2.6% at n = 20, negligible on large lots. Exported sampleVariance in stats/math.ts is the single implementation. Exported CSVs carry the same σ.

Sweeps are plots

Sweeps are drawn on the Insights My plots tab, beside your other plots, and the Sweeps tab is gone. Nothing needs changing to keep working: insights.sweeps and insights.onRemoveSweeps still draw, and log a notice the first time. defaultView: 'sweeps' opens the My plots tab.

To move over, give each sweep as a plot, with its id and title on the plot and the rest under sweep:

// before
insights: { sweeps: [{ id: 'power', title: 'Power Sweep', series: [...], xLabel: 'dBm' }] }

// after
insights: { plots: [{ id: 'power', title: 'Power Sweep', chart: 'sweep', sweep: { series: [...], xLabel: 'dBm' } }] }

A sweeps file ({ "format": "tsmap-sweeps", "sweeps": [...] }) is read by readPlotsFile, which returns the same sweep plots, so a host that stored one can pass its text through. The reader can then edit sweeps, save them with the rest of their plots, and keep them across lots. If you supply both a plot and a sweep with the same id, the plot is used.

Insights is on by default

insights.enabled now defaults to true wherever there is a toolbar: always for renderWaferGallery, and for renderWaferMap unless showToolbar is false. A chromeless map stays a plain map. If your app does not want the Map | Insights switch, pass insights: { enabled: false }. Gallery cards are never Insights hosts, and the chart code is still downloaded only when Insights is first opened.

onSaveText can receive a Blob

SaveTextHandler's first argument is now string | Blob. A table of a million cells or more (a lot's die list at 400k dies × 50 tests is 20 million) is written in slices and handed over as a Blob, so no single string holds the whole file. Smaller tables are still a string, saved before the call returns. Handle both:

onSaveText: async (content, filename) => {
  if (typeof content === 'string') return saveString(content, filename);
  await pipeToFile(content.stream(), filename); // or: saveString(await content.text(), filename)
}

A handler that only expects a string (calling .length or .replace on it) fails on a large export.

Right-click on a map always opens the drilldown menu

Right-click on a map, a gallery card or a chart mark used to open the drilldown menu only where there was something to chart, and was otherwise left to the browser or your app. The menu now always has Dies, so your own context menu on those surfaces no longer appears. The toolbar's Chart button is always shown and is labelled "Charts and tables for …". To keep a context menu of your own, attach it to an element outside the map.

The Overview no longer carries the test-values and functional-tests tables

They moved, unchanged, to the Data tab's Statistics view, and the Overview ends with a link to it. Code that clicks the "Test values CSV" or "Functional CSV" button on the Overview should open the Data tab first (data-wmap-insights-tab="data"). The Summary panel's own tables are unchanged, but its CSV buttons are gone: the Data tables button opens the same tables with Export CSV and Copy.

0.32.0

Test values on built dies are read-only

die.testValues and die.testPass on a die from buildWaferMap are now built from the map's columns each time you read them, as a frozen object. Three things follow:

  • Writing fails. die.testValues = … throws a TypeError. The objects are frozen, so die.testValues[1050] = … or delete throws in strict-mode code (ES modules, TypeScript output) and is silently ignored in a classic script. Put the values in the input to buildWaferMap, or make your own copy of the die: { ...die, testValues: { ...die.testValues, 1050: v } }.
  • Each read is a new object, so die.testValues !== die.testValues. Compare values, not objects, and read the object once into a local variable inside a loop over tests.
  • The map no longer shares your input's objects. Changing a record's testValues after the build does not change the map; build again.

A spread, structuredClone or JSON.stringify of a built die gives ordinary objects with the same values. Dies you build yourself keep ordinary objects.

Input values of the wrong type are left out

A bin, site number or test value that is not a number (for example the string "3"), or a verdict that is not true/false, is now treated as missing, the same as a value outside the STDF V4 ranges. It is still reported as the input-values-not-numbers warning. If your data can carry numbers as strings, convert them before calling buildWaferMap: a die whose only bin was text now has no verdict instead of counting as a fail, which can change yield. Pre-built dies get the same checks as results, and a pre-built die whose coordinates STDF cannot store becomes an unpositioned die.

renderWaferGallery now draws a card's canvas only while the card is on (or near) the screen; the rest are drawn as they scroll into view. The gallery's own PNG, printing and a card's own PNG draw every card first, so they always show the whole gallery. If your app captures the cards itself — reading a card's <canvas> with toDataURL, or screenshotting the page with a tool such as html2canvas — cards that have not been on screen are blank: scroll them into view first, or use the gallery's own PNG export.

WaferMapResult.view is removed

view was marked @internal, and the renderers build their own draw list whenever they draw. If your code read result.view.plotMode, result.view.metadata or similar, read the same field on the result itself: result.plotMode, result.metadata, result.isLotStack, result.hbinDefs, result.sbinDefs, result.testDefs. There is no replacement for the draw list itself (rectangles, hoverPoints, overlays): draw with renderWaferMap or renderWaferGallery.

0.31.0

Removed exports

0.31.0 removes 74 exports: the 73 deprecated in 0.30.0 and renderFindingsReportHtml, deprecated in 0.30.3. Each one logged a console notice naming its replacement on first use. If your code calls buildWaferMap, renderWaferMap, renderWaferGallery, analyzeWaferMap and analyzeWaferLot, and imports none of the names below, you have nothing to change here.

To check: search your imports from @wafertools/wafermap for the names in these tables. In TypeScript, each one is now a compile error at the import.

Colours

Removed Use instead
resolveBinColors binColorsForMaps(results), which reads each map's own pass bins, or getBinColors() on a WaferMapController or GalleryController
getBinColorScheme binColorsForMaps(results): the colours a map actually draws
valueToViridis, valueToGreyscale resolveValueColorFn('default'), resolveValueColorFn('greyscale')
getValueColorScheme resolveValueColorFn(name, reversed) to colour by value; listValueColorSchemes() for names and labels
contrastTextColor none: the renderers choose label colours themselves
// Before
const colours = resolveBinColors(result.dies, { passBins: [1, 5] });

// After: pass bins come from the result
const colours = binColorsForMaps(result);          // one map
const lotColours = binColorsForMaps(results);      // several, resolved together

Figures for your own tables, exports and charts

Every figure the charts, Summary panel and reports show comes back from the analysis. Options such as computePerTestStats are on analyzeWaferMap and analyzeWaferLot.

Removed Use instead
buildYieldData, buildYieldDataCombined lotYieldSeries on analyzeWaferLot's result; stats.yieldPercent on each summary
buildBinParetoData, buildBinClusterData stats.hardBinCounts and stats.softBinCounts, on the wafer summary or on each perWafer entry of a lot summary
buildCapabilityData stats.capability (enable computePerTestStats)
buildTestBoxplotData stats.perTestStats (enable computePerTestStats); perWaferTestStats on a lot summary
buildTestTrendData, trendCentre perWaferTestStats on analyzeWaferLot's result, in slot order
buildTestPassRateData, hasJudgeableTests stats.testSpecYield (test limits), stats.testFlagYield (tester verdicts), stats.functionalYield, and stats.specVerdictDisagreementDies
computeFunctionalYield stats.functionalYield
buildRegionYieldData, buildRingRegions, buildQuadrantRegions stats.regionYield.ring and stats.regionYield.quadrant
buildSectorRegions, buildReticlePositionRegions, buildTestSiteRegions, areQuadrantsAdjacent, sectorCompassNames, parseRegionKey the findings: each names its region in comparison.left. Region keys are identities; do not parse them
classifyPattern stats.spatialPattern: label, confidence and geometry features, for every wafer
classifyDie, getRingLabel ring and quadrant yield in stats.regionYield; a die's ring and quadrant in the die list's CSV export
buildTestHistogramData, buildTestHistogramSeries, buildScatterData, buildScatterDataGrouped, buildCorrelationMatrix, filterCorrelationMatrix none: these prepared data for the Insights charts, which the renderers draw (insights: { enabled: true }). If you need correlations as data, ask
// Before
const yieldData = buildYieldData(items, [1]);

// After
const lot = analyzeWaferLot(results);
lot.lotYieldSeries;                  // [{ waferIndex, yieldPercent }, …]
lot.perWafer[0].summary.stats.regionYield.quadrant;   // [{ key, label, yieldPercent, n, passDies }, …]

Reports

Removed Use instead
renderSummaryReportHtml renderWaferReportHtml(result, summary?)
renderLotSummaryReportHtml renderLotReportHtml(results)
renderFindingsReportHtml renderWaferReportHtml or renderLotReportHtml: their Findings section is the same table
openHtmlReport openReportModal(html), or setReportOpener to route reports into your app

Both report builders read pass bins and ring count from the built maps, so there is nothing to keep in step.

Die layouts and geometry

Removed Use instead
createWafer, generateDies, clipDiesToWafer buildWaferMap({ layout: true, waferConfig, dieConfig }) for a die layout with no test data
STANDARD_WAFER_DIAMETERS_MM buildWaferMap's standardDiameters; the default is [100, 125, 150, 200, 300]
resolveGridPitch each built die's width and height carry the pitch buildWaferMap resolved
aggregateValues, aggregateBinCounts, getUniqueBins buildWaferMap's lotStack option
isPositionedDie hasPosition
// Before
const wafer = createWafer({ diameter: 300 });
const dies = clipDiesToWafer(generateDies(wafer, { width: 10, height: 10 }), wafer, { width: 10, height: 10 });

// After
const layout = buildWaferMap({
  layout: true,
  waferConfig: { diameter: 300 },
  dieConfig: { width: 10, height: 10 },
});
renderWaferMap(container, layout);

Small helpers

Removed Use instead
getDieTestValue(die, n) die.testValues?.[n]
dieHasTestData none: buildWaferMap, the analysis and the renderers apply it themselves
isParametricTest(def) def.testType !== 'F'
metadataCategoricalValue metadataDisplayValue
DEFAULT_FACET_CURATION buildFacetTable applies it by default; its curation option layers over it
buildDieListSection the maps show the die list themselves (the dieList option)

The low-level drawing pipeline

buildView, toCanvas, buildHoverText, buildMapTitle, applyOrientation, transformDies, isInsideWafer, generateReticleGrid, applyProbeSequence, mapDataToDies and the affine* helpers are removed with no direct replacement. Build with buildWaferMap and draw with renderWaferMap or renderWaferGallery. If you drew maps yourself (to SVG, a server-side image or another canvas library), say what you need in an issue.

Options

Removed or changed What to do
downloadFilename (changed) It is now a prefix for every file a map or gallery saves, CSVs included: LOT123_sort gives LOT123_sort_W05_hard-bin.png, not LOT123_sort.png. If your onSaveImage or onSaveText matches the name it receives, match on the prefix.
buildWaferMap's second argument (WaferMapOptions) Set the starting plot mode and other view options on the renderer: renderWaferMap(container, result, { viewOptions: { plotMode: 'value' } }). The second argument only set the initial result.plotMode, and the Web Worker never passed it.
WaferViewOptions.showPartialDies Remove it. No map buildWaferMap builds has partial dies, so it had nothing to act on. A saved preference that still carries it is ignored.
isYieldEligibleDie's includePartial Remove it. Partial dies are always left out of yield; includeEdgeExcluded is unchanged.

Types

The types that belonged only to removed functions are removed with them. The types of everything that remains, such as WaferMapResult, StatsSummary and RenderOptions, are unchanged.

Removed with Types
The chart-data builders CapabilityDatum, CapabilityItem, CorrelationTestInfo, CorrelationCell, CorrelationMatrix, CorrelationSummary, BoxplotDatum, BoxplotItem, TrendDatum, TrendItem, TestPassKind, TestPassRateData, TestPassRateItem, TestPassRateRow, TestPassRateValue, HistogramBucket, HistogramItem, HistogramSeries, HistogramSeriesData, ScatterPoint, ScatterItem, ChartDatum, YieldItem, YieldSortBy, BinType, BinItem, BinCluster, BinClusterData
The region builders StatsRegion, RegionYieldDatum, ParsedRegionKey
The drawing pipeline and geometry helpers View, ViewOptions, ViewRect, ViewText, ViewOverlay, ViewHoverPoint, WaferMapOptions, ToCanvasResult, HitTarget, MapTitleParts, WaferSpec, WaferNotch, DieSpec, PositionedDie, ReticleSpec, ProbeSequenceConfig, TransformOptions, DataRow, MapOptions, Quadrant, DieClassification, ClassifyOptions, AggregationMethod, DieLike, PitchResult
The other helpers BinColorOptions, DieListOptions, LotSummaryReportParams, MetadataColumn, MetadataColumnScope, MetadataColumnSet, ResolveMetadataColumnsOptions

STDF value ranges

0.30.4 warned about values STDF V4 cannot store (input-values-outside-stdf) and used them as given. 0.31.0 treats them as missing. If that warning appeared on your data, the map now differs:

Value Legal Outside the range
hbin, sbin whole numbers 0–32767 the die has no bin — neither pass nor fail
x, y whole numbers −32767 to 32767 the die has no position, and is listed rather than drawn
test numbers (testValues/testPass keys, TestDef.testNumber, derived tests) whole numbers 0–4294967295 the test is left out
test values finite numbers the value is left out
siteNum 0–255 the die has no site
waferConfig.orientation 0, 90, 180, 270 (or an equivalent such as −90) the map is built at 0

Fix the data at its source, or convert it before building. A coordinate given as 1.5 is the usual cause of a map losing its dies' positions: pass whole prober steps.