Notebook Execution

Use Notebooks to work with lot measurements in Python. The server prepares pandas frames for your scope; cells can use pandas, NumPy, DuckDB, SciPy, scikit-learn, PyArrow, and Plotly. You do not need a local Python installation.

Choose a scope and run a cell

1. Open Notebooks, select a lot, and open an editable notebook or start a draft. Check that the status says server runtime ready. Execution requires editor access and a configured server runtime.
2. Open Show Setup if the setup details are hidden. For an Analyze selection, choose Attach Current Live Scope, or choose an analysis and version under Saved Analysis, then Attach Saved Scope.
3. Check Current Scope, including the lot, snapshot, selected dies, and limits. Run the cell below with its run button or Shift+Enter.

show(analysis_scope)
show({
    "attached_rows": len(scope_test_results),
    "source_artifact_rows": scope_test_results.attrs["stratum_source_row_count"],
    "sampled": scope_test_results.attrs["stratum_sampled"],
    "scope_status": scope_test_results.attrs["stratum_scope_status"],
})

Use Analyze in the same tab before attaching its live scope. The button uses that tab’s Analyze state, not a selection in another tab. To use work saved elsewhere, select its analysis and version under Saved Analysis instead. The list is for the chosen lot; attaching a saved scope also adopts that version’s snapshot.

Attaching the live scope captures it at that point; it is not a subscription to later brushes in Analyze. Attach again to use a changed selection or limits. Detach Analyze Scope returns to the chosen lot/snapshot without that explicit selection or scenario. It does not remove the lot’s data attachment.

Existing cell outputs can remain visible after an attachment changes. Rerun the cells before using their results for the new scope. server runtime ready reports service availability, not your permission to execute: a viewer can still receive Editor role required when running a cell.

Run All runs nonempty cells in order. Put imports and setup above dependent cells, and inspect errors before trusting later outputs. For saving code, versions, recovery, and sharing, see Saved Work And Sharing.

Know which rows you have

An attachment contains at most 250,000 measurement rows across all tests, selected by deterministic hash ordering after scope and retest filtering. It is not a 250,000-row allowance per test, and it is not every measurement in a large lot. Rows with null measurements are excluded. The account’s retest policy determines which eligible attempt supplies each die/test/return result.

For runtimes using bounded JSON attachments, the complete execution-message budget depends on the deployment’s execution backend:

Execution backend	Message budget
Isolated execution (broker)	128 MiB
Process execution (process)	256 MiB

This includes code, scope, selected-die identities, limits, measurement rows, metadata, and JSON encoding overhead. It is not a RAM allowance or an upload-file limit. Your administrator can confirm the backend; an input-size error names the actual attachment budget on your installation. Returned frame metadata reports whether rows were capped, not the numeric byte budget.

Long text fields can reduce an attachment below 250,000 rows. In this case, the runner keeps a prefix of the same deterministic row order, reports byte_capped, and marks the attachment sampled. Row text, selected-die identities, and scenario limits are not truncated. If the code and scope leave no room for even one measurement row, execution fails with an input-size error before running the cell; reduce the attachment or code. Existing sessions are not reset by that rejection.

Older runtimes do not report byte_capped. Check the returned metadata rather than assuming that every installation has this transport. Reused attachments retain their original row count and cap status; a smaller later cell does not fetch rows omitted when the attachment was prepared.

The execution summary reports prepared or reused rows and flags sampled attachments. The same metadata is available in the result frames’ attrs:

Attribute	Meaning
stratum_source_row_count	Catalog row count of the source artifact, before selection and result filtering; zero if unavailable. Not an exact selected-population or selected-test denominator.
stratum_sampled	The row cap was reached with more source rows, or the transport byte cap omitted measurement rows. This is a conservative cap flag, not a measured sampling fraction.
stratum_scope_status	complete, capped (row cap), byte_capped (transport cap, where supported), empty_selection, or no_scope. complete describes the eligible attachment, not all raw attempts in the lot.

Keep sample results labelled

len(scope_test_results) counts attached measurement rows, not unique dies. A test or wafer can be underrepresented or absent from a capped attachment. Filtering that frame cannot fetch omitted rows, and sampled: false does not turn a selected scope into a full-lot population. Do not scale a count by source_artifact_rows / attached_rows to claim an exact lot total. At exactly 250,000 attached rows, treat the frame as potentially capped even if missing source-count metadata prevents the sampled flag from being set.

With selection inactive, the attachment covers the eligible lot population up to the cap. With selection active but empty, it contains no measurements. An empty selected_dies frame alone cannot distinguish those cases; check analysis_scope.selection_active. The no_scope status means no analysis scope was supplied; the Notebooks UI normally supplies a default lot scope.

Frames and test identity

Frame	Contents
analysis_scope	Context summary: lot, snapshot, selection state/counts, selected test/return, wafer focus, and scenario-limit count.
selected_dies	Explicit selected identities: wafer number, X, Y.
selection_runs	Compact selection ranges in the attached die index. They are not row ranges into the measurement frames.
scenario_limits	Attached limits keyed by test_number and return_index.
scope_test_results	All tests in the attached die scope, subject to filtering and the shared cap.
selected_test_results	Rows from that attachment matching the selected test and return. Empty if no test is selected.

Wafer focus does not automatically narrow either result frame. Both include wafer/X/Y, site, test and return identity, result/unit, recorded limits and pass, effective limits and effective_pass, and retest_sequence. effective_* incorporates attached scenario limits, then account spec overrides, then recorded values. Recorded verdicts and limit membership can disagree. These are test-result fields, not a recomputation of full-die yield.

Keep MPR returns separate, and retain null return indices for PTR/FTR tests:

summary = (
    scope_test_results
    .groupby(["test_number", "return_index", "test_name", "unit"], dropna=False)
    .agg(attached_n=("result", "count"), mean_result=("result", "mean"))
    .reset_index()
)
show(summary)

To explicitly narrow the selected-test frame to the focused wafer:

focused_results = selected_test_results.copy()
wafer = st.context().get("selected_wafer_number")
if wafer is not None:
    focused_results = focused_results.loc[focused_results["wafer_number"].eq(wafer)]
show(focused_results)

An empty result here can mean no test selected, no matching measurements, an empty die selection, or omitted rows in a capped attachment. Check scope and sampling metadata before treating it as a data-quality finding.

SQL inside a cell

sql(...) runs DuckDB over the attached frames in this Python process. It does not call the SQL editor or query additional Parquet rows. The SQL editor’s portable views and current_scope_* helpers are not registered here. This example counts only the rows already attached:

show(sql("""
    SELECT test_number, return_index, COUNT(*) AS attached_rows
    FROM scope_test_results
    GROUP BY test_number, return_index
    ORDER BY test_number, return_index
"""))

st.tables() lists available frame names. st.scope_test_results() and st.selected_test_results() return fresh copies. show(...) displays a value; a cell’s final expression is also displayed automatically. Neither Python frame edits nor this local DuckDB connection apply limits to Analyze or write changes to the source lot.

Display previews and output limits

If a displayed table has a Showing … of … rows caption, you are seeing a bounded preview, not every attached row. On runtimes with this preview support:

Display limit	Budget
DataFrame or Series preview	First 50 rows and 30 columns
Table cell or label text	256 characters
Display attempts per cell	124
Retained display output per cell	24 MiB
Captured stdout, stderr, and cell error	1 MiB each

Display byte budgets count JSON-encoded UTF-8, including escaping. Table captions report the displayed and total dimensions; nested values may be abbreviated. The preview does not change the frame used by Python or sql(...). Use len(scope_test_results) for its attached row count, not the number of rows visible in a preview.

Output truncated means some display or captured text was shortened or omitted. An oversized HTML table or Plotly figure is omitted whole, not cut into broken markup. A figure can use the remaining shared display budget; there is no smaller per-figure allowance. An omitted item still counts as a display attempt, but a later small summary can appear if budget remains. Plotly’s JavaScript stays embedded, so plots do not require a public CDN.

These limits apply to output, not calculations or temporary allocations. Constructing a large figure or custom representation can still exhaust memory or time before output is collected. Normal display truncation preserves the session and attached data; an execution timeout or worker failure can still reset them. The receiver separately caps responses at 32 MiB and 128 output items; violating that transport contract resets the session.

Preview support depends on the installed runtime release, not just the backend. Older runtimes without preview captions may reset after oversized output; use an explicit small slice or aggregate rather than assuming automatic previews. Neither a preview caption nor byte_capped proves that execution is isolated.

Reuse, mutations, and resets

The first cell prepares the attachment and starts a server process. Later cells reuse it while the scope and dataset identity remain unchanged. The summary separates preparation, runner round-trip, and execution time; peak memory is the process lifetime high-water mark, not memory used by that cell.

At each cell boundary, built-in frame names are rebound from the retained attachment. Ordinary pandas mutations to scope_test_results in one cell do not alter the next cell’s built-in frame or the registered SQL source. Keep derived work under your own variable, such as working = scope_test_results.copy(); that variable persists in the current process until a reset.

Changing scope or snapshot resets the runtime. Each editor has its own process; another tab does not share your variables. Leaving Notebooks or changing workspace releases it. A hidden tab releases an idle runtime after about a minute, without interrupting an already-running cell. The server also expires idle sessions, normally after 15 minutes, and may reclaim idle processes when capacity is needed.

A restarted or evicted runtime can rebuild its attachment, but cannot restore your Python variables. Rerun imports and setup cells before dependent cells. The normal per-cell execution timeout is 120 seconds; operators can configure it. A timeout discards the process. Retry Runtime rechecks availability, not a saved execution state. Old displayed outputs are not evidence that the new runtime has rerun the code, and outputs and variables are not saved versions.