bpskit 0.2.0__tar.gz

bpskit-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+/.[!.]*/
+!/.github/
+__pycache__/
+*.py[cod]
+/dist/
+/build/
+*.egg-info/

bpskit-0.2.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to bpskit. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the versions
+[Semantic Versioning](https://semver.org/): until 1.0, a minor release may
+change the public API (the names in each module's `__all__`).
+
+## [0.2.0]
+
+### Added
+- `bpskit.synthetic`: a synthetic BPS delivery with planted structure
+  (`make_delivery`, `config`, `FILES`), and `bpskit synthetic` on the command line.
+- `examples/quickstart.py`, a worked example run in CI.
+- A declared public API (`__all__` in every module), type hints and `py.typed`.
+- Packaging metadata, a release workflow publishing to PyPI by trusted
+  publishing, `CITATION.cff`.
+
+### Changed
+- The version is read from `bpskit/__init__.py` (one place to bump).
+
+## [0.1.0]
+
+### Added
+- `delivery`, `icd`, `persontime`, `stats` and `transfer`, extracted from the
+  BPS sex-differences workflow, and the `bpskit pullable` / `bpskit check-logs`
+  command line.
+
+[0.2.0]: https://github.com/loucerac/bpskit/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/loucerac/bpskit/releases/tag/v0.1.0

bpskit-0.2.0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "If you use bpskit, please cite it as below."
+title: "bpskit: tools for studies on a BPS health-records delivery"
+type: software
+authors:
+  - family-names: Loucera
+    given-names: Carlos
+    email: clou@us.es
+license: MIT
+repository-code: "https://github.com/loucerac/bpskit"
+version: 0.2.0
+keywords:
+  - epidemiology
+  - electronic health records
+  - ICD-10
+  - disclosure control

bpskit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Loucera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bpskit-0.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: bpskit
+Version: 0.2.0
+Summary: Tools for studies on a BPS (Base Poblacional de Salud) health-records delivery, including an identifier check for outputs leaving a secure data environment
+Project-URL: Homepage, https://github.com/loucerac/bpskit
+Project-URL: Changelog, https://github.com/loucerac/bpskit/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/loucerac/bpskit/issues
+Author-email: Carlos Loucera <clou@us.es>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ICD-10,ICD-9,disclosure control,electronic health records,epidemiology,person-time,snakemake,trusted research environment
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: icd-mappings<0.7,>=0.6.2
+Requires-Dist: numpy>=2
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=15
+Requires-Dist: pyyaml>=6
+Requires-Dist: scipy>=1.11
+Description-Content-Type: text/markdown
+
+# bpskit
+
+Tools for studies on a BPS (Base Poblacional de Salud, Servicio Andaluz de
+Salud) health-records delivery, and for working with pseudonymised
+health-record extracts in a secure data environment generally.
+
+- **Read the delivery.** Pipe-delimited files read as text, sentinel codes for
+  "unknown", month- and day-precision dates, streaming in fixed-size blocks so a
+  400-million-row file never sits in memory.
+- **ICD codes.** Code specifications like `A15-A19, H35.3`, ICD-10 chapters,
+  and ICD-9 → ICD-10 mapping with the CMS GEM. That includes the V/E
+  supplementary codes, which are also valid ICD-10 and can only be placed by
+  the record's date relative to a changeover.
+- **Person-time.** Dates as days since 1970, age bands, Lexis splitting,
+  person-sorted streaming.
+- **Exact tests.** Poisson rate ratios (Garwood intervals), binomial tests,
+  BH and Bonferroni.
+- **An output check for leaving the secure environment.** `bpskit.transfer`
+  refuses any file that contains an identifier the workflow read, or a
+  per-person column, and fails closed when it cannot read something.
+- **A synthetic delivery** with BPS column names and planted structure, for
+  tests and examples.
+
+## Installing
+
+```bash
+pip install "bpskit @ git+https://github.com/loucerac/bpskit.git@v0.2.0"
+```
+
+In a pixi project (`pixi.toml`):
+
+```toml
+[pypi-dependencies]
+bpskit = { git = "https://github.com/loucerac/bpskit.git", tag = "v0.2.0" }
+```
+
+In a Snakemake rule environment (`workflow/envs/*.yaml`):
+
+```yaml
+dependencies:
+  - pip
+  - pip:
+      - git+https://github.com/loucerac/bpskit.git@v0.2.0
+```
+
+Pin a release. Bumping the tag changes the environment file, and Snakemake's
+`software-env` rerun trigger reruns the rules that use it. A module imported
+from a sibling folder gets no such tracking.
+
+## A worked example
+
+[`examples/quickstart.py`](examples/quickstart.py) runs in a few seconds with no
+real data:
+
+1. it writes a 5,000-person synthetic delivery;
+2. it measures the incidence of type 2 diabetes (E11) in primary care in
+   2018-2025;
+3. it compares women with the whole population;
+4. it runs the transfer check on the result.
+
+The core of it:
+
+```python
+from bpskit import transfer
+from bpskit.delivery import normalise_code, parse_date, read_delivery, stream_csv
+from bpskit.icd import expand_spec, prefix_mask
+from bpskit.persontime import day_of, follow_up, to_days
+from bpskit.stats import poisson_rr
+from bpskit.synthetic import make_delivery
+
+cfg = make_delivery("work/delivery", n_persons=5_000)  # files + how to read them
+
+# people: birth and death as days since 1970 (NaN = alive)
+u = cfg["universe"]
+people = read_delivery(f"work/delivery/{u['file']}", [u["id"], u["sex"], u["birth"], u["death"]])
+birth = to_days(parse_date(people[u["birth"]], u["date_format"], ["", "-1"], mid_month_day=15))
+
+# first E11 record per person, streamed block by block
+ap = cfg["sources"]["ap"]
+for block in stream_csv(
+    f"work/delivery/{ap['file']}", [ap["id"], ap["date"], ap["code"]], 16, "utf-8"
+):
+    hits = block[prefix_mask(normalise_code(block[ap["code"]]), expand_spec("E11"))]
+    ...
+
+# follow-up, then observed vs expected with an exact interval
+entry, exit_, in_period = follow_up(birth, death, day_of("2018-01-01"), day_of("2025-12-31"))
+ratio, lo, hi, p = poisson_rr(observed, expected, alpha=0.05)
+
+# nothing leaves the machine that names a patient
+n, problems = transfer.check(
+    ["work/results/out"],
+    ids=set(people[u["id"]]),
+    strict=True,
+    forbidden=transfer.forbidden_columns(cfg),
+)
+```
+
+```
+E11 incidence 1,258 per 100,000 person-years; women vs all: 1.12 (0.98-1.27)
+aggregate table: 1 file checked, 0 problem(s)
+with a leaked file:
+  .../first_cases.csv: contains 3 patient identifier(s)
+  .../first_cases.csv: per-person or identifier column(s) ['patient']
+```
+
+## The transfer check
+
+The rule it enforces: no row carrying a patient identifier leaves the machine
+that holds the delivery. It checks the bytes of every file against the
+identifiers the workflow actually read, not against a guessed id format. A
+workflow writes those identifiers with `transfer.write_ids`:
+
+- `results/work/ids/universe.parquet`: every id in the people file, written
+  before anyone is dropped;
+- `results/work/ids/<source>.parquet`: ids in a diagnosis file but not in the
+  people file.
+
+Where an id file is missing (a run that died early), the check reads the
+delivery file instead. An unreadable file, an unknown suffix or an empty id set
+all refuse. With `strict=True` (for a results folder copied off wholesale),
+only csv/txt/png pass. CSVs whose header holds a per-person key, one of the
+delivery's id or date columns, or an identifier-like name are refused too.
+
+From a workflow directory on the data machine:
+
+```bash
+bpskit pullable --strict results/out   # exit 0 only if results/out/ may leave
+bpskit check-logs .                    # list the logs that may leave
+bpskit synthetic data/synthetic --persons 2000
+```
+
+`pullable` and `check-logs` read the workflow's `config/config.yaml`
+(`--config` to change it). Its `universe` and `sources` sections, in the shape
+`bpskit.synthetic.config()` returns, name the id columns.
+
+## Developing
+
+```bash
+pixi run test       # pytest
+pixi run lint       # ruff check + format check
+pixi run example    # the worked example
+pixi run build      # sdist + wheel, twine check
+```
+
+Releasing: bump `__version__` in `src/bpskit/__init__.py`, add the release to
+`CHANGELOG.md`, commit, then tag `vX.Y.Z` and push the tag.
+`.github/workflows/release.yml` checks that the tag matches the version,
+builds, and publishes to PyPI by trusted publishing.
+
+## Citing
+
+See [`CITATION.cff`](CITATION.cff). MIT licensed.

bpskit-0.2.0/README.md

@@ -0,0 +1,153 @@
+# bpskit
+
+Tools for studies on a BPS (Base Poblacional de Salud, Servicio Andaluz de
+Salud) health-records delivery, and for working with pseudonymised
+health-record extracts in a secure data environment generally.
+
+- **Read the delivery.** Pipe-delimited files read as text, sentinel codes for
+  "unknown", month- and day-precision dates, streaming in fixed-size blocks so a
+  400-million-row file never sits in memory.
+- **ICD codes.** Code specifications like `A15-A19, H35.3`, ICD-10 chapters,
+  and ICD-9 → ICD-10 mapping with the CMS GEM. That includes the V/E
+  supplementary codes, which are also valid ICD-10 and can only be placed by
+  the record's date relative to a changeover.
+- **Person-time.** Dates as days since 1970, age bands, Lexis splitting,
+  person-sorted streaming.
+- **Exact tests.** Poisson rate ratios (Garwood intervals), binomial tests,
+  BH and Bonferroni.
+- **An output check for leaving the secure environment.** `bpskit.transfer`
+  refuses any file that contains an identifier the workflow read, or a
+  per-person column, and fails closed when it cannot read something.
+- **A synthetic delivery** with BPS column names and planted structure, for
+  tests and examples.
+
+## Installing
+
+```bash
+pip install "bpskit @ git+https://github.com/loucerac/bpskit.git@v0.2.0"
+```
+
+In a pixi project (`pixi.toml`):
+
+```toml
+[pypi-dependencies]
+bpskit = { git = "https://github.com/loucerac/bpskit.git", tag = "v0.2.0" }
+```
+
+In a Snakemake rule environment (`workflow/envs/*.yaml`):
+
+```yaml
+dependencies:
+  - pip
+  - pip:
+      - git+https://github.com/loucerac/bpskit.git@v0.2.0
+```
+
+Pin a release. Bumping the tag changes the environment file, and Snakemake's
+`software-env` rerun trigger reruns the rules that use it. A module imported
+from a sibling folder gets no such tracking.
+
+## A worked example
+
+[`examples/quickstart.py`](examples/quickstart.py) runs in a few seconds with no
+real data:
+
+1. it writes a 5,000-person synthetic delivery;
+2. it measures the incidence of type 2 diabetes (E11) in primary care in
+   2018-2025;
+3. it compares women with the whole population;
+4. it runs the transfer check on the result.
+
+The core of it:
+
+```python
+from bpskit import transfer
+from bpskit.delivery import normalise_code, parse_date, read_delivery, stream_csv
+from bpskit.icd import expand_spec, prefix_mask
+from bpskit.persontime import day_of, follow_up, to_days
+from bpskit.stats import poisson_rr
+from bpskit.synthetic import make_delivery
+
+cfg = make_delivery("work/delivery", n_persons=5_000)  # files + how to read them
+
+# people: birth and death as days since 1970 (NaN = alive)
+u = cfg["universe"]
+people = read_delivery(f"work/delivery/{u['file']}", [u["id"], u["sex"], u["birth"], u["death"]])
+birth = to_days(parse_date(people[u["birth"]], u["date_format"], ["", "-1"], mid_month_day=15))
+
+# first E11 record per person, streamed block by block
+ap = cfg["sources"]["ap"]
+for block in stream_csv(
+    f"work/delivery/{ap['file']}", [ap["id"], ap["date"], ap["code"]], 16, "utf-8"
+):
+    hits = block[prefix_mask(normalise_code(block[ap["code"]]), expand_spec("E11"))]
+    ...
+
+# follow-up, then observed vs expected with an exact interval
+entry, exit_, in_period = follow_up(birth, death, day_of("2018-01-01"), day_of("2025-12-31"))
+ratio, lo, hi, p = poisson_rr(observed, expected, alpha=0.05)
+
+# nothing leaves the machine that names a patient
+n, problems = transfer.check(
+    ["work/results/out"],
+    ids=set(people[u["id"]]),
+    strict=True,
+    forbidden=transfer.forbidden_columns(cfg),
+)
+```
+
+```
+E11 incidence 1,258 per 100,000 person-years; women vs all: 1.12 (0.98-1.27)
+aggregate table: 1 file checked, 0 problem(s)
+with a leaked file:
+  .../first_cases.csv: contains 3 patient identifier(s)
+  .../first_cases.csv: per-person or identifier column(s) ['patient']
+```
+
+## The transfer check
+
+The rule it enforces: no row carrying a patient identifier leaves the machine
+that holds the delivery. It checks the bytes of every file against the
+identifiers the workflow actually read, not against a guessed id format. A
+workflow writes those identifiers with `transfer.write_ids`:
+
+- `results/work/ids/universe.parquet`: every id in the people file, written
+  before anyone is dropped;
+- `results/work/ids/<source>.parquet`: ids in a diagnosis file but not in the
+  people file.
+
+Where an id file is missing (a run that died early), the check reads the
+delivery file instead. An unreadable file, an unknown suffix or an empty id set
+all refuse. With `strict=True` (for a results folder copied off wholesale),
+only csv/txt/png pass. CSVs whose header holds a per-person key, one of the
+delivery's id or date columns, or an identifier-like name are refused too.
+
+From a workflow directory on the data machine:
+
+```bash
+bpskit pullable --strict results/out   # exit 0 only if results/out/ may leave
+bpskit check-logs .                    # list the logs that may leave
+bpskit synthetic data/synthetic --persons 2000
+```
+
+`pullable` and `check-logs` read the workflow's `config/config.yaml`
+(`--config` to change it). Its `universe` and `sources` sections, in the shape
+`bpskit.synthetic.config()` returns, name the id columns.
+
+## Developing
+
+```bash
+pixi run test       # pytest
+pixi run lint       # ruff check + format check
+pixi run example    # the worked example
+pixi run build      # sdist + wheel, twine check
+```
+
+Releasing: bump `__version__` in `src/bpskit/__init__.py`, add the release to
+`CHANGELOG.md`, commit, then tag `vX.Y.Z` and push the tag.
+`.github/workflows/release.yml` checks that the tag matches the version,
+builds, and publishes to PyPI by trusted publishing.
+
+## Citing
+
+See [`CITATION.cff`](CITATION.cff). MIT licensed.

bpskit-0.2.0/examples/quickstart.py

@@ -0,0 +1,91 @@
+"""bpskit end to end on a synthetic delivery, in a few seconds.
+
+Writes a 5,000-person synthetic BPS delivery, measures the incidence of type 2
+diabetes (ICD-10 E11) in primary care in 2018-2025, compares women with the
+whole population, and runs the transfer check on the result table: once on the
+aggregate table (it passes), once on a file that names a patient (it is refused).
+
+    python examples/quickstart.py [work_dir]
+"""
+
+import sys
+import tempfile
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from bpskit import transfer
+from bpskit.delivery import normalise_code, parse_date, read_delivery, stream_csv
+from bpskit.icd import expand_spec, prefix_mask
+from bpskit.persontime import DAYS_PER_YEAR, day_of, follow_up, to_days
+from bpskit.stats import poisson_rr
+from bpskit.synthetic import make_delivery
+
+work = Path(sys.argv[1] if len(sys.argv) > 1 else tempfile.mkdtemp())
+cfg = make_delivery(work / "delivery", n_persons=5_000)
+root = Path(cfg["delivery_root"])
+sentinels = ["", "-1", "-2", "-9"]
+
+# 1. People: sex, and birth and death as days since 1970 (NaN = alive).
+u = cfg["universe"]
+people = read_delivery(root / u["file"], [u["id"], u["sex"], u["birth"], u["death"]])
+is_f = people[u["sex"]].map(u["sex_values"]).eq("F").to_numpy()
+birth = to_days(parse_date(people[u["birth"]], u["date_format"], sentinels, 15))
+death = to_days(parse_date(people[u["death"]], u["date_format"], sentinels, 15))
+
+# 2. Each person's first primary-care record of E11, streamed block by block.
+ap = cfg["sources"]["ap"]
+prefixes = expand_spec("E11")
+first: dict[str, float] = {}
+for block in stream_csv(root / ap["file"], [ap["id"], ap["date"], ap["code"]], 16, "utf-8"):
+    hit = block[prefix_mask(normalise_code(block[ap["code"]]), prefixes)]
+    days = to_days(parse_date(hit[ap["date"]], ap["date_format"], sentinels, 15))
+    for pid, d in zip(hit[ap["id"]], days):
+        first[pid] = min(d, first.get(pid, np.inf))
+event = people[u["id"]].map(first).to_numpy(float)
+
+# 3. Follow-up 2018-2025. A record before the start makes a person prevalent and
+#    removes them from the risk set; an incident record ends their follow-up.
+entry, exit_, in_period = follow_up(birth, death, day_of("2018-01-01"), day_of("2025-12-31"))
+at_risk = in_period & ~(event < entry)
+incident = at_risk & (event <= exit_)
+exit_ = np.where(incident, event, exit_)
+years = np.where(at_risk, (exit_ - entry) / DAYS_PER_YEAR, 0.0)
+
+# 4. Women against the whole population: observed cases over those expected at
+#    the overall rate, with an exact Poisson interval.
+rate = incident.sum() / years.sum()
+obs, exp = incident[is_f].sum(), years[is_f].sum() * rate
+ratio, lo, hi, p = poisson_rr(obs, exp, alpha=0.05)
+table = pd.DataFrame(
+    {
+        "group": ["women"],
+        "cases": [obs],
+        "expected": [exp],
+        "ratio": [ratio],
+        "ratio_lo": [lo],
+        "ratio_hi": [hi],
+        "p": [p],
+    }
+)
+print(
+    f"E11 incidence {rate * 1e5:,.0f} per 100,000 person-years; women vs all: "
+    f"{float(ratio):.2f} ({float(lo):.2f}-{float(hi):.2f})"
+)
+
+# 5. The transfer check: no file leaving the machine may name a patient.
+out = work / "results/out"
+out.mkdir(parents=True, exist_ok=True)
+table.to_csv(out / "e11_incidence.csv", index=False)
+ids = set(people[u["id"]])
+forbidden = transfer.forbidden_columns(cfg)
+n, problems = transfer.check([out], ids, strict=True, forbidden=forbidden)
+print(f"aggregate table: {n} file checked, {len(problems)} problem(s)")
+assert not problems
+
+leak = out / "first_cases.csv"
+pd.DataFrame({"patient": list(first)[:3]}).to_csv(leak, index=False)
+n, problems = transfer.check([out], ids, strict=True, forbidden=forbidden)
+print("with a leaked file:", *problems, sep="\n  ")
+assert problems and all(str(leak) in p for p in problems)

bpskit-0.2.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "bpskit"
+dynamic = ["version"]
+description = "Tools for studies on a BPS (Base Poblacional de Salud) health-records delivery, including an identifier check for outputs leaving a secure data environment"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Carlos Loucera", email = "clou@us.es" }]
+requires-python = ">=3.11"
+keywords = ["epidemiology", "electronic health records", "ICD-10", "ICD-9", "person-time",
+            "trusted research environment", "disclosure control", "snakemake"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Typing :: Typed",
+]
+dependencies = [
+    "numpy>=2",
+    "pandas>=2.2",
+    "scipy>=1.11",
+    "pyarrow>=15",
+    "pyyaml>=6",
+    "icd-mappings>=0.6.2,<0.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/loucerac/bpskit"
+Changelog = "https://github.com/loucerac/bpskit/blob/main/CHANGELOG.md"
+Issues = "https://github.com/loucerac/bpskit/issues"
+
+[project.scripts]
+bpskit = "bpskit.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/bpskit/__init__.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E9", "E501", "F", "I"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "CHANGELOG.md", "CITATION.cff", "LICENSE"]

bpskit-0.2.0/src/bpskit/__init__.py

@@ -0,0 +1,14 @@
+"""Shared tools for studies on a BPS (Base Poblacional de Salud, SAS) delivery.
+
+    bpskit.delivery    read the pipe-delimited delivery: sentinels, dates, streaming
+    bpskit.icd         ICD-10 code specs and chapters, ICD-9 -> ICD-10 mapping (CMS GEM)
+    bpskit.persontime  dates as numbers, age bands, Lexis splitting, person streaming
+    bpskit.stats       exact Poisson and binomial tests, BH / Bonferroni
+    bpskit.transfer    the check that no file leaving the data machine names a patient
+    bpskit.synthetic   a synthetic BPS delivery with planted structure, for tests
+
+The command line (`bpskit pullable`, `bpskit check-logs`) runs the transfer
+check on the data machine.
+"""
+
+__version__ = "0.2.0"

bpskit-0.2.0/src/bpskit/cli.py

@@ -0,0 +1,102 @@
+"""The transfer checks, run on the data machine before anything is copied off it.
+
+    bpskit pullable [--strict] <path> ...   exit 0 only if no file names a patient
+    bpskit check-logs [workflow_dir]        list the logs that may leave
+    bpskit synthetic <out_dir>              write a synthetic delivery (bpskit.synthetic)
+
+pullable and check-logs run from the workflow directory and read its config
+(default config/config.yaml) for the delivery's id columns and the id files
+under results/work/ids/.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from bpskit import transfer
+from bpskit.delivery import load_config
+
+
+def pullable(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    cfg = load_config(root / args.config)
+    ids = transfer.ids_for_root(root, cfg)
+    n, problems = transfer.check(args.paths, ids, args.strict, transfer.forbidden_columns(cfg))
+    print(f"[CHECK] {n} file(s), {len(problems)} problem(s)")
+    for p in problems:
+        print(f"[REFUSE] {p}")
+    if problems:
+        print("No transfer: these files stay on this machine.")
+        return 1
+    print("[PASS ] no file names a patient")
+    return 0
+
+
+def check_logs(args: argparse.Namespace) -> int:
+    """Write the clean logs to results/work/logs_pullable.txt (which sync.sh copies).
+
+    A traceback can print a data row, so a log containing an id is WITHHELD,
+    not redacted. The list is emptied first, so any failure leaves nothing listed.
+    """
+    root = Path(args.workflow_dir).resolve()
+    out = root / "results/work/logs_pullable.txt"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text("")
+    ids = transfer.ids_for_root(root, load_config(root / args.config))
+    candidates = sorted(
+        list((root / "results/work/logs").rglob("*.log"))
+        + list((root / ".snakemake/log").glob("*.snakemake.log"))
+        + [p for p in [root / "results_run.txt"] if p.exists()]
+    )
+    clean, withheld = [], []
+    for f in candidates:
+        try:
+            why = transfer.check_file(f, ids, strict=False, forbidden=set())
+        except Exception as exc:  # noqa: BLE001 -- fail closed: any error withholds
+            why = [f"could not be checked: {exc}"]
+        (withheld if why else clean).append((f, why))
+    out.write_text("".join(f"{f.relative_to(root).as_posix()}\n" for f, _ in clean))
+    for f, why in withheld:
+        print(f"WITHHELD ({'; '.join(why)}): {f.relative_to(root)}")
+    print(f"{len(clean)} of {len(candidates)} logs cleared")
+    return 0
+
+
+def synthetic(args: argparse.Namespace) -> int:
+    from bpskit.synthetic import make_delivery
+
+    make_delivery(args.out_dir, args.persons, args.seed)
+    print(f"{args.persons:,} synthetic persons -> {args.out_dir}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bpskit", description=__doc__.split("\n")[0])
+    parser.add_argument(
+        "--config",
+        default="config/config.yaml",
+        help="workflow config, relative to the workflow directory",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("pullable", help="refuse files that name a patient")
+    p.add_argument(
+        "--strict",
+        action="store_true",
+        help="results/out/ rules: csv/txt/png only, no per-person columns",
+    )
+    p.add_argument("paths", nargs="+")
+    p.set_defaults(func=pullable)
+    c = sub.add_parser("check-logs", help="list the logs free of patient ids")
+    c.add_argument("workflow_dir", nargs="?", default=".")
+    c.set_defaults(func=check_logs)
+    s = sub.add_parser("synthetic", help="write a synthetic BPS delivery")
+    s.add_argument("out_dir")
+    s.add_argument("--persons", type=int, default=50_000)
+    s.add_argument("--seed", type=int, default=1)
+    s.set_defaults(func=synthetic)
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())