Conversation
Replaces the legacy multi-concept pages (core-concepts, economic-impact-analysis, country-models-us/uk, regions-and-scoping, advanced-outputs) with task-shaped pages: getting-started, households, reforms, microsim, outputs, impact-analysis, regions, countries.
Rewrites fix real v4 API usage:
- Outputs use ``simulation=``/``baseline_simulation=``/``reform_simulation=`` kwargs plus ``.run()`` + result fields (no ``.compute(baseline)``).
- ``AggregateType``/``ChangeAggregateType`` list only ``SUM``/``MEAN``/``COUNT``.
- Filters use ``filter_variable``/``filter_variable_eq/leq/geq`` and quantile kwargs, not pandas-style strings.
- Parametric reforms use ``reform=`` on ``calculate_household`` and ``policy=`` on ``Simulation`` with flat ``{"param.path": value}`` dicts and ``base[0].amount`` bracket indexing.
- Regional analysis uses ``RowFilterStrategy``/``WeightReplacementStrategy`` and ``region_registry.get_by_type(...)``.
Also updates ``dev.md`` to reflect the Quarto toolchain (not MyST) and the ``.added.md``/``.changed.md`` changelog-fragment format, and refreshes the source-tree diagram.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reviewer flagged four factual errors against the real v4 API: - calculate_us_poverty_rates and calculate_us_inequality take a single ``simulation=`` and return a single-simulation output (OutputCollection or Inequality). The docs had them returning a baseline+reform pair. Fix outputs.md and impact-analysis.md to call them once per simulation. - region.scoping_strategy is only populated for regions that filter (US places, UK countries); US states use dataset_path instead. regions.md now documents that distinction and swaps the state/ca example for a place/* region. - UK dataset label updated to "Enhanced FRS 2023/24" to match the filename. - Drop "plus official thresholds" — the model only tracks SPM and deep SPM in US_POVERTY_VARIABLES.
MaxGhenis
force-pushed
the
docs-content-rewrite
branch
from
4272e8c to
11a2e08
Compare
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
1 participant
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.
Summary
Replaces the legacy multi-concept docs with task-shaped pages aligned to the v4 API. Stacked on top of PR #304 (Quarto toolchain swap); should be rebased onto
mainonce #304 merges.Structure
Added
getting-started.md— install, first household, first reform, first microsimhouseholds.md—pe.us.calculate_household/pe.uk.calculate_householdreferencereforms.md— parametric-reform dict shape (reform=on household,policy=onSimulation), time-varying, scale bracket indexing, structural fallback via the country packagemicrosim.md—Simulation+ensure()lifecycle,ensure_datasets,managed_microsimulationoutputs.md— full catalog ofAggregate/ChangeAggregate/DecileImpact/Poverty/Inequality/ProgramStatistics/ geographic impactsimpact-analysis.md—economic_impact_analysis(baseline, reform)and itsPolicyReformAnalysisreturn typeregions.md— state filtering, congressional districts, constituencies, local authorities,RowFilterStrategycountries.md— US vs UK entity mapping, default dataset, default income variable, parameter treesRemoved (content folded into the new pages)
core-concepts.mdeconomic-impact-analysis.mdcountry-models-us.md,country-models-uk.mdregions-and-scoping.mdadvanced-outputs.mdUpdated
index.md— one-pager with a "where to go next" matrix_quarto.yml— sidebar split into Get started / Calculate / Analyse / Referencedev.md— references Quarto (not MyST) and thebranch.type.mdtowncrier format; source-tree diagram reflectscli.py,results/,data/Correctness fixes
The rewrite corrects errors in the prior documentation against the actual v4 API:
simulation=/baseline_simulation=/reform_simulation=kwargs and the.run()→ result-fields pattern (notAggregate(...).compute(baseline))AggregateType/ChangeAggregateTypelist onlySUM/MEAN/COUNTfilter_variable=/filter_variable_eq/leq/geq/quantile=(not pandas-stylefilter="state_code == 'CA'"strings)[0].amountbracket indexing for scale parametersRowFilterStrategy/WeightReplacementStrategy; region registry isget_by_type(...)/get(code)Test plan
quarto render docsbuilds cleanly (13 pages, no broken-link warnings).mdlinks resolve to generated.html(grep -o 'href=' docs/_site/index.htmlshows expected targets)mainpost-Swap docs toolchain from MyST to Quarto #304🤖 Generated with Claude Code