docs: add four fairness explainers (Simpson's paradox, conditional DP, subgroup fairness, differential privacy) - #541
Merged
yakew7 merged 1 commit intoSep 9, 2026
Conversation
…, subgroup fairness, differential privacy) New explainers (explainers/*.md + generated pages, data.js, sitemap, llms-full.txt, package mirror, OG images, explainer-count bumps): - simpsons-paradox: an aggregate fairness metric is a weighted average of within-stratum rates, so pooling can manufacture or reverse a gap. Real example: Benefits Denial (Adult Census) sex income gap +19.6 pp aggregate, ~+3 pp within marital-status strata, -0.9 pp inside the largest one. - conditional-demographic-parity: parity checked within strata of a chosen legitimate factor, and how that choice decides the answer. Same audit: conditioning on education leaves the gap at +18.4 pp, conditioning on marital status removes ~84% of it. - subgroup-fairness: passing a check on each attribute is not passing it on every combination (fairness gerrymandering). Real example: Healthcare Readmission gender gap 0.19 pp overall, -5.15 pp inside the Asian subgroup. Contrasts a brute-force subgroup scan with the fixed-pair --cross. - differential-privacy: DP-SGD's clipping and noise degrade minority accuracy hardest. Illustrative numbers from Bagdasaryan, Poursaeed, Shmatikov (NeurIPS 2019) - this repo trains no DP model - plus a runnable DP-SGD noise toy. Also folds in the explainers/unsupervised-learning.html regeneration that was already stale on main (the "Audit 04" -> "Audit 05" heading from an earlier commit); if that lands separately first this rebases to nothing. Closes yakew7#483, yakew7#484, yakew7#485, yakew7#486
propcgamer20-png
requested review from
Shreyash0712 and
yakew7
as code owners
September 9, 2026 16:11
Contributor
|
@propcgamer20-png is attempting to deploy a commit to the yashkewlani2020-gmailcom's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
@yakew7 @Shreyash0712 - new PR touching a path you own, please review. |
yakew7
added a commit
that referenced
this pull request
Sep 9, 2026
…irness content fixes make build-explainers after the 3 preceding content-fix commits. Also picks up first-commit datePublished/dateModified for all 4 explainers added in #541 (git-log-derived; couldn't resolve until those files had a real commit history, the same one-time chicken-and-egg noted in check_generated_files_current.py's own docstring).
yakew7
added a commit
that referenced
this pull request
Sep 9, 2026
Backfills entries under the existing [2.2.0] section (same version): 15 Fixed entries for #526-540 (14 by @propcgamer20-png, 2 by new contributor @Aaqibhafeezkhan), and 1 Added entry for #541 (4 new explainers by @propcgamer20-png, plus the errors found and fixed in this session's review of that PR). Verified each of the 16 fixes directly (re-ran every repro, cross-checked engine parity where applicable, ran the full test suite) before writing these up.
yakew7
added a commit
that referenced
this pull request
Sep 9, 2026
@propcgamer20-png bumped to 33 merged PRs / 50 commits (was 19/36), added the 14-PR batch (#528-541) to their bio, and added to 3 "Contributions by area" rows their recent work now touches (Profiler - web, Benchmark harness, Website & explainer build). New contributor @Aaqibhafeezkhan (2 merged PRs, first merged 2026-09-09): two one-line doc fixes (#526, #527). Added to the Explainers and Website & explainer build area rows. Refreshed the file's own snapshot line (was "through PR #510"; now "through PR #541").
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
2 participants
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.
Adds the four explainers requested in #483, #484, #485, #486. Each is
explainers/<slug>.mdplus its generated page, anassets/explainers-data.jsonentry, OG images (dark + light), and theexplainers-data.js/sitemap.xml/llms-full.txt/ package-mirror / explainer-count regeneration.The four
simpsons-paradox(#483)sexincome gap +19.6 pp, ~+3 pp withinmarital.statusstrata, -0.9 pp (reversed) insideMarried-civ-spouse(46% of rows)Benefits Denial/adult.csvconditional-demographic-parity(#486)education.numleaves +18.4 pp; conditioning onmarital.statusremoves ~84% of itsubgroup-fairness(#485)genderreadmission gap 0.19 pp overall (ratio 0.984, passes) but -5.15 pp inside theAsiansubgroup (n=641)Healthcare Readmission/diabetic_data.csv; contrasts a brute-force subgroup scan with this repo's fixed-pair--crossdifferential-privacy(#484)Every explainer follows the existing template (one-sentence definition -> why it matters -> how it works -> concrete example -> detection code -> limitations -> related concepts / projects / further reading) and the em-dash-free house style. All citations were fetched and confirmed (venue, year, author list, finding).
Checks
scripts/check_em_dash.py- cleanscripts/check_broken_links.py- clean (1467 links, 82 files)scripts/check_explainer_count.py- all 6 mentions match, 60 filesscripts/check_generated_files_current.py- up to datepytest tests/test_build_explainers.py- passesAlso folds in the
explainers/unsupervised-learning.htmlregeneration that is already stale onmain(the "Audit 04" -> "Audit 05" heading fromc898369); if #540 lands that separately first, this rebases cleanly to nothing for that file.Closes #483
Closes #484
Closes #485
Closes #486