From 3a5ad857582f730cfdba3be575fb6c3f283c9de8 Mon Sep 17 00:00:00 2001 From: vahid-ahmadi Date: Fri, 18 Sep 2026 14:55:27 +0100 Subject: [PATCH] Refresh the documentation landing page and the roadmap The landing page said function documentation would arrive 'in the future', which #324 has since added, so the first page of the docs told a reader the API reference does not exist. It now describes what the package does, installs it, and links to both pages. examples.md opened with 'See these rendered Jupyter notebooks' followed by no links. It now links the one notebook there is. The roadmap claimed graphs and Tax-Calculator helpers, neither of which is in the package - grep finds no taxcalc reference and no plotting code - and listed replicate-weight standard errors as future work, which shipped in #320 and is the paper's headline feature. Replaced with what the package does and three things it does not do yet. --- ROADMAP.md | 21 +++++++++++++++------ changelog.d/docs-landing.changed.md | 1 + docs/examples.md | 2 +- docs/home.md | 20 +++++++++++++++++++- 4 files changed, 36 insertions(+), 8 deletions(-) create mode 100644 changelog.d/docs-landing.changed.md diff --git a/ROADMAP.md b/ROADMAP.md index 36fc95a6..9d6649a7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,9 +1,18 @@ # `microdf` roadmap -`microdf` currently provides capabilities for analyzing weighted microdata, including statistics, distributional tables, graphs, and special functions for working with PSL Tax-Calculator. In the future, it will provide more functionality, including: -* Charts showing distributional changes between a baseline and reform policy -* Extending these charts to more than one reform -* Presets for working with common datasets, e.g. suggesting the appropriate weight for SCF and CPS -* Standard error calculations for surveys with replicate weight files +`microdf` provides weighted data structures for survey microdata: weighted +quantiles and moments, inequality measures including the Gini coefficient and +top and bottom shares, Foster-Greer-Thorbecke poverty measures, and variance +estimation from replicate weights. -See the [issues page](https://github.com/PolicyEngine/microdf/issues) to view and suggest other items. +Planned work: + +* Variance from stratum and cluster identifiers, for designs where replicate + weights are not published +* Presets for common datasets, such as suggesting the appropriate weight + variable for the SCF and the CPS +* Wider coverage of pandas methods that change shape, so fewer operations need + an explicit override + +See the [issues page](https://github.com/PolicyEngine/microdf/issues) to view +and suggest other items. diff --git a/changelog.d/docs-landing.changed.md b/changelog.d/docs-landing.changed.md new file mode 100644 index 00000000..f567f448 --- /dev/null +++ b/changelog.d/docs-landing.changed.md @@ -0,0 +1 @@ +Adds an installation snippet and links to the API reference from the documentation landing page, and updates the roadmap. diff --git a/docs/examples.md b/docs/examples.md index a56e222d..a5ee4d66 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,7 +1,7 @@ Examples ======== -See these rendered Jupyter notebooks for examples of `microdf` usage. +Worked examples of `microdf` usage. The [Gini coefficient notebook](gini.ipynb) shows the estimator against a known distribution. ## Keeping weights through pandas operations `MicroSeries` and `MicroDataFrame` retain independent copies of their row diff --git a/docs/home.md b/docs/home.md index 2b432f06..0f2b8652 100644 --- a/docs/home.md +++ b/docs/home.md @@ -1,4 +1,22 @@ `microdf` documentation ======================= -This includes example notebooks, and in the future will also include function documentation. \ No newline at end of file +`microdf` provides weighted data structures for survey microdata analysis in +Python. `MicroSeries` and `MicroDataFrame` carry sampling weights inside the +object, so the weights stay aligned with their rows through merges, filters, +grouping and reindexing, and the weighted estimators — quantiles, variance, +Gini, top shares, poverty rates — use documented conventions rather than ad hoc +ones. + +```python +import microdf as mdf + +df = mdf.MicroDataFrame({"income": [10_000, 30_000, 120_000]}, weights=[800, 1_200, 50]) +df.income.median() # 30000, weighted +df.income.gini() +``` + +Install with `pip install microdf-python`. + +- [Examples](examples.md) — worked analyses, and how weights survive a pipeline +- [API reference](api.md) — every weighted estimator and weight-handling method