Document settings, repeated runs and scenario comparison - #224
Merged
Conversation
…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 Report❌ Patch coverage is
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. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 inspecttlca.timelinebetween steps, re-run one step with different arguments).So this follows the shape scikit-learn uses for
Pipeline/GridSearchCV:fit/predictstay the spine, and "run many of them" is its own topic page that assumes you already know the spine. Same pattern asrequests(Quickstart vs.Sessionin Advanced) andpytest(plain asserts, then fixtures).The Walkthrough is untouched, except one closing pointer in Step 4.
What's here
New page — Repeated Runs & Scenario Comparison (
content/getting_started/scenarios.md), placed after the Walkthrough:TimexLCASettings, viafrom_settings().run()compare()andComparisonResult.summary, pluskeep_objects/on_errorcreate_missingin the Quick Start rather than restating itSupporting edits, deliberately small:
compare()exists; it points there insteadrun()/compare()reference tableVerification
Every snippet on the new page was executed against a throwaway project before being written down —
from_settings/run, the overrides, the refused-backgroundValueError, andcompare()'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.