Regressor Panel API¶

QCEW national rows for the regressor panel (roadmap Stage 3; Req 2; Req 21; D1; D7).

Stage 1's finding (specs/findings/employment-statistics-coverage.md) fixes the source: QCEW annual averages for 2022–2025, national grain, private ownership (own_code 5). The panel reads the Open Data Access national slices ({year}_US000_annual.csv) under the sha256 values the finding records; they agree with the annual single files on every national row.

• Cells. One cell per code and year. Sectors 31-33, 44-45 and 48-49 are keyed 31, 44 and 48, as in the codebook. Each of the 19 six-digit NAICS 238 codes that BLS publishes only as residential (…1) and nonresidential (…2) codes is its five-digit parent's only child, so its cell is read from the parent's row.
• Usable. A cell is usable when it is disclosed and its employment, establishments and wages are all positive. A suppressed cell is never read as zero.
• Population. The codes with a usable cell in every window year.
• Rows (D7). One row per population code and feature year t in 2022–2024: the covariates are log establishments and log total annual wages from year t (D1), and the outcome is log annual-average employment in year t + 1.
• Growth (Req 21). In growth mode the outcome is log E(t + 1) − log E(t) instead, from the same cells, and nothing else changes. Every population code has a usable cell in every window year, so the difference is always defined.

The regressor panel's sealed outer sets (Req 2; Req 4; roadmap Stage 3; D7).

Every panel row is a code in a feature year. One partition serves both regimes, so that no validation read touches either regime's sealed set:

• Held-out outer set (H). Every row of a code whose employment includes a held-out four-digit group: at levels 4–6 the code's own four-digit ancestor (or the code itself) is held out; at levels 2 and 3 a held-out group rolls into the code.
• Seen outer set (S). The remaining rows with feature year 2024, whose outcome is 2025 (D7).
• Remainder (R). The remaining rows, feature years 2022 and 2023. Validation reads only these.

The held-out groups are drawn once, stratified by sector, and committed (conf/data/regressor_heldout_groups.csv). The split's fingerprint is the sha256 of that table's canonical CSV, which equals the committed file's hash: a redraw gets a new fingerprint, so it would not count as a reopening, and the table is therefore never redrawn.

Draw the regressor panel's held-out four-digit groups (roadmap Stage 3; Req 2; Req 4).

naics-embedder data regressor-groups runs this once. The table it writes (conf/data/regressor_heldout_groups.csv) is committed, and the panel reads it from then on, so the held-out regime's outer set never moves. The seen regime's outer set leaves out the held-out groups too, so a redraw moves both outer sets, and its new fingerprint would not count as a reopening: an existing table is replaced only with force.

Ridge regression on standardized features along a penalty grid (Req 2 "Fitting"; D1).

standardized_ridge_path matches scikit-learn's make_pipeline(StandardScaler(), Ridge(alpha)) at every penalty on the grid, from one singular value decomposition of the standardized fit set. The mean and scale come from the fit rows only, and a constant column keeps scale 1, as StandardScaler does.

The text-only comparator of the regressor panel (Req 2; roadmap D9).

D9: "the arm's own backbone, frozen, embedding each code's text, reduced by PCA to the arm's dimension". The table holds one vector per code at the backbone's hidden size; the panel reduces it to the arm's dimension when it scores the arm.

• Text. The four channels the arm reads (title, description, excluded, examples) from the arm's own descriptions file, without the arm's field markers (spec 4.2).
• Pooling. Each channel is mean-pooled over its tokens under the attention mask, as the arm's encoder pools (text_model/shared_encoder.py). A code's vector is the mean over its present channels: an absent (null or blank) channel is masked out, never encoded as a placeholder.
• Frozen. The backbone runs in evaluation mode under torch.no_grad, on the CPU in float32, with no adapter.

The regressor panel (Req 2; Req 1, regressor estimand; Req 4; roadmap Stage 3; D1, D7, D8, D9).

An arm's coordinates enter a ridge regression as regressors, and the panel returns out-of-sample predictions per row, keyed by code, year and group, so that Stage 4 can compute whichever statistic it settles on and resample by four-digit group.

• Rows (D7; Req 21). A code in a feature year t (2022–2024): covariates from year t, and the panel's outcome (qcew_rows): log employment in t + 1 (level, the default) or its log change from t (growth). The outcome names the reads: regressor_seen and regressor_heldout for the levels, growth_seen and growth_heldout for growth.
• Regimes (D8: each is a panel). seen: every scored code has earlier rows in the fit set; one-hot is a real competitor. heldout: every row of a held-out four-digit group leaves the fit set; it runs at levels 4–6, where four-digit parents exist.
• Partition. One partition serves both regimes (regressor_splits): validation reads only the remainder, feature years 2022 and 2023 of codes outside the held-out groups.
• Comparators (Req 2). Covariates alone (log establishments and log wages, D1), and each representation alone and with the covariates: the arm's coordinates, six-digit one-hot (level-L one-hot in the multi-level variant; seen regime only), ancestor indicators at levels 2 to L − 1, and the text-only table reduced by PCA to the arm's dimension (D9). The margin read (Req 24) scores only the comparators that read no arm's tables, and reads no arm.
• Fitting. Ridge on standardized features, the penalty tuned by nested cross-validation inside the remainder only (FitTask). Fold assignments depend on the regime, level, repeat and group ids alone, never on the arm, so every arm is scored on the same folds (Req 5).
• Sealing (Req 22). Each regime's outer set is read only after a logged opening by the same panel object. An opening is recorded against the split, not the outcome: one under either outcome's read name counts for both, so a second opening of the same split (the same regime and held-out draw, by fingerprint) needs a stated reason. Every read goes to the selection log, whose n_queries field counts rows here.