[solarsys]

Problem

When no cache_dir is given, a dataset writes processed copies of its source data (the event table every patient is read from, and the samples each set_task() produces) to the user cache folder: platformdirs.user_cache_dir("pyhealth"), e.g. ~/Library/Caches/pyhealth or ~/.cache/pyhealth. That was logged only at INFO level.

For identified clinical data this silently copies row-level data outside the project's controlled storage. A downstream EHR project found it only by reading the code.

Changes

• Loud default. Without cache_dir, PyHealth logs a WARNING naming the resolved path and explaining what is written there. It warns once per path, so repeated loads don't spam.
• Opt-in hard stop. With PYHEALTH_REQUIRE_CACHE_DIR=1 (or true/yes), a dataset created without cache_dir raises ValueError before writing anything. An environment variable protects every script and notebook in a project at once, which a per-call argument can't.
• Both entry points. One helper, _default_cache_dir(), is used by BaseDataset and by the FHIR dataset base, which had its own copy of the default. MEDSDataset inherits it.
• Unchanged: behaviour when cache_dir is given, and the default location itself.

Tests, docs, example

• New tests/core/test_default_cache_dir.py:
  • the warning names the path and the env var;
  • it is logged once per path;
  • an explicit cache_dir gives no warning;
  • the env var raises for several spellings and creates nothing;
  • the env var still allows an explicit cache_dir.
• Existing base-dataset, caching and FHIR tests pass.
• docs/api/datasets.rst: the cache_dir bullet names the default location, and there is a new "Working with identified data" section. That section also notes that create_sample_dataset(..., in_memory=False) writes to the system temp folder.
• New examples/require_cache_dir.py on the bundled MIMIC-III demo.
• Full core suite: Ran 1386 tests … OK (skipped=76). tools/check_pr_rules.py passes.

🤖 Generated with Claude Code

[jhnwu3]

lgtm