Contributing

Adding a dataset

PaMIR ships no data — a dataset is added as a recipe that fetches it from its original source and harmonizes it locally. You never commit a data file.

  1. Check it meets the inclusion criteria: binary default target, publicly downloadable, ≥1,000 rows, ≥3% default rate, and either a flat table or one the recipe can reduce to a flat table (a documented join/aggregation is fine — see bondora).

  2. Add an entry to pamir/data/catalog.json with the metadata (name, rows, defaults, DR, features, geography, product, target_definition, license, source, source_url, and — where the license or academic origin requires it — attribution), plus:

    • download: {kind, locator, file, sep, encoding, …} — where the raw file comes from. kind is one of: kaggle (slug), uci_zip / github_zip (a zip URL; a member is extracted, one level of nesting supported), github_raw (a direct file URL), or hf (a HuggingFace dataset repo). For a headerless raw file add "header": "none" + "columns": [...]; for ARFF add "format": "arff".

    • harmonize: {target, target_rule, day_zero_drop, extra_drop, drop_prefix, shuffle_seed, …}. day_zero_drop is the list of post-outcome columns (the leakage-free semantic cut); extra_drop / drop_prefix remove further leaks or identifiers; shuffle_seed fixes the row order.

  3. If it needs a bespoke read, target rule, or rescale, add the branch in pamir/harmonize.py and reference it via target_rule (see bondora, prosper, south_german).

  4. Run pamir.download("<id>"), confirm it harmonizes cleanly, then freeze the result into pamir/data/expected.json (columns, n_rows, n_defaults, DR) — this is the validation contract every future download is checked against.

  5. Cite the source: put the paper / repository that introduced or used the dataset in the catalog attribution field and in Licenses & attribution.

  6. pamir/data/*.parquet is git-ignored — never commit the dataset itself.

  7. Open a pull request.

Running tests

pip install -e ".[dev,data]"
pytest tests/ -v

Tests that need data skip cleanly when a dataset is not cached (e.g. CI without Kaggle credentials); catalog, recipe and protocol tests always run. The suite checks:

  • Catalog & recipe integrity — 19 datasets, all metadata fields, every dataset has a valid download/harmonize spec, and expected.json agrees with the catalog.

  • Harmonizer/downloader internals — synthetic end-to-end harmonize, expected.json validation, cache location.

  • Leakage-free guards (from the audit) — rows shuffled (|ρ(position, target)| < 0.1), no day_zero_drop column survives, no surrogate-key column, no divisibility leak, no single-column AUC > 0.95.

  • Streaming protocol — no future-label leakage, lag enforced, monotonic train growth, pre-commitment.

  • Data quality — no duplicate rows, no constant features, licenses and attribution present where required.

All tests must pass before a PR is merged.