Improve developer-facing area weights documentation (issue #506)#513
Merged
Improve developer-facing area weights documentation (issue #506)#513
Conversation
… of 2) Restructure tmd/areas/AREA_WEIGHTING_GUIDE.md as a developer-and- analyst guide: add audience preface and table of contents, fix CD commands missing the now-required --congress flag, repair the out-of-date "File Locations" tree (add prepare_shares, batch_weights, sweep_params, make_all, census_population, validate_crosswalk; show cds_118/cds_119 distinction; mark legacy correctly), and replace the duplicate Quality Report section with a pointer up to the user README that PR 1 added. Tweak two passages so the guide describes targets as primarily-SOI plus Census, consistent with PR 1. Update tmd/areas/AREA_WEIGHTING_LESSONS.md inline: rewrite the Congressional Districts section, which described CDs as "not implemented yet," to instead describe how the state-pipeline expectations actually held up in the production CD pipeline. Reconcile tmd/areas/prepare/recipes/README.md with what the CLI actually loads: cd_target_spec.csv and state_target_spec.csv are the production specs; states.json is retained only for the test that exercises the legacy JSON code path; cds.json no longer exists. Document the CSV spec format (columns, count/scope/fstatus codes), the cd_solver_overrides.yaml schema, and why the JSON recipe is still on disk. Add a "Key entry points / used by" section to the tmd/areas/create_area_weights.py module docstring so a developer reading the file knows it is a library called by solve_weights, developer_tools, and make_all. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
donboyd5
added a commit
to donboyd5/tax-microdata-benchmarking
that referenced
this pull request
Apr 26, 2026
…SLmodels#513), branches pruned
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.
Restructure tmd/areas/AREA_WEIGHTING_GUIDE.md as a developer-and- analyst guide: add audience preface and table of contents, fix CD commands missing the now-required --congress flag, repair the out-of-date "File Locations" tree (add prepare_shares, batch_weights, sweep_params, make_all, census_population, validate_crosswalk; show cds_118/cds_119 distinction; mark legacy correctly), and replace the duplicate Quality Report section with a pointer up to the user README that the user documentation PR (PR 1) added. Tweak two passages so the guide describes targets as primarily-SOI plus Census, consistent with PR 1.
Update tmd/areas/AREA_WEIGHTING_LESSONS.md inline: rewrite the Congressional Districts section, which described CDs as "not implemented yet," to instead describe how the state-pipeline expectations actually held up in the production CD pipeline.
Reconcile tmd/areas/prepare/recipes/README.md with what the CLI actually loads: cd_target_spec.csv and state_target_spec.csv are the production specs; states.json is retained only for the test that exercises the legacy JSON code path; cds.json no longer exists. Document the CSV spec format (columns, count/scope/fstatus codes), the cd_solver_overrides.yaml schema, and why the JSON recipe is still on disk.
Add a "Key entry points / used by" section to the
tmd/areas/create_area_weights.py module docstring so a developer reading the file knows it is a library called by solve_weights, developer_tools, and make_all.