Changelog

All notable changes to processbehavior are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased¶

Added¶

• A bare response is charted in the order received. formulate(response=...) with no time, factors or plan used to be refused. The values are now numbered 1..N in an Observation column (the same numbers as obs_id) and the study is exactly the one time='Observation' gives: a single stream, ADS 2, X/mR, sigma from N − 1 moving ranges. An NA response keeps its place as an empty cell. The design report adds Time: received order (no time column given). If the data already has an Observation column, formulate asks you to pass it as time= or rename it (#129).

• Phased limits on Xbar and S charts. execute(chart='Xbar', phased=True) gives each factor combination its own centre line and limits on one chart, drawn as stepped lines with a divider at each change, the way phased X/mR already does for its lanes. Each phase is computed as a separate Xbar/S analysis, exactly as by=[time] computes one chart per condition: the centre is the mean of the phase’s subgroup means, with its own S-bar and sigma-hat (10-12 manual Eqs 11-5, 11-8, 11-9, 11-16, 11-17). by=['stage', time] pools the other factors into the subgroup and phases on the stage; the centre is then the mean of the pooled subgroup averages, as Dr. Bishop specified (2026-10-18). On Wheeler’s four-cavity thickness data the per-cavity centres and limits match Minitab’s staged Xbar-S chart. Residual values, calibrations and by=[time] are refused with messages that say what to use instead; a phase with no replicated subgroup keeps its points without limits and is named in metadata['insufficient_phases']. (#144)

• result.phase_statistics(chart, stratum=None). One row per phase of a phased chart. Xbar/S: phase, subgroups, N, center, s_bar, sigma_hat, lpl, upl. X/mR: phase, points, center, mR_bar, lpl, upl, per stratum on a stratified chart (stratum=, or through focus()). (#144)

Changed¶

• formulate(response=..., factors=[]) with no time is the same study. It used to treat the whole column as one replicated cell: ADS 1, a recommended one-point Xbar chart, the “within-cell replication” series-length line, and an X chart plotted against the response values. Its chart tables now start with Observation (#129).

• Xbar and S chart data carry n. get_chart('Xbar') / get_chart('S'), and the Excel chart sheets, gain an n column after the subgroup label. Unstratified Xbar/S metadata names the label column as group_col (#143).

• Lane dividers on an Xbar or S chart are labelled with the phase. These charts have no time column and so no cell band under the axis, which is where X charts name their lanes. (#144)

• Phased chart data and chart_table carry a phase column (the lane label) after the subgroup label, on X/mR as well as Xbar/S. Phased Xbar/S metadata carries phase_by, lane_boundaries, single_point_phases and insufficient_phases; n_avg is not reported on a phased chart, whose n_mode='average' is applied per phase, so the per-phase mean size is phase_statistics(chart)['N']. (#144)

Fixed¶

• Xbar/S chart_table keeps the subgroup label and n on every by=. With a by= other than time alone, such as a pooled subset (by=['FACTOR 1', time]), all factors, factors without time, or one factor, the table dropped both columns, so a row couldn’t be traced to its subgroup and stepped limits went unexplained. n is now the aggregation’s own count, which covers every cell a pooled subgroup spans. This also corrects one row on residual charts whose limits rest on R2 (R1, R3, R4, R5) in a design with singletons: the stream’s first cell, where R2 is undefined at the first value, showed its cell size, not the one-fewer values its S and limits use. Limits, centres and statistics are unchanged (#143).

• execute() no longer documents phased=True as requiring by=[]. Stratified phasing of X/mR (by=['factor 1'], phased=True) has been accepted since 75bcdd1; the docstring never caught up. (#144)

• The companion mR of a phased X chart reports single_point_phases. Only the solo mR did. (#144)

• X/mR lane order honours an ordered pandas Categorical factor. A stage column with categories before < after already ordered the Xbar/S subgroups that way, but the canonical row order sorted the raw labels, so X/mR lanes, phases and strata came out after, before. The canonical sort now uses an ordered Categorical’s category codes; plain string and numeric factors sort as before. (#144)

0.4.0 - 2026-10-14¶

This release aligns the library with Bishop’s VAS documentation manual dated 10-12-2026 and reproduces his VAS runs of October 2026 (PM SDS, PM INERT, known-effects and Medicare decks). Equation numbers below are that manual’s.

Changed¶

• R6’s factor-level effect is the average of the condition effects over the level. R6 = α_i + R2 with α_i the condition effects ρ̂_k = R5 - R2 averaged over the level (was the level’s mean of R5, Eq 14-24, “≈ α_i”). The two differ by the level’s average R2, which Dr. Bishop notes is always near 0; in ADS 1 it is 0 (R2 averages to zero in each cell). On ADS 2/3 it shows when levels are small: Tom’s Medicare run centres the organisation-effects chart at 10831.1 (PB was 10829.8, now 10831.1).

• R2 for designs with a one-observation subgroup (ADS 2 and 3) follows the manual. The data are first stripped of the process mean and the condition and period effects (Z = Y − Ȳ_k − Ȳ_t + Ȳ, Eq 14-4 / 14-9), Z is differenced along the condition-then-time sequence, and the difference is divided by twice the R2 scale factor c(K, M) = √((K − 1)/(2K) · (1 − K/(M − 1))), computed from the layout (Eqs 14-5..14-13). Previously R2 was half the difference of consecutive raw values, so every step from one condition’s last period to the next condition’s first carried the level difference between them, a common trend was read as noise, and the result sat on a smaller scale than σ. R3–R6, the effects, maximum information and potential capability follow. PM SDS 2 R2 chart limits ±1.94 → ±2.76, PM SDS 3 ±2.47 → ±3.70, potential Cp on PM SDS 2 (specs 232/242) 2.51 → 1.78; on the Medicare ACO file the R2 σ falls from about 1,023 to 300 and the organisation chart (recentred R5 by ACO) flags 19 of 24 organisations instead of 8. ADS 1 R2 (within-cell deviation, Eq 14-3) is unchanged. calculate_r2 now dispatches on r2_method and takes n_conditions; its n_per_cell argument is gone.

• Taguchi loss follows the manual. ADS 1 unexplained loss is the average cell variance (1/KT)·ΣS²_kt, without dividing each S_kt by c4 (Eq 15-16). ADS 2/3 unexplained loss is the sample variance of R2 (Eq 15-17; the 1/0.7 correction is gone), and the interaction is what the other parts leave of the total loss (Ȳ − T)² + S², set to 0 when negative (Eqs 15-18..15-20), so the parts add to the total. PM SDS 1 at target 237: unexplained 23.0% → 20.9%, interaction 43.3% → 44.5%; PM SDS 2: interaction 42.5% → 25.6%, unexplained 23.6% → 30.0%; pure noise (PM INERT) now shows 0% interaction in ADS 2/3.

• Re-centred residuals are the residual plus the process mean, the mean of the cell means (Eq 14-26). RCR3, RCR4 and RCR5 were “reconstructed Y” (each algebraically Ȳ_kt + R2), so a recentred interaction chart plotted close to the raw cell means. They now plot the effect plus R2 on the measurement scale, as VAS does; RCR2 is unchanged. Xbar means by condition (RCR5) or period (RCR4) are unchanged on complete designs; period effects are charted from R4.

• ADS 3 recommends the Xbar chart (was X): Xbar/S is VAS’s default for SDS 3 and 6.

• Capability is centred on the process mean as VAS computes it: the unweighted mean of the (factor × time) cell means, the same centre as the Xbar chart and the loss function, instead of the plain average of the readings. CapabilityResult.y_bar, current PPL/PPU and the potential centre (ȳ + mean(R2)) move when cells have different sizes (SDS 3, 4, 6); balanced designs are unchanged. PM SDS 6 now reads PROCESS MEAN 237.86 and PPL 1.102 / PPU 0.78, as Tom’s VAS run does (was 237.834, 1.098 / 0.784).

• Validation gate re-referenced to Tom’s 3 October 2026 VAS run (validation/e2e_bishop_report.py, tests/fixtures/bishop_analyses/). PM SDS 3 is checked as Xbar/S, as VAS now draws it; its limits vary with subgroup size and are not printed on the slides, so they carry no reference yet. The gate now reports 254 assertions passing and 61 with no reference value (was 280 / 35); PB’s side is compared at full precision.

• The validation gate covers every VAS run on hand (14 runs, 1155 assertions, was 3 runs and 254): PM SDS 1-6, PM INERT SDS 1-6 (the pure-noise column with each design state’s missing-data pattern), Tom’s known-effects data (validation/PBTESTKNOWNEFFECTS_T100.csv, SDS 1) and the Medicare ACO data (validation/aco_per_capita_expenditure.csv, 24 organisations x 4 years). Each run’s reference values, spec limits and target are in its own file, tests/fixtures/bishop_analyses/<run>.json (the vassds{1,2,3}analysis.json references are now pm_sds_{1,2,3}.json). All six PM runs use target 237; PM SDS 5’s loss shares come from Tom’s rerun at 237 (8 October 2026), because his 10/3 run used the process mean.

• Limits VAS prints as “UNEQUAL” are checked against the lines it draws. Where subgroup sizes differ, VAS steps the limits per subgroup and prints no value; the gate now reads every subgroup’s LBL/UBL from the red limit lines in the VAS chart drawing (scaled by the y-axis ticks, good to about one drawing unit) and compares PB subgroup by subgroup, to 1.5 drawing units. 186 charts in SDS 3-6; the gate reports 1475 assertions passing, 0 failing, and 79 with no reference (was 1155 / 0 / 399).

• The R6 S charts are checked wherever VAS computed them correctly. VAS’s α_N (Eq 10-11) used Minitab’s GAMMA function, which overflows above N = 343; the 10/3 VAS runs held α_N at 0.9995 from there on, so their S limits followed N = 500 whatever the subgroup size. Dr. Bishop confirmed it (8 October 2026) and is replacing it with a table; PB computes α_N with log-gamma for any N. The gate now checks the R6 S charts whose subgroups are under 343 (all match), the factor S charts’ centerlines (one subgroup per factor level, as Dr. Bishop confirmed), and PM SDS 5’s loss shares from his rerun at 237; only the limits for subgroups of 343 or more wait for his rerun. The references’ notes now give that cause.

• Every R6 S chart in the PM runs is checked, against Dr. Bishop’s reruns of 13 October 2026. His reruns of PM SDS 1-6 and PM INERT SDS 1-6 compute α_N for every N. Against the 10/3 runs they change only the R6 S charts (pages 21, 25 and 27) and potential capability in PM SDS 3 and 4. The limits for subgroups of 343 or more, pending until now, all match PB within the gate’s tolerances (36 assertions). The rerun’s potential capability is now PB’s value to the digit it prints: PM SDS 3 Cp 1.58 and CPL 1.84 (PB 1.5751 and 1.8356; the 10/3 run printed 1.57 and 1.83), and PM SDS 4 CPL 2.66 (PB 2.6555; was 2.65). The gate no longer lists the per-factor loss shares (F1, F2, PDC Int) for a one-factor run such as Medicare, where they don’t exist. It reports 1547 assertions passing, 0 failing and 4 with no reference (was 1511 / 0 / 43): the known-effects factor S limits, whose 6 October run predates the fix.

Added¶

• R2 is reported unavailable, with the reason, when the R2 scale factor is undefined (fewer than two process design conditions, or M < K + 2 observations). formulate() warns; R2–R6 are not offered; execute() and why_not() give the reason; loss_function() and maximum_information() raise ValidationError; capability() reports potential capability unavailable. Previously these layouts produced half-differences of the raw data.

• CapabilityResult.potential_center: the centre of the potential values, ȳ + mean(R2). Potential CPL/CPU and the potential chart’s centre line use it, as VAS does (Medicare potential PPU 5.74; ȳ alone gives 5.73). It equals ȳ in ADS 1.

Fixed¶

• Stratified charts take time in proportion to the data, however many strata there are. The stratified X/mR path looked each stratum up with a scan of the whole table, so its cost grew with strata × rows. With every row its own condition, an X/mR pair took 48 s at 30,165 rows, and an estimated 80 minutes at 307,683 (a gene-expression study, 6,033 genes × 51 subjects). It now takes 0.2 s and 1.9 s. The same scan sat in the stratified Xbar/S loops and the lane-boundary loop, the per-stratum limits were computed one pd.Series at a time, and two lists of strata were searched as lists. Results are unchanged: every chart, statistic, lane boundary and stratum list was compared before and after on the reference data and a 30,165-row gene-effects file. scripts/benchmark.py adds a one-row-strata scenario, and tests/test_performance.py checks that it scales linearly. Stratified Xbar/S still costs about 2.5 ms per stratum (15 s at 6,033): linear, but not yet vectorised.

• Charts with many lanes draw in a fraction of a second. Each lane divider was added to the figure with its own add_shape call, and plotly re-validates every shape already there, so the cost grew with the square of the number of lanes: 800 dividers took 27 s, and an X chart of a 6,033-gene study (one lane per gene) would have taken about 25 minutes. They are now added in one assignment, which builds the same figure (0.03 s for 800). Above 1,000 (plotting.lane_boundaries.MAX_LANE_DIVIDERS) none are drawn: the dividers would merge into a solid band at any chart width.

• detect_signals() works on phased charts. It raised TypeError on every phased=True chart: each phase has its own centre, so the statistics carry center=None, and the zone calculation read that scalar. The chart already marks run rules not applicable, but only the plot read the flag. Phased charts now get Rule 1 by default, judged against each phase’s limits, with the same points the chart flags; an explicit rule list runs as given, against each row’s own centre. The limits and the flagged points on the chart were always correct.

• value='response' charts the response, as the execute() signature and docstring say. Every chart refused it (“Valid charts for RESPONSE: None”): residuals are told apart by a leading R, which RESPONSE also has. execute(), supports_calibration() and why_not() now treat it, in any case, exactly as value=None.

• Xbar and S charts with subgroups of unequal size follow the manual (Eqs 11-5, 11-16, 11-17). sigma-hat is the average of each subgroup’s S_r / c4(N_r) (was S-bar / c4(N_r)), and each subgroup’s limits use its own N_r, so they step with subgroup size, as VAS draws them. N_r now counts the values the chart is drawn from (was the response’s count): on ADS 2 and 3 residual charts, R2’s blank first value leaves one subgroup one smaller. Equal-size charts are unchanged. Found on Tom’s Medicare run (slides 52-53): ACO-001 has 3 R6 values, and its limits are wider by sqrt(4/3) on the Xbar chart and use B4(3) on the S chart.

• Xbar charts include one-reading subgroups, as VAS draws them. A subgroup with one value has no S, so it takes no part in sigma-hat, but it is charted with limits centre ± 3 sigma-hat (Eqs 11-16/17 with N_r = 1); it was left off the chart. The companion S chart still leaves it out. On PM SDS 3 the Xbar chart now has all 800 subgroups (was 783) and on PM SDS 6 all 772 (was 642), matching the limit lines in Tom’s VAS run subgroup by subgroup; on PM SDS 6’s interaction chart the one cell whose single reading has no R2 stays off, as in VAS. Designs without one-reading subgroups (ADS 1) are unchanged.

• Per-stratum Xbar centre lines count one-observation subgroups. The centre is Bishop’s unweighted mean of every subgroup mean; subgroups with n = 1 were dropped before it was taken, which moved four of the eight PM SDS 3 per-condition centres by 0.01–0.04.

• Code and docs cite the manual’s Chapters 10 and 12. The X/mR limits and constants (Eqs 12-1..12-11), c4 and the S-chart factors (Eqs 10-11, 10-12, 10-14), the cell and marginal means (Eqs 10-7, 10-9) and the model the residuals estimate (Eq 10-3) now cite the manual where the code computes exactly those equations, and every citation names the 10-12 edition (its Chapter 10 drops the 10-1 edition’s Eq 10-4, so Eqs 10-5..10-16 became 10-4..10-15); dotted citations (“Eq 12.4”) and an older manual’s numbering in a test are gone. tests/test_manual_citations.py keeps one citation form, and CONTRIBUTING.md describes it. The residuals guide now says Ȳ is the mean of the cell means.

• Bishop’s methodology is called the Variation Analysis System, as his VAS documentation manual names it (was “Variance Analysis System” in the README, docs, CITATION.cff, docstrings and the design report’s VAS line). The synthetic-data module no longer credits the design states to Wheeler.

• Docs: the three note blocks in the chart-types and design-state guides now render on the MyST site (they used mkdocs syntax); the DS 4–6 chart tables and the no-factors branch of the decision tree match what the library offers (a time-only study is DS 1, 2 or 3 by the number of observations per time point, not DS 6); the R1 note no longer claims the residuals sum to zero on unbalanced data (their cell means average to zero); R1 is cited as Eq 14-2, and the design states are attributed to Bishop. The README’s Validation section describes the gate as it is (14 VAS runs, 1,547 assertions, SDS 4–6 included); it still described 3 runs and 254.

0.3.3 - 2026-09-29¶

Changed¶

• Individuals and moving-range limits now use the constants exactly as Bishop’s VAS manual defines them. The individuals-chart multiplier is 3/1.128 = 2.659574 (previously the rounded 2.66) and the moving-range upper limit is 1 + 3(0.8525)/1.128 = 3.267287 (previously 3.268), built from the manual’s d₂ = 1.128 and d₃ = 0.8525 (Eq 12.4, 12.5, 12.10, 12.11). The manual prints the rounded values; Bishop’s VAS software computes them without rounding, and PB’s X and mR limits now match it digit for digit (Medicare first chart: ±3838.32 and 4715.38). Limits move by 0.016% and 0.02%, so a signal changes only for a point within that distance of a limit. The d₂ used on the calibration path and by the maximum-information chart is now exactly 1.128 (it was 3/2.66 = 1.1278), and MR_SIGMA_INTERVAL_80 was regenerated: five entries move by 0.001. New constant D3_N2 in processbehavior.spc_constants.

Added¶

• Docs: the chart-types guide now explains the three views of a study with factors and time (the combined by=[] chart, the phased=True view, and full stratification), how to read a signal at a subgroup boundary on the combined chart (evidence about the traversal, kept in the calculation deliberately because it reproduces Bishop’s reference limits), and which claims survive reordering the lanes, with the R5 chart’s limits caveat for DS 2 and 3. The phased view is documented in the user guide for the first time. From the #114 discussion with rabujamra, whose permutation check is validation/mr_permutation_invariance.py.

0.3.2 - 2026-09-15¶

Fixed¶

• Binning a heavily tied column no longer collapses to one bin. 0.3.1 capped the requested bin count at the number of distinct values before taking the quantiles, and on a column of 3,000 ones and 1,000 twos the halved quantile positions both landed on 1, so one bin fitted where 0.3.0 fitted two. When at least as many bins are requested as there are distinct values, the fit now cuts at the midpoints between neighbouring values: one bin per distinct value, every value in its own bin, with the message requested n bins, ties produced k (one per distinct value). Requesting fewer bins than distinct values is untouched (the original quantile / equal-width path). Found by the app’s preview test.

• The connecting line on a lane chart no longer crosses lane boundaries. On an X or mR chart with factors and by=[] (one chart, subgroups side by side), the last point of each subgroup was joined to the first point of the next, so every boundary drew a steep rise or drop that was only the sort order. The line is now its own trace with a gap at each boundary, drawn under the markers; the markers trace keeps hover, legend and signal highlighting exactly as before. Single-series and faceted charts are unchanged. #121

Added¶

• Docs: a user-guide page on series length and where sigma comes from (the position, the n = 3..30 precision table from validation/short_series_bands.py with credit to rabujamra, the trending-series and not-one-process cautions, the formulation lesson from #114, and the two-audiences position on run rules), and a user-guide page stating the derived-variables contract (never raises, what counts as a violation, what bins promise, what construction rejects).

0.3.1 - 2026-09-14¶

Fixed¶

• Derived variables: evaluate and validate now keep their never-raises promise. An adversarial pass (36,000 fuzzed evaluations) found four ways to make them raise from pandas: ±inf in the source column (equal_freq / equal_width: “bins must increase monotonically”), range labels that collide at six significant digits on a tiny range or a near-constant sd fit (“labels must be unique”), duplicate or null explicit bin_labels, and a string shift / exponent reaching numpy. Now: ±inf leaves the bin fit, becomes NaN, and is counted in n_invalid with a message; range labels gain precision until distinct (numbered bins as the last resort, with a message); explicit labels must be non-empty, null-free and unique; shift, exponent and breaks must be finite numbers; on_invalid must be 'error' or 'na'; n must be a positive integer (numpy integers accepted, booleans rejected) — all at construction, as ValidationError. A datetime or categorical source now evaluates to an all-NA result with a message instead of transforming nanoseconds or category codes. A permanent seeded fuzz test guards the contract.

Changed¶

• Every non-finite transform result is a domain violation. log/sqrt of inf, square overflow and inverse of a denormal used to return inf with n_invalid=0 (only power overflow was flagged); all are now violations, so on_invalid applies and an inf can no longer reach the limits. A z-score of a constant (or single-value) column is now a violation for every value rather than a silent all-NaN column, so on_invalid='error' names the derivation at formulate. arcsin on values in (1, 100] adds the hint “if these are percentages, divide by 100”. Requesting more equal-frequency / equal-width bins than there are distinct values now fits one bin per distinct value and says so. 'ordinal' labels above five bins say they fell back to numbered bins. to_dict converts numpy scalars and arrays (it was documented JSON-safe but was not); from_dict decodes the Infinity/NaN tags only under numeric keys, so a bin labelled "NaN" stays a string; a missing id is a ValidationError, not a KeyError. Finite inputs with distinct labels produce byte-identical edges, labels and values.

0.3.0 - 2026-09-14¶

Added¶

• The design report states where sigma comes from at the observed structure and series length. One line under Structure: Series length: T=4. Sigma for X/mR rests on 3 moving ranges. With every cell replicated it reads Series length: T=1. Sigma rests on within-cell replication. — a single time period is a complete study. Exposed as study.series_length (SeriesLengthPrecision, frozen) and study.series_length_description. The result also carries within_cell_df and, for the moving-range case, mr_interval_80 — the p10/p90 of MRbar/d2 by n = 3..30 from MR_SIGMA_INTERVAL_80 (spc_constants), generated by validation/short_series_bands.py (contributed by rabujamra in #114 / #119) — for callers who want the numbers; the report prints only the sentence. It is a fact beside the design state, not a judgment on it: no threshold, label, or warning, and the design state, recommended chart and analysis menu do not move with T (pinned by test). Closes the series-length half of #114.

Changed¶

• The R2 method for partial replication is reported as ma2, not hybrid. The docs described a per-cell hybrid for design state 3 (exact deviation where a cell has n ≥ 2, moving average where n = 1) and said it was validated by Monte Carlo. The code has not done that since cb037f8 (2026-03-05): with any singleton cell, R2 is Bishop’s ungrouped 2-point moving average over the full canonical sequence (Eq 13.7–13.9) for every observation, and the 89 ADS 3 reference assertions hold against that. Only the word survived, in six docs pages (three of which described it three different ways), the detector’s method token, the analysis-plan limitation text, two docstrings and two test names. All now say what the code does. R2Method is Literal['exact', 'ma2']; SDSRegistry.get_r2_method returns 'ma2' where it returned 'hybrid'; get_sds_characteristics and SDSAnalysisPlan.residual_calculation_method use the same two spellings in place of 'within_cell', 'moving_average' and 'hybrid'. No arithmetic changed; none of these names is exported from the package top level.

Dependencies¶

• plotly>=5.18,<8 (was <7). plotly 7.0.0 (2026-08-25) was tested against the full suite before the bound moved: its breaking changes (mapbox traces, decimal-fraction rgb() strings, hsv(), Kaleido < 1.0, figure_factory) touch nothing here. #116.

Fixed¶

• A missing value in a factor column no longer makes a two-factor study fail. With one factor, rows with a blank factor value were dropped silently; with two or more, the composite subgroup label was built before that drop and formulate raised ValidationError: Cannot build RSG ... missing values in factor columns. The same file formulated with either factor alone and failed with both (a 85,101-row survey file with 7,980 blank SURVEY QUESTION rows). Rows with no value in any factor column now leave the analysis before the label is built, for any number of factors, and the library says so with a ProcessBehaviorWarning naming the count per factor. Response and time missing values are handled as before.

• evaluate no longer raises on a constant column. Binning a column with no spread (every value identical) returned the documented no-spread result for equal_freq but raised ValueError: Bin edges must be unique from pd.cut for equal_width and sd, because their fitted edges were identical yet finite and slipped past the guard. The derivations module promises evaluate never raises on a routine state; a constant column is one. All three methods now return the same no-spread result, whose fitted dict also carries n_bins: 0, edges: [] and labels: [] so callers see one shape. Explicit breaks on a constant column still bin. Found through the app on a single-time-point file whose TIME column was a constant.

0.2.1 - 2026-09-09¶

Fixed¶

• A short series no longer returns an unqualified all-clear from detect_signals. SignalConfig.min_observations (default 20) was unreachable: SignalDetector read a hardcoded per-rule table and never consulted the config, so SignalConfig(min_observations=30) changed nothing. Separately, the detector already recorded which rules it skipped for length (rules_skipped, added in 0.2.0) but SignalResult.summary ignored that and printed ✓ No signals detected regardless. On a four-point X chart six of the eight rules cannot fire, and the one that can is weakened by any trend in the data, so the checkmark described an examination that had mostly not happened.

  Now: the per-rule table is the structural minimum (RULE_MIN_OBSERVATIONS, a rule is skipped below it, as before) and min_observations is the advisory minimum. Below it the detector emits a ProcessBehaviorWarning naming both numbers (one per chart evaluated; silence it with warnings.simplefilter('ignore', ProcessBehaviorWarning) once a pipeline has accounted for it) and the result is marked partial even when every runnable rule ran. SignalResult gains rules_evaluated, rules_applicable, n_observations, min_observations, below_min_observations and evaluation_note; is_partial / evaluation_status now also reflect the advisory threshold. A partial evaluation prints ⚠ Partial evaluation in X: 2 of 8 rules applicable at n=4 (...). No signals from the rules evaluated. and the checkmark line is reserved for a complete evaluation. Which rules run, and what they flag, is unchanged. Excel export’s Summary sheet adds evaluation status. Reported privately (GHSA-hw63-2x95-fmpv) and in #114.

• SECURITY.md supported-versions table said 0.1.x while the prose said 0.2.x. The table now matches the prose.

Removed¶

• Seven never-called utilities from datasets.synthetic — make_edge_cases (unseeded, non-deterministic), compare_sds_characteristics (its docstring table was factually wrong), validate_sds_detection (vacuous: it compared observed_sds to the very value it was handed, so it always returned True), generate_test_suite, get_sds_info + print_sds_summary (a second, drifting copy of SDSRegistry metadata), and make_large_dataset. Zero callers existed anywhere in the package, tests, docs, or examples.

• SDSRegistry.print_all_analysis_plans and SDSRegistry.get_capability_matrix (same finding: no callers).

• Dead branches: the Excel exporter’s _write_stratified_summary_tab (unreachable since stratified charts moved to the single-entry strata payload) and its Series/scalar effects arms; the plotter’s legacy underscore-name stratification arm and unused _get_data_legend_name; the Study arm of the loss function’s _coerce_ads (assess_loss takes an AnalysisDataSet).

CI / Infrastructure¶

• The Bishop validation gate now bites. validation/e2e_bishop_report.py exits nonzero when any of its 280 assertions diverge from the reference values (previously it only rendered PASS/FAIL into the report), the publish workflow runs the same gate before any release, the four reference artifacts are SHA-256-pinned by tests/test_reference_integrity.py and check out byte-exact on every platform, and CODEOWNERS routes any change to the gate’s inputs through the maintainer.

0.2.0 - 2026-08-31¶

Removed¶

• Dict-emulation on AnalysisResult. result['Xbar'], result.keys(), result.values(), result.items(), result.get(...), len(result), in result and iteration are gone. They were labelled “for backward compatibility” with no released version to be compatible with, and they gave a second, undocumented way to reach chart payloads that shadowed the real accessors. Use result.get_chart(name) for chart data, result.get_statistics(name) for statistics, result.all_charts for the list of chart names, and result.charts for the raw payload map.

• Plotter from processbehavior.plotting.__all__. It was already labelled internal; listing it in the star-import surface made it a semver commitment by accident. Still importable (from processbehavior.plotting import Plotter) for anyone who wants it.

Both are removed now rather than deprecated because nothing has been published yet, so no one is depending on them. After the first release each would have cost a deprecation cycle.

Added¶

• Study.supports_calibration(...) and CalibrationNotSupportedError. Whether a calibration can be applied depended on a private rule, so clients re-derived it — and got it wrong, because the rule is not the one you would guess: Xbar/S stratify on by=[time] only when charting the response, so the same by is refused for the response and accepted for a residual. The predicate takes the same arguments as execute() (minus the calibration itself, which never affects the answer) and returns a bool without running the analysis. The refusal is now a typed exception carrying a context attribute rather than a message to string-match; it subclasses ValidationError, so existing handlers are unaffected.

• pb.formulate(df, ...) — a module-level entry point, so the advertised idiom is literally one expression:

  pb.formulate(df, response='y', factors=['machine'], time='shift').execute().plot()

  Equivalent to ProcessBehavior(df).formulate(...); the class remains the path for the fluent derived-variable verbs, which must attach before formulating. This also retires a naming collision: the docs bound pb = ProcessBehavior(df), shadowing the conventional module alias, so pb.formulate read as module-level when it was an instance method.

• result.statistics(chart, stratum=None) — a type-stable statistics accessor. get_statistics() returns {'N','center','lpl','upl'} for an unstratified result but {stratum: {...}} for a stratified one, so stats['center'] works on one dataset and raises KeyError on the next depending on whether the chart happened to stratify. The new method always returns the four-key dict and asks for a stratum when the answer would otherwise be ambiguous, naming the available strata. get_statistics is unchanged.

• execute(stratify_by=...) — an explicit spelling of by= for X/mR. by composes the subgroup for Xbar/S but splits into separate charts for X/mR; the alias puts which operation is intended at the call site. Same parameter underneath; passing both raises. by= is unchanged and still accepts either meaning.

Fixed¶

• Binning silently dropped every observation equal to the column maximum. With right=False — the default — pd.cut leaves the top edge exclusive, and pandas’ include_lowest only closes the bottom one. So the maximum, and every value tied with it, came back with no category. A row whose category is missing leaves the analysis entirely once the binned column is used as a factor.

  It was silent in the worst way: _range_labels renders that final interval with a closed bracket ([239.03, 243.225]), under a comment saying the rendering exists “so the extreme value is included”. The label promised what the binning did not deliver.

  Affected equal_freq and equal_width, whose edges are fitted from the data so an edge coincides with an observation. sd and breaks bound with ±inf and were never affected, nor was any right=True binning. The fix widens only the edge passed to pd.cut, by one float step — fitted['edges'] and the range labels still report the true quantile / linspace cut points.

• A moving-range chart of residuals now works standalone, not only as a companion. execute(chart='mR', value='R2') raised “Chart type ‘mR’ (moving range) is not supported for residual charts” while execute(chart='mR', value='R2', companion=True) returned exactly the chart it called unsupported. A moving range is the absolute difference between consecutive values of whatever series is plotted, so it is as well defined for a residual as for the response.

  The cause was a missing 'mR' entry in _RESIDUAL_SOLO_STRATEGY_MAP — present in _SOLO_STRATEGY_MAP, and under a comment claiming the two tables held the same entries. That omission failed late and confusingly, and the response to it had been to add an early guard with a friendlier message rather than to add the entry. Both are gone: the dispatch entry is restored and the guard deleted. Output is byte-identical to what the companion path already produced for R1–R5 and their recentered forms.

  why_not('mR', value) had always answered “IS available”, disagreeing with execute; the two now agree. residual_charts still lists no mR (or Histogram) entries — neither chart is ADS-gated — so it remains an incomplete basis for “can this pair be charted”; _residual_pair_problem documents all three regimes.

• Stratified Xbar/S mishandled strata with no replication, three ways from one cause. A stratum whose every subgroup holds a single observation cannot contribute to a subgroup chart; both paths dropped it from the data and statistics but still published it in strata.

  • Stratified S with every stratum insufficient (ADS 2) concatenated an empty list, so a raw pandas ValueError: No objects to concatenate reached the analyst. The ungrouped S path and the stratified Xbar path already raised a self-diagnostic error; this one was the gap. All three now share one message.

  • With some strata insufficient, the dropped stratum stayed in result.strata with no data and no statistics, so result.focus(stratum) raised “No data found for stratum” — the contract _split_strata_by_sufficiency keeps on the X/mR path, which Xbar/S had never adopted. Only focusable strata are published now, and the dropped ones are reported in metadata['insufficient_strata'] rather than vanishing.

  • Companion Xbar + S raised KeyError on a partially-replicated study: Xbar passed its unfiltered stratum list through the shared intermediates while per_stratum held only the computed ones.

  Output on fully-replicated data is byte-identical — verified by diffing strata, statistics and data across all stratified Xbar/S requests on ADS 1 and ADS 3.

• The residual alias noise resolved to R5 — design-condition main effects — when the word means R2 everywhere else in the project (“within-cell noise”, “the noise floor”, “irreducible noise (R2)”). The table contradicted itself, since it also mapped within_cell to R2. noise now resolves to R2.

• Every multi-word residual alias was unreachable. _parse_chart_request tested for an underscore before consulting the alias table, so within_cell was handed to the old-syntax parser, split into within + cell, matched no base chart, and produced a generic “Invalid chart name”. Four of the five aliases could never produce their guidance message. The alias check now runs first; old-syntax guidance is unchanged.

• Three residual vocabularies collapsed into one. RESIDUAL_ALIASES carried its own per-entry label/description — read by nothing, and drifted far enough to label R5 “Noise / Unexplained variation”. The canonical names now live in spc_constants.RESIDUAL_LABELS, which the plotting layer re-exports rather than redefines. Aliases cover R1–R6 (R6 was absent entirely); the unused RESIDUAL_ID_TO_ALIAS reverse map is gone, since several spellings may share a code.

• Benchmark baselines were attributed to the wrong commit. --update-baseline runs before the commit containing the measured code exists, so the recorded git_sha always named the previous commit. The run now also records git_dirty, making the record true — “this commit, plus uncommitted changes” — instead of naming a commit that does not contain the code.

• README understated signal detection as “Rule 1 (3-sigma)”. X/mR evaluate all eight Western Electric rules; Xbar/S evaluate Rule 1 alone, because the run- and zone-based rules need a time order that subgroup comparisons do not have.

• Lane boundaries were malformed when a boundary fell on a duplicated index label. _calculate_lane_boundaries mapped positions back through df.index.get_loc(), which returns a boolean mask rather than an integer for a non-unique label — so the boundary came back with position as a numpy array and label as a Series, neither of which the plotting layer can use. Positions are now computed positionally and cannot express that state.

• DesignReport.missing_combos / extra_combos were wrong for studies mixing integer and float factor columns, reporting every combination as both missing and extra even when the plan matched the data exactly.

  RSG keys were built with df[cols].apply(lambda row: encode_rsg(tuple(row)), axis=1), and materialising a row as a Series upcasts mixed dtypes — so an integer factor beside a float factor encoded as '1.0' rather than '1'. Plan expansion encodes from Python values and produces '1', so observed keys could never match expected ones. A new encode_rsg_series converts per column, which keeps each column on its own dtype, agrees with the plan-side encoding, and is ~31x faster. Six call sites moved to it.

  This changes rsg key strings for studies with mixed-dtype factor columns — the point of the fix. Single-factor and same-dtype studies are byte-identical, which has its own regression test. Not reachable from the Streamlit app, whose factor picker offers non-numeric and low-cardinality integer columns only.

• get_residual('R6') no longer reports “not found” about data the result is holding. A single result object gave three answers: result.dataset['R6'] held 4,000 values, result.residuals omitted it, and get_residual('R6') logged a false “not found” and returned an empty Series — so a caller who did not check len() computed on nothing. The lookup consulted a snapshot taken at construction and never looked at the result’s own dataset. plot_residuals('R6') had the same defect and is fixed by the same change; both now route through one lookup.

  result.residuals still excludes R6, deliberately — see below.

Changed¶

• R6/RCR6 are computed onto a per-request frame. Study._compute_r6 used to write the request residual onto the shared study-level dataset from inside execute()'s validation — so execute() (and even a supports_calibration(value='R6', ...) probe) mutated Study.dataset, and a later unrelated result inherited a stale R6 column that AnalysisResult._locate_residual had to gate against with chart metadata. The computation now lives in Analysis.calculate() (residual_calculator.calculate_r6_residuals) and lands on the requesting result’s own frame: execute() and the probes are pure, the study-level frame is immutable after formulate(), and the metadata gate is gone because the condition it defended against no longer exists. The math moved verbatim — numeric output is bit-identical (verified across 48 R6/RCR6 scenarios on the T100 validation data and unbalanced synthetic designs). Visible side effects: a plain result’s dataset (and its Excel Full_Dataset sheet) no longer shows a stale R6 column from an earlier request, and requesting R6 when R5/R2 are absent now raises ChartNotAvailableError instead of a raw KeyError.

• detect_signals(rules='standard') works as documented. The presets ('standard'/'extended'/'all') were resolved only when passed to SignalConfig(enabled_rules=...) directly; the public detect_signals(rules=...) path assigned the raw string after construction, bypassing the resolution, and raised “Invalid enabled_rules state”. Preset strings now route through the constructor.

• Docs: the six pulled tutorials are back, rewritten and CI-gated. basic-imr returns as Your First X/mR Chart; sds-validation splits into Bishop Reference Validation plus a new Design-State Tour; xbar-s, signal-detection, stratified-analysis and sds1-complete-analysis rejoin the TOC and the nbmake gate (now 13 notebooks). The API reference was rewritten from introspected signatures and is drift-guarded by tests/test_api_reference.py; new comparison and worked-example pages; docs versioning policy documented in CONTRIBUTING.

• The two kinds of VAS residual now have names. spc_constants defines STORED_RESIDUALS (R1-R5, RCR1-RCR5 — computed at formulate(), independent of by=) and REQUEST_RESIDUALS (R6, RCR6 — computed at execute() from that request’s by=). R6(by=['A']) and R6(by=['B']) are different series, so there is no canonical study-level R6 and result.residuals correctly omits it. Previously both kinds were just “residuals”, so an enumeration that omitted R6 was indistinguishable from a bug. (“derived” is deliberately not used — derivations.py owns it.)

• BREAKING (return contract): get_residual raises instead of returning an empty Series. Unknown codes, and residuals genuinely absent from a result, now raise ValidationError with a message saying which case applies and what to do. The empty return was the only silent-wrongness path in the public API.

• get_residual will not hand back another request’s numbers. Computing R6 writes its column onto the study-level dataset, so a result created afterwards inherits an R6 it never asked for. The lookup gates on the result’s own chart metadata, so that case raises rather than returning values from a different by=.

• why_not() no longer contradicts the error that sends users to it. Asking for an unavailable chart x residual pair raised a correct ChartNotAvailableError ending “Use study.why_not(‘Xbar’, value=‘R2’) for details” — and that call replied “‘Xbar’ (R2) is not a recognized chart type”, which is false, then referred on to study.support, which had no row for the pair. why_not answered only from support, whose residual rows enumerate just the potentially valid pairs, so “no row” was conflated with “unknown chart”.

  Both why_not and execute now answer from one predicate (Study._residual_pair_problem), so they cannot disagree. why_not also distinguishes an unrecognised chart name, an unrecognised residual code (R9), and a recognised chart in an invalid pairing — three cases that previously produced the same wrong message — and accepts recentered (RCR5) and lowercase forms, matching what execute already normalised.

Changed¶

• BREAKING (validation only): execute(chart='S', value='R1') now raises. R1 was exempt from the chart x residual check, so residual_charts claimed R1 was Xbar/X-only while execute accepted any chart — the two authorities genuinely disagreed, and why_not could not be made correct while both existed. The exemption is deleted; residual_charts now governs outright. Nothing informative is lost: R1 is the response shifted by a constant, so its S chart is byte-identical to the response’s S chart (same N, center, lpl, upl — verified). Use chart='Xbar' or chart='X' for R1, or the plain response S chart. Histogram and mR residual behaviour is unchanged; both remain structurally exempt by design.

Performance¶

• Stratified charts are ~40x faster — a stratified X at 1M rows goes from 26.5s to 0.66s, bringing them into the same range as the ungrouped path.

  _split_strata_by_sufficiency decided which strata are publishable by running a full-column comparison inside a loop over strata — O(strata × rows), or ~126M element comparisons and 632 intermediate DataFrames at 200K rows, to learn 632 integers. It was 89% of a stratified execute. It now counts once with value_counts(). The companion membership test moved from a list to a set, retiring an O(strata²) scan that was invisible at 632 strata and quadratic beyond.

  The sufficiency rule is unchanged — a stratum with fewer than min_obs rows after the first-mR drop is still unpublishable, and every published stratum is still focusable.

  scripts/benchmark.py gains an execute_x_stratified scenario. This defect survived because nothing measured the stratified path: the existing by=[] scenario never enters it. The new scenario is the guard against it returning.

• execute() on X/mR charts is ~15x faster — 4.10s → 0.27s at 1M rows, same machine (Xbar improves further too, 0.29s → 0.17s). Two per-row loops, both now array operations:

  • _add_beyond_limits_flag called detect_beyond_limits once per observation — ~1,000,000 Python calls at 1M rows. It is now a nested np.where. The scalar detect_beyond_limits is unchanged and stays the reference the Bishop validator exercises. This single method serves twelve call sites, so every chart type gains.

  • _calculate_lane_boundaries (the X-chart vertical dividers — visual only) combined collapsed factors with a row-wise .agg('_'.join, axis=1) and then called df.index.get_loc() once per boundary, which is not O(1) on these frames. Both are now array operations.

  Signal classification is unchanged — the 280 Bishop assertions cover it.

• execute() is ~10x faster on Xbar/S charts — 2.82s → 0.29s at 1M rows, same machine. The chart builders computed control limits by calling the scalar calculate_limits once per subgroup through DataFrame.apply(axis=1), each call constructing a pd.Series to carry two numbers. At 1M rows that is ~50,000 Python calls per chart. A new calculate_limits_vectorized does the same arithmetic on whole columns.

  calculate_limits itself is unchanged and stays the scalar reference — it is what the Bishop validator exercises, so keeping it independent means those 280 assertions remain an external check on the fast path rather than a check of it against itself. Conversion is deliberately partial: the four primary Xbar/S sites are converted; phase-segment and per-stratum sites iterate over a handful of rows, were not hot when measured, and still use the scalar form. That is recorded in the function’s docstring so a future reader does not mistake partial conversion for completeness.

• formulate() gains a further ~20% on designs with multiple factors (SDS-2 at 1M: 6.49s → 5.11s), from the same change described under Fixed below.

• ProcessBehavior(df) is ~19x faster — 4.09s → 0.21s at 1M rows × 50 columns, same machine. It was the single most expensive step in the pipeline, costing more than formulate(), which is not where any of the documentation points.

  Two changes, both output-identical (same values and same dtypes — client code reads post-init dtypes to decide what a column can be used for):

  • The garbage-token scan ran on every column. A token is a string, so numeric, datetime and boolean columns cannot contain one; they are now skipped. The test is “is text-like”, not “is not numeric” — a categorical of strings can hold a token and must still be scanned.

  • Numeric-formatting cleanup ran per row. It now cleans the distinct values and maps back, on plain object columns whose cardinality is under 5% of their length. Subtlety: the 80% acceptance threshold is frequency-weighted, so it is re-scored against the full column rather than the distinct values — a column of 9,900 copies of '1' plus 100 labels converts by row (99%) but not by distinct value (1%). The shortcut is restricted to object because Series.map preserves extension dtypes: mapping a categorical returns a categorical of ints where the direct path returns int64.

  Design-state detection is unaffected, and provably so: _build_structure_view normalises missing tokens and canonicalises the kt columns itself on a minimal projection, so N_kt is identical whether or not __init__ cleaned first. That property now has its own test. Cleaning also stays eager and total — deferring it to formulate() would leave a ['235.5', '*', '237.2'] column non-numeric at the point a client builds its column pickers, hiding the very column cleaning exists to rescue.

• formulate() is 1.4-3.8x faster. Observed-design-state detection computed N_kt (valid responses per cell) with groupby(...).apply(lambda s: s.notna().sum()) — one Python round-trip per cell. GroupBy.count() computes exactly the same thing in Cython. Cells whose responses are all NA still yield 0, so the “attempted but empty” semantics that ODS 4-6 detection depends on are unchanged, as are all N_kt values, design-state classifications, residuals, limits, and the 280 Bishop reference assertions.

  The win scales with cell count, so it is largest where cells are singletons:

  1M rows	before	after
  SDS-2 (no replication) formulate	25.17s	6.56s	40K → 152K rows/sec
  SDS-1 (full replication) formulate	3.13s	2.25s	319K → 444K rows/sec

  Profiling also corrected a long-standing misattribution: the MA2 sort, previously blamed for SDS-2’s cost, is 0.09s at 1M — 0.4% of formulate. The perf-suite docstrings said otherwise and have been fixed. Peak memory is ~5% higher (3.9x input, against a 6x cap).

Fixed¶

• R6 chart titles rendered as R6 (R6). _RESIDUAL_LABELS had no entry for R6, and _generate_title resolves labels with .get(code, code), so the code was printed in place of its name. R6’s computation was never affected — it is validated against Bishop’s Minitab reference in validation/e2e_bishop_report.py — this was display only.

• R1 chart titles carried R2’s concept. R1 was labelled Within-Subgroup, but Bishop §13.1 (Centering the Original PM Data at 0) defines R1 = Y_ktn − Ȳ.. — the response re-expressed as ± about zero, a location shift, not a within-subgroup quantity. Now Response Centered at 0.

• R1 was advertised but not chartable. study.residuals listed R1 while study.residual_charts omitted it entirely, so support / why_not() silently had nothing to say about it. R1 is now in the allowlist for Xbar and X only — it differs from the response by a constant, so an S or mR chart of R1 would duplicate the response’s dispersion charts exactly.

Changed¶

• Residual labels adopt Bishop’s design-condition vocabulary. Chart titles, the user guide, the README, and the tutorials now read Design Condition Main Effects (R5) and Design Factor Main Effects (R6) in place of “Factor Effects” / “Factor Main Effect”, matching the “process design conditions (PDC)” terminology already used by loss_function.py. R2 is Within-Cell (was Within-Subgroup Variation) and R4 is Time Main Effects. Display-only: residual codes, value= arguments, dataset column names, and every computed value are unchanged, and all 280 Bishop reference assertions pass untouched. Callers passing an explicit title= are unaffected.

• The user guide documents R1 as a chartable diagnostic. docs/user-guide/residuals.md gains an R1 section (it previously appeared only in the formulas appendix), and the availability table gains an R6 column. The README documents R6 for the first time.

• Demo dataset load_coffee_shop() rebuilt into a fuller process-behavior story. New schema — date, year_week, week, day_of_week, hour, daypart (Peak/Off-peak, the process-design factor), wait_sec — dropping the old subgroup_id and reading_no columns (data-contract change). Formulate with factors=['daypart'], time='date' for a complete (SDS 1) design. The series now carries three teachable events: a week-8 espresso-machine improvement (Xbar shift), a ~one-week week-12 POS learning curve (a run, not a lone outlier), and a weeks 14–16 new-hire spell where the mean holds but within-subgroup spread doubles (an S-chart signal). The before/after eras (~240s → ~205s) are preserved. Regenerated deterministically by scripts/generate_coffee_shop_demo.py. New tutorial docs/tutorials/coffee-shop.ipynb walks the whole story; the standalone calibration.ipynb tutorial was retired (calibration is now shown in-context there).

• Design Report now labels the observed/sampling lineage row SDS (Sampling) instead of ODS (Observed), aligning with Bishop’s “Sampling Design State” terminology (the lineage reads Planned → Sampling → Analytical). Display-only: internal attributes (study.observed_design_state) and all values are unchanged.

• Observed Design State (ODS) now reports Bishop’s full R = K×T design state even without an explicit sampling plan. The no-plan path previously classified only over cells that contained data, so sparse observational data (many absent condition×time combinations, no */NA markers) was reported as complete/ semi-complete (SDS 1–3). It now classifies over the full grid — the cross of the distinct observed process-design conditions with the distinct observed production times — so genuinely absent (condition, time) cells count as N_kt=0 and the design is correctly detected as incomplete (SDS 4/5/6), matching Bishop’s definition. The grid uses the composite observed condition tuple (not the independent cross of each factor’s levels), so nested / non-crossed designs are not over-flagged. This is a diagnostic-only change: ODS is lineage/reporting only. The Analytical Design State (ADS) — which drives valid charts, R2 method, residual availability, and variance decomposition — is computed independently on tidy data and is unchanged, as are all chart/residual/variance outputs. Datasets that declare empties via */NA rows or via a plan (e.g. the PBTESTDATABASE_T100 reference) are unaffected.

• chart_table (the per-chart display table) now uses a 1-based position index (matching the chart’s plotted x-axis, which starts at 1) instead of a 0-based counter, and adds the source-row id as an “Obs” column on Individuals (X/mR) tables for traceability. Xbar/S tables are unchanged (their rows are subgroup aggregates).

• obs_id is now the 1-based source-row id (raw→analytic lineage), replacing the previous 0-based post-cleaning counter. It is stamped on the raw frame before cleaning, so every analytic row traces back to its source-file row; rows dropped in cleaning leave gaps in obs_id (e.g. 1, 3, 4, 5). Ordering is unchanged — obs_id remains the (cell_key, obs_id) sort tie-breaker and the SDS-4 implicit-time key — and the “Obs N” shown in signal summaries and plot hover is now the source-row number. Data-contract change: consumers relying on obs_id starting at 0 or being contiguous should update.

Fixed¶

• Individuals (X) and Moving-Range (mR) charts now label the y-axis “Individual Value” / “Moving Range” instead of the response variable name. Fixed in Plotter._get_yaxis_label (keyed on chart type), so it applies to residual X/mR charts too (e.g. the R2 “Unexplained Effects” chart). Xbar/S labels (“Sample Average” / “Sample Standard Deviation”) are unchanged, and an explicit .plot(yaxis_title=...) override still takes precedence.

• Signal detection no longer aborts on small groups. detect_signals previously raised ValueError("Insufficient observations…") whenever a group had fewer points than the most-demanding applicable run-rule (Rule 7 needs 15) — which broke detection on small stratified subgroups. It now evaluates the rules the group supports and reports the rest via SignalResult.rules_skipped (plus is_partial / evaluation_status accessors), so “no signals” is distinguishable from “not fully evaluated”. The genuine input guards (empty data, missing limit statistics) now raise ValidationError instead of raw ValueError; ValidationError additionally subclasses ValueError so existing except ValueError handling keeps working.

• Input data cleaning no longer coerces a pre-parsed datetime64 column to int64. _try_clean_numeric_strings guarded only numeric dtypes, so a datetime64 column passed to ProcessBehavior(df) (e.g. from pd.read_csv(..., parse_dates=...)) was silently converted to nanosecond integers (pd.to_numeric succeeds on datetimes). It now skips datetime and Period dtypes, mirroring DataPreparation._detect_and_convert_type. String date columns are unaffected (still parsed to datetime64 at formulation).

Added¶

• Derived variables — create new columns from existing ones with fluent, pipeable verbs on ProcessBehavior that return a new (immutable) instance: pb.transform(column, function, ...) (log/ln, log10, sqrt, arcsin = arcsin√x for proportions, inverse, square, power, zscore) and pb.bin(column, method=..., n=..., breaks=..., bin_labels=...) (equal_freq/equal_width/breaks/sd → an ordered categorical). Derived columns become referenceable by response=/factors=/time= after formulate(), which is the immutability boundary that freezes data-dependent fits (bin edges, z-score μ/σ) onto the new Study.derivations. A binned bin_labels='ordinal' factor now charts in bin order (Low → High). Derivations are serializable specs (Derivation with a stable id, to_dict/from_dict round-trip) built by the same Derivation.transform / Derivation.bin factories the application’s attach-free live preview uses via evaluate(spec, column); validate(spec, dataset) returns structured pass/fail (label collisions, breakpoint/label-count checks) without raising. Domain violations are reported as structured data (count + row index), resolved at formulation per on_invalid ('error' raises with a count; 'na' coerces) or a shift= constant. Inspect/edit pending specs with pb.derivations / remove_derived / replace_derived (keyed on id). Box–Cox is intentionally deferred (no scipy dependency); derived-on-derived chaining and custom expressions are out of scope for v1.

• Named Calibrations — standards-given control limits. Calibration(label, mean, sigma) (top-level export) is a frozen value object pinning a chart’s limits to a known mean and within-subgroup individual sigma instead of data-derived estimates. Attach by label with study.with_calibration(cal) (immutable; returns a new Study) and apply per call via study.execute(..., calibration=cal_or_label). The sigma is applied forward and used as-is — never run back through c4/d2/b3/b4 to “recover” a process sigma. Location charts place limits constant-free in sigma (X/residual: center ± n_sigma·σ; Xbar: center ± n_sigma·σ/√N); dispersion-statistic charts carry their sampling-distribution constants (S: center c4(N)·σ, B5(N)·σ … B6(N)·σ; mR: center d2·σ, 0 … D4·d2·σ). Plain residuals center at 0 (mean ignored); raw response and recentered residuals center at calibration.mean. n_sigma composes on Xbar/S; calibrated X/mR stay 3-sigma and reject a non-default n_sigma. Result metadata carries a limits_source='calibration' badge. calibration=None (the default) is byte-for-byte unchanged. Stratified and phased calibration are rejected with a clear error (follow-up).

• load_coffee_shop() (top-level + processbehavior.datasets): a bundled demo dataset of coffee-shop wait times with a deliberate process change at week 8, returned as a ready-to-formulate ProcessBehavior. Backs the new “Capability — Before vs. After” tutorial (docs/tutorials/process-capability-before-after.ipynb), which demonstrates time-windowed capability on the dataset.

• Time-windowed capability views: study.capability(..., window=(start, end)) (and assess_capability(..., window=...)) render current capability on a before/after subset of the study’s declared time axis — an integer sequence or a date, half-open start <= t < end with either bound None for open. This is a view over the immutable analytic dataset: the windowed observed values drive current stats and the potential centering, while the potential noise floor (σ̂_R2) stays the full-study pooled R2 — never re-estimated on the subset. Thin windows refuse (n < 8) or warn (8 ≤ n < 30); the chart self-describes the window and labels the pooled potential basis. window=None (the default) is byte-for-byte unchanged.

CI / Infrastructure¶

• Docs notebooks are now executed as part of CI via pytest --nbmake on the ubuntu / Python 3.13 cell. The allowlist covers docs/getting-started/quickstart.ipynb, docs/tutorials/process-capability.ipynb, and docs/tutorials/loss-function.ipynb — the three notebooks known to execute cleanly against the current API. Catches future versions of the chart='Imr'-style typos that lived in the quickstart for months. nbmake is added to the [test] extra.

• publish.yml now runs the full test matrix (3 Python versions × 2 primary OSes + macOS / 3.13) before building and uploading to PyPI. Previously a tag fired build → twine check → publish with no test step, so a regression on main between the last CI run and the tag push could publish a broken wheel.

• .pre-commit-config.yaml bumped ruff from v0.6.4 to v0.14.9 so contributors’ pre-commit hooks align with editor-bundled ruff versions. Dependabot now tracks pre-commit revs alongside pip and github-actions. The bump applied ruff-format to 87 files (pure whitespace + import-sort changes; no behavior change).

• Six tutorial notebooks in docs/tutorials/ are not yet in the nbmake gate — basic-imr, signal-detection, stratified-analysis, xbar-s-analysis, sds-validation, sds1-complete-analysis — because they reference stale API (Study.sds attribute removed, chart names changed, missing companion=True). Tracked for rewrite in a follow-up; the CI gate catches new bugs while these are getting addressed.

Added¶

• Two tutorial notebooks added to the published docs site: docs/tutorials/process-capability.ipynb and docs/tutorials/loss-function.ipynb. Both existed on disk but weren’t in the MyST TOC, so they didn’t deploy. Re-executed against the current API.

• README Validation section explicitly bounding the Bishop-reference claim: 280 numerical assertions pass for ADS 1, ADS 2, ADS 3 (the three complete-design states). ODS 4–6 detection works; Bishop end-to- end coverage of incomplete-grid scenarios is on the 0.2.0 roadmap.

• PyPI keyword expansion: variance-analysis, bishop-vas, wheeler, design-of-experiments — surfaces the library to searches for the differentiated methodology.

• GitHub repo description, homepage, and topics set via gh repo edit so the repo landing page reflects the differentiator at a glance.

• processbehavior.types module formalizing the chart-payload contract as TypedDicts (ChartPayload, ChartStatistics, HistogramExtras, ChartMetadata, Charts type alias). Producer return types in analysis.py and consumer signatures in plotting/plotter.py and plotting/renderers.py now reference the typed contract so mypy catches key drift at edit time. The strata-list and Xbar dead-branch bug classes (commits f938fdf and 1444b63) were producer/consumer disagreements about this shape; the TypedDicts close that gap.

• make_design(state=N, ...) is now the canonical synthetic-data generator, using the three-state vocabulary (PDS / ODS / ADS). The former make_sds(sds=N, ...) dispatcher has been removed (it was never released) — all internal call sites migrated. The ignored n parameter is gone from the canonical signature. The per-state generators make_sds1..make_sds6 remain available.

• SDSResult is re-exported at the top level so users can from processbehavior import SDSResult for type hints on study.observed_design_state and study.analytical_design_state.

• DesignReport.factors_table — preferred name for the factor-level summary DataFrame. The legacy DesignReport.factors continues to work as an alias; rename avoids confusion with Study.factors (which is a list[str] of column names, not a DataFrame).

• Literal[...] type hints on stringly-typed enum parameters: study.execute(chart=, value=, n_mode=), result.plot(theme=) and the three sibling plot methods, MaximumInformationResult.plot(view=), and CapabilityResult.plot(view=). IDEs now offer autocomplete for the valid values; arbitrary strings still work for custom themes / forward-compat.

Removed¶

• 5 stale planning docs at the root of docs/ removed from the source tree: release_gate_0_1_0.md, pre_release_audit.md, api_ux_review.md, chart_statistics.md, sampling_plan_design.md. They were never linked from the MyST TOC but would have deployed as orphan pages.

Changed¶

• docs/myst.yml navigation label “Sampling Design States” renamed to “Design-State Lineage (PDS / ODS / ADS)” to match the three-state vocabulary the page now teaches. Copyright bumped to 2025-2026.

• AnalysisResult.get_statistics() no longer uses the string literal 'Varies' as a sentinel for variable limits. The affected stats fields (N, lpl, upl) are now None when limits vary, and a new optional 'limits_vary': True flag is added to the dict so callers can detect variable limits without comparing against magic strings. Fixes the type-pollution where stats['upl'] > x would raise TypeError on charts with variable cell sizes or phased limits. Pre-release breaking change: code that does stats['upl'] == 'Varies' must migrate to stats.get('limits_vary') or stats['upl'] is None.

• AnalysisResult.get_statistics() returns a unified shape across every chart type: {N, center, lpl, upl}. The Histogram chart additionally carries {mean, std, n} as extras (mean is an alias for center; n is an alias for N); its lpl and upl are None because a histogram has no control limits. Previously the Histogram path returned {mean, std, n} only, contradicting the documented contract.

• Study.observed_design_state now raises RuntimeError with a clear message when accessed on a Study instance that was not built via ProcessBehavior.formulate(). Previously it silently returned None while typed as SDSResult.

Changed¶

• Design-state terminology rolled out across the user surface. The library has always reported three states (Planned / Observed / Analytical Design State), but documentation, error messages, and the module docstring previously talked about “SDS” as if it were a single concept. The user-facing surfaces now consistently use PDS / ODS / ADS for the states and reserve the integer 1–6 codes for Bishop’s reference scale (which each state carries on its .sds field). Touched: __init__.py module docstring, README.md, CLAUDE.md, docs/intro.md, docs/getting-started/quickstart.ipynb, docs/getting-started/installation.md, docs/sds-detection.md, docs/user-guide/sds-detection.md, docs/reference/sds_definitions.md, and the public docstrings of Study, ProcessBehavior, AnalysisResult.

• Study.__repr__ lineage block now reads PDS (Planned) / ODS (Observed) / ADS (Analytical) and drops the redundant SDS prefix on the integer code.

• User-facing error messages from study.execute() (“Chart type X is not valid for ADS N” instead of “for SDS N”) now name the analytical state explicitly.

• Internal infrastructure (SDSResult, SDSRegistry, SDSAnalysisPlan, sds_detector.py, the .sds field on each state, test_sds_detector.py, test_sds.py) is unchanged — a deeper internal rename is deferred to a future breaking-change pass.

• Yesterday’s 0.1.1 entry that claimed “Sampling Design State (SDS)” as canonical terminology is superseded by this pass.

Fixed¶

• make_sds(sds=4), make_sds(sds=5), make_sds(sds=6) now produce data that classifies as ODS 4 / 5 / 6 respectively. Prior implementations were scenario archetypes (single-stream time series, nested hierarchy, regime-change sparse sampling) that all classified as ODS 2 (complete grid, no replication) regardless of the requested state. The new generators produce Bishop’s structural incomplete-grid shapes via empty (NaN-y) cells. After tidying, ODS 4/5/6 collapse to ADS 1/2/3 as Bishop’s table prescribes.

• New tests/test_design_state_lineage.py (21 tests) pins the make_sds(sds=N) → ODS N contract so this drift cannot recur.

0.1.1 - 2026-05-18¶

Changed¶

• Synced validation dataset to Tom Bishop’s corrected golden copy (validation/PBTESTDATABASE_T100.csv, replacing TABVASTESTDATABASE.csv). PM SDS 4/5/6 columns are now labeled so PM SDS N data classifies as ODS N (the prior file had a cyclic offset that the old TestSDSRenumberDrift test class documented). PM KNOWN column removed. PM SDS 1/2/3 + factor, time, and PM INERT columns are byte-identical. The e2e Bishop validator remains all-green; TestSDSRenumberDrift is replaced by TestSDSColumnLabelAlignment with two cleaner parametrized invariants.

• Documentation, docstrings, and the quickstart notebook now use the canonical “Sampling Design State (SDS)” terminology consistently. The prior “Design State (DS)” phrasing in __init__.py, the installation guide, and the quickstart was non-canonical.

• study.execute(), AnalysisResult.get_chart(), and get_statistics() docstring Raises blocks now name the actual exception subclasses (ValidationError, ChartNotAvailableError) instead of bare ValueError / KeyError.

Fixed¶

• Xbar center line now correctly computes Bishop VAS’s mean of (factor × time) cell means on the charted column for both response and residual charts. Previously a dead-code branch in _calculate_xbar caused the center to fall through to an observation-weighted mean (df[value_col].mean()), producing a small (<0.05) divergence from Bishop’s reference on unbalanced designs. Surfaced on SDS 3 R3 (recentered) Xbar by PRODUCTION_TIME, where the center shifts from 237.81 to the methodologically-correct 237.83. Balanced designs (SDS 1, SDS 2’s degenerate single-obs cells) and stratified Xbar charts were unaffected.

• AnalysisResult.strata now returns the order-preserving intersection of every chart’s strata list. Previously it returned the first chart’s list, which for X+mR companion results inherited the X chart’s full strata even when mR had dropped first-row-per-stratum on single-observation cells. result.focus(stratum) then raised on those strata, breaking any caller that drove .focus() from .strata. The mR chart’s published strata list is also now filtered to exclude insufficient strata.

• AnalysisResult.chart_table() previously raised ValueError: You are trying to merge on object and int64 columns when a chart’s by-column had been stringified during construction (e.g. PRODUCTION TIME → object) while the analysis dataset kept it numeric. The n-join now coerces both sides to str when the join-key dtypes differ, and falls back to skipping the n-join entirely if the merge still fails — the table renders either way. Surfaced on chart='Xbar', by=[time_var], value='R4', companion=True, recentered=True.

0.1.0 - 2026-05-03¶

Initial public release. The 0.1.x line is alpha — the public API is settling and may change between minor versions until 1.0.

Added¶

Core API¶

• ProcessBehavior wrapper for pandas DataFrames with IDE auto-completion for column references via pb.cols

• Two-step analyst workflow: pb.formulate(...) → study.execute(...) → AnalysisResult

• Automatic detection of Bishop’s six Sampling Design States (SSDS 1–6) on raw data before NA handling, including incomplete designs (SDS 4–6)

• Self-diagnostic exceptions (ColumnNotFoundError, FactorNotFoundError, ChartNotAvailableError, ValidationError) reporting what is available and how to fix the call

Charts¶

• Xbar, S, X (Individual), mR (Moving Range), Histogram with correct limit calculations per Bishop’s VAS methodology

• Stratified X/mR analysis: a single combined chart with per-stratum limits via study.execute(chart='X', by=[...]) and result.focus(stratum)

• Phased limits (phased=True) for run-segmented X/mR charts

Variance Analysis (VAS)¶

• Residuals R1–R5 (and the rounded R6) for factorial designs in DS 1–3

• Variance decomposition for Xbar/S; rsg-based stratification for X/mR

• Effects analysis: factor effects, time effects, and factor × time interactions

• DesignReport for plan-vs-observed comparison

• why_not() explanations for unavailable chart types

Capability and Information¶

• Capability indices (Cp, Cpk, Pp, Ppk) via CapabilityResult with SpecLimits

• Loss-function analysis (LossResult)

• Maximum-information analysis (MaximumInformationResult)

Signal Detection¶

• Western Electric rules (1–8) configurable via RuleSet

• SignalDetector and SignalResult for programmatic access

Visualization¶

• Plotly-based interactive charts with zone shading and signal markers

• Themed plots (processbehavior, minimal, dark, ggplot) via ChartTheme, register_theme, get_theme, list_themes

• result.plot(), faceted plots for stratified analysis

Export¶

• Excel export with result.to_excel(path) (requires [excel] extra)

• HTML export of interactive figures

• Static image export (requires [images] extra)

Datasets¶

• make_sds(sds=N, seed=...) synthetic dataset generators for SDS 1–6, re-exported at the top level for pb.make_sds(...)

• Edge-case generators (make_edge_cases)

• Bishop’s PBTESTDATABASE_T100.csv reference is shipped in the source distribution for validation

Packaging¶

• PEP 561 typed package (py.typed marker)

• PEP 639 license metadata (License-Expression: Apache-2.0)

• Optional dependencies: [excel], [images], [test], [lint], [docs]

• Supports Python 3.9–3.13

Dependencies¶

• numpy >= 1.23

• pandas >= 2.0, < 3

• natsort >= 8.0

• plotly >= 5.18, < 7