Docs & terminology reconciliation: ODS ↔ SDS ("Sampling") across the codebase

[cnicholas]

Summary

The Design Report now labels the observed lineage row SDS (Sampling) (Bishop's
"Sampling Design State" terminology) instead of ODS (Observed) — see study.py
DesignReport.__repr__. That leaves the rest of the codebase (docs, tutorials, README,
docstrings, the make_sds* API, and internal identifiers) still using ODS / Observed
Design State, and it collides with the fact that "SDS" is already used as the umbrella
term for the whole Sampling-Design-State concept. This issue tracks reconciling the
terminology across the codebase.

This is not a mechanical find-replace — it needs a naming decision first (see below),
and it touches methodology-facing pedagogy, so it should be settled with Tom.

Background — what prompted this

• Tom/Bishop call the state that results from executing the sampling plan the Sampling
  Design State (SDS). The library elaborated Bishop's single SDS into a three-stage
  lineage: PDS (Planned) → ODS (Observed, raw) → ADS (Analytical, tidy).
• Tom looks at the Design Report and expects the observed row to read "SDS", so we
  relabeled that one row (display-only; internal study.observed_design_state unchanged).
• The rest of the library still says "ODS", producing an inconsistency between what the
  app shows and what the docs teach.

The core decision (blocker before any sweep)

"SDS" already means the umbrella concept, pervasively:

• "Sampling Design State / SDS" appears 45× in docs/sds-detection.md, 45× in
  docs/tutorials/sds-validation.ipynb, 16× in docs/tutorials/loss-function.ipynb.
• The public generators are literally make_sds1() … make_sds6() (exported in
  processbehavior/datasets/__init__.py); doc files are named sds-detection.md,
  sds_definitions.md.
• Internal machinery keeps the name: SDSResult, SDSRegistry, sds_detector.py, and the
  integer .sds (1–6) field carried by all three states.
• Sharpest inconsistency: make_sds4()'s own docstring says it "Generates Observed
  Design State 4 (ODS 4) data" — an sds-named function documenting an ODS output.

So PDS/ODS/ADS are the three lineage stages under the SDS umbrella. Blindly
replacing ODS→SDS makes "SDS 1–6" (the general scale) and "SDS (Sampling)" (one stage)
ambiguous. We must first decide what the three lineage nodes are called once "SDS"
is (or isn't) claimed by the observed stage. Options to weigh with Tom, e.g.:

1. Keep the umbrella = SDS; keep the stages = PDS/ODS/ADS. Revert the Design Report
   row to ODS (Observed) and instead teach clearly that "the SDS you compute is the ODS
   stage." (Smallest change; resolves the app label the other direction.)
2. Umbrella = SDS; rename the observed stage to SDS (Sampling) everywhere, and pick
   new disambiguation for the general scale (e.g. always say "the design state" / "state
   1–6"). Requires rewriting the three-state pedagogy + reconciling make_sds*.
3. Keep ODS internally (attributes/classes) but standardize the user-facing label
   as "SDS (Sampling)" — i.e. the split we have now, made consistent in docs/prose only,
   with a short "ODS = the SDS stage" note. (Medium; no API/identifier churn.)

Sites requiring attention

Counts are of \bODS\b / "Observed Design State" in source files (generated
docs/_build/** excluded — the Docs workflow rebuilds it; do not hand-edit).

User-facing display (DONE / verify against decision)

• processbehavior/study.py DesignReport.__repr__ — observed row label (already
  SDS (Sampling); revisit if decision goes option 1).
• processbehavior/study.py compact Study.__repr__ / _repr_html_ tokens
  ods=…, ads=… (~2467, 2493) — not changed (notebook-only, not shown in app);
  align to the decision.

Docs (source) — ~63 hits / 11 files

File	hits
docs/user-guide/sds-detection.md	21
docs/getting-started/key-concepts.md	10
docs/tutorials/sds-validation.ipynb	8
docs/intro.md	6
docs/user-guide/formulation.md	5
docs/sds-detection.md	4
docs/getting-started/quickstart.ipynb	4
docs/getting-started/installation.md	2
docs/reference/sds_definitions.md	1
docs/reference/api.md	1
docs/myst.yml	1

Conceptual anchors that would need genuine rewriting (not sweep): key-concepts.md,
user-guide/sds-detection.md, reference/sds_definitions.md.

README — 11 hits

README.md (also uses "SDS" as umbrella 3×).

Python docstrings / prose — ~57 lines / 6 files

File	hits	notes
processbehavior/datasets/synthetic.py	28	make_sds4/5/6 docstrings describe output as "ODS 4/5/6" — the sharpest make_sds ↔ ODS clash
processbehavior/process_behavior.py	10	formulate/ODS-detection prose
processbehavior/analysis_dataset.py	7	observed_sds param docstring
processbehavior/study.py	5	observed_design_state property docstrings
processbehavior/__init__.py	5	module docstring "Observed Design State (ODS)"
processbehavior/analysis_result.py	1

Public API naming (decision-dependent — API change if renamed)

• make_sds1 … make_sds6 (processbehavior/datasets/synthetic.py, re-exported in
  processbehavior/datasets/__init__.py __all__). Renaming = breaking API change; the
  docstrings' "ODS n" wording is the reconcilable part even if names stay.

Internal identifiers (only if we go beyond display)

• observed_design_state (attribute on Study and AnalysisDataSet), _ods_result,
  observed_sds, SDSResult, SDSRegistry, sds_detector.py. CLAUDE.md already flags
  these as legacy names for a three-state model; likely keep, but list them so the
  decision is explicit.

Authoritative definition to update alongside

• CLAUDE.md "ADS drives everything" bullet (the PDS/ODS/ADS + "legacy SDS" vocabulary
  paragraph) — must match whatever we land on.

Out of scope / already shipped

• Design Report observed-row label → SDS (Sampling) (display-only; shipped).
• Generated site output under docs/_build/** (rebuilt by the Docs workflow).
• Detection logic / values (unchanged; this is terminology only).

Suggested approach

1. Settle the naming decision (options above) with Tom — this is a methodology-facing
   call, not a code style one.
2. Update the authoritative anchors first: CLAUDE.md, docs/reference/sds_definitions.md,
   docs/getting-started/key-concepts.md.
3. Sweep prose/docstrings/README consistently with the decision; reconcile the
   make_sds* docstrings ("ODS n" → agreed term).
4. Decide separately whether to rename identifiers / make_sds* (API impact) or keep them
   with a documented "these legacy names map to the stage" note.
5. Rebuild the Jupyter Book and verify the Docs workflow passes.

Acceptance criteria

• A single, documented terminology model (umbrella vs three stages) written down in
  CLAUDE.md + docs/reference/sds_definitions.md.
• Docs, README, and docstrings consistent with it (no stray ODS (Observed) unless
  intentional per the decision).
• make_sds* docstrings no longer contradict the chosen terms.
• Design Report / Study repr labels consistent with the decision.
• Docs build green.

Measured on main after the SDS (Sampling) Design Report relabel (commit 8194d00).

[cnicholas]

Flagging a near-miss, since this issue is what prevented it.

An implementation pass on 2026-08-24 worked from a review that listed the Design Report's SDS (Sampling) row as an inconsistency to fix, and relabelled it to ODS (Observed). That is option 1 of the three this issue lays out — chosen unilaterally, before the decision this issue exists to hold.

Reverted in d886341. The label is back to SDS (Sampling) and there is now a comment at the site in study.py pointing here, so the next reader (or the next review) finds an open question rather than what reads like a typo.

Nothing else in that pass touched ODS/SDS naming, so this issue's scope is unchanged. Still awaiting the naming decision with Tom.