Skip to content

Document settings, repeated runs and scenario comparison - #224

Merged
TimoDiepers merged 6 commits into
mainfrom
docs/settings-and-scenarios
Aug 24, 2026
Merged

Document settings, repeated runs and scenario comparison#224
TimoDiepers merged 6 commits into
mainfrom
docs/settings-and-scenarios

Conversation

@TimoDiepers

Copy link
Copy Markdown
Member

Merge last. This sits on top of #219, #222 and #223, because it documents features from all three — it merges #222 into #223's branch so the docs can reference create_missing and compare() in the same breath. Until those land, the diff below includes their commits; the two commits belonging to this PR are the merge and the docs commit at the tip.

Strategy: one spine, one topic page — not two tracks

run() calls the same four steps the Walkthrough teaches, in the same order. Documenting it as a parallel "track" would imply a choice that doesn't exist, duplicate every concept, and leave newcomers picking between two ways to do one thing — while the procedural API stays necessary anyway (you inspect tlca.timeline between steps, re-run one step with different arguments).

So this follows the shape scikit-learn uses for Pipeline/GridSearchCV: fit/predict stay the spine, and "run many of them" is its own topic page that assumes you already know the spine. Same pattern as requests (Quickstart vs. Session in Advanced) and pytest (plain asserts, then fixtures).

The Walkthrough is untouched, except one closing pointer in Step 4.

What's here

New pageRepeated Runs & Scenario Comparison (content/getting_started/scenarios.md), placed after the Walkthrough:

  • one calculation as one TimexLCASettings, via from_settings().run()
  • re-running with per-call overrides, with a table of what each kind of change reuses vs. rebuilds — including why a changed background is refused, and where to go instead
  • compare() and ComparisonResult.summary, plus keep_objects / on_error
  • where the scenario databases come from — linking to create_missing in the Quick Start rather than restating it

Supporting edits, deliberately small:

  • Step 2 claimed "comparing scenarios is the same script in a loop over filters" — stale now that compare() exists; it points there instead
  • Quick Start gains a six-line "steps 5–7 in one call" snippet beside the procedural example, plus a run()/compare() reference table
  • the API page introduces the two new classes (mkdocstrings already picks them up from the module)

Verification

Every snippet on the new page was executed against a throwaway project before being written down — from_settings/run, the overrides, the refused-background ValueError, and compare()'s summary columns — so the shapes and claims match the code rather than my memory of it. Internal links and cross-page anchors checked programmatically. Full suite across the merged branches: 440 passing.

…reation' into docs/settings-and-scenarios

# Conflicts:
#	CHANGES.md
#	bw_timex/timex_lca.py
Adds one User Guide page rather than a second track through the docs. run()
calls the same four steps the Walkthrough teaches, so presenting them as
parallel tracks would imply a choice that does not exist and would need every
concept documented twice. This follows what scikit-learn does with Pipeline and
GridSearchCV: fit/predict stay the spine, and "run many of them" is its own
topic page that assumes you already know the spine.

The Walkthrough is therefore untouched except for one closing pointer in Step 4.

New page (content/getting_started/scenarios.md):
- one calculation as one TimexLCASettings, via from_settings().run()
- re-running with per-call overrides, and a table of what each kind of change
  reuses or rebuilds - including why a changed background is refused
- compare() and ComparisonResult.summary, with keep_objects / on_error
- where the scenario databases come from, linking to create_missing in the
  Quick Start rather than restating it

Supporting edits:
- Step 2 said "comparing scenarios is the same script in a loop over filters",
  which compare() now replaces; it points there instead
- Quick Start gains a six-line "steps 5-7 in one call" snippet beside the
  procedural example, and a run()/compare() reference table
- the API page introduces the two new classes (mkdocstrings already picks them
  up from the module)

Every snippet on the new page was executed against a throwaway project first -
from_settings/run, the overrides, the refused background change, and compare()'s
summary columns - so the shapes and the claims match the code. Internal links
and cross-page anchors checked programmatically.
@codecov

codecov Bot commented Aug 23, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.15068% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.50%. Comparing base (1bb7fb4) to head (dae42df).
⚠️ Report is 30 commits behind head on main.

Files with missing lines Patch % Lines
bw_timex/timex_lca.py 93.15% 5 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #224      +/-   ##
==========================================
+ Coverage   83.37%   84.50%   +1.13%     
==========================================
  Files          14       15       +1     
  Lines        3013     3428     +415     
==========================================
+ Hits         2512     2897     +385     
- Misses        501      531      +30     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@TimoDiepers
TimoDiepers merged commit 716de15 into main Aug 24, 2026
11 checks passed
@TimoDiepers
TimoDiepers deleted the docs/settings-and-scenarios branch August 24, 2026 13:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant