[Aprameyaraya]

Closes #913

Problem

Datasets with pre-defined splits (e.g. TUEV/TUAB) each needed their own
function in splitter.py. The four *_tuh functions repeat the same logic,
and every new dataset would add more copies.

Changes

• pyhealth/datasets/splitter.py
  • Add split_by_predefined, a generic splitter for datasets whose samples
    carry an official partition label (split_key, default "split").
    Samples with train_value form the pool that is cut by ratios (2 values
    for train/val, 3 for train/val/cal). All other samples are the test set.
  • by_patient=True keeps each patient's samples in one split. Patient IDs
    are sorted before shuffling, so the result does not depend on sample order.
  • Reduce split_by_patient_tuh, split_by_sample_tuh,
    split_by_patient_conformal_tuh and split_by_sample_conformal_tuh to
    thin wrappers. Names, signatures and docstrings are unchanged.
  • The sample-level versions now read each sample once instead of two or
    three times.
• pyhealth/datasets/__init__.py: export split_by_predefined.
• CONTRIBUTING.md: add "Porting a Dataset's Official Splits", the standard
  asked for in Create file structure standard/documentation for how people should port over their task data splits. #913: tag samples with "split" in the task, call
  split_by_predefined instead of adding a splitter, and put any
  fixed-argument wrapper next to the dataset module.
• <docs file(s) updated>
• <example file(s) updated>

Backward compatibility

The *_tuh functions keep their public API. For the same seed they should
return the same indices as before. <Say here how you checked, e.g. compared
old vs new get_index=True output on a fake dataset.>

Testing

• <command you ran, e.g. pytest tests/core/test_splitter_predefined.py>
• python tools/check_pr_rules.py --base <base_sha> --head HEAD

Notes

These functions split an already-processed SampleDataset, so its processors
were fitted on all samples. This PR does not change that. For preprocessing fitted
on the training part only, use set_task(..., split=PatientSplit(...)).

[jhnwu3]

/review

[github-actions]

Test Coverage

Total: 71.65% (18836 / 26289 lines)

Modified file	Coverage	Lines
pyhealth/calib/predictionset/__init__.py	100.00%	8 / 8
pyhealth/calib/predictionset/base_conformal/__init__.py	62.89%	61 / 97
pyhealth/calib/predictionset/label_shift/__init__.py	100.00%	4 / 4
pyhealth/calib/predictionset/label_shift/black_box_shift.py	87.69%	57 / 65
pyhealth/calib/predictionset/label_shift/label_shift.py	96.39%	80 / 83
pyhealth/calib/predictionset/label_shift/mlls.py	95.12%	78 / 82
pyhealth/datasets/__init__.py	83.33%	40 / 48
pyhealth/datasets/ptbxl.py	83.51%	157 / 188
pyhealth/datasets/splitter.py	96.08%	294 / 306
pyhealth/models/transformers_model.py	90.00%	81 / 90
pyhealth/tasks/__init__.py	89.19%	33 / 37
pyhealth/tasks/ptbxl.py	93.42%	71 / 76
pyhealth/tasks/sleep_staging.py	93.33%	84 / 90
pyhealth/tasks/temple_university_EEG_tasks.py	83.97%	131 / 156

Workflow run · 71dc1f1

[Logiquo]

/review