meds-summary-stats 0__tar.gz

meds_summary_stats-0/.github/actions/setup/action.yaml

@@ -0,0 +1,30 @@
+name: Setup Package
+description: This workflow sets up the package for other workflows.
+inputs:
+  python-version:
+    description: The Python version to use for the setup.
+    required: true
+    default: "3.11"
+  group:
+    description: The dependency group to install (benchmarks, dev, docs)
+    required: false
+    default: "dev"
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-python@v7.0.0
+      with:
+        python-version: "${{ inputs.python-version }}"
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v9.0.0
+      with:
+        enable-cache: true
+        cache-suffix: "py${{ inputs.python-version }}"
+
+    - name: Install packages
+      shell: bash
+      env:
+        UV_GROUP: ${{ inputs.group }}
+      run: |
+        uv sync --locked --group "$UV_GROUP"

meds_summary_stats-0/.github/dependabot.yml

@@ -0,0 +1,44 @@
+version: 2
+updates:
+  # GitHub Actions: track action versions across workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    # Wait 7 days after a release before opening an update PR. Mitigates
+    # supply-chain risk by giving time for malicious releases to be flagged
+    # and yanked before they propagate here.
+    cooldown:
+      default-days: 7
+    # Skip patch-level Action updates — they're almost always non-functional
+    # changes to the action's own README or CI. Security advisories fire on
+    # a separate channel regardless of this filter.
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-patch"]
+    groups:
+      actions:
+        patterns: ["*"]
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    open-pull-requests-limit: 5
+
+  # Python dependencies via uv (pyproject.toml + uv.lock).
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    groups:
+      python:
+        patterns: ["*"]
+    commit-message:
+      prefix: "deps"
+    labels:
+      - "dependencies"
+      - "python"
+    open-pull-requests-limit: 5

meds_summary_stats-0/.github/workflows/action-selftest.yaml

@@ -0,0 +1,124 @@
+# Exercises `action.yml` against itself.
+#
+# A composite action is not covered by the Python test suite: its shell, its argument threading, and
+# its output wiring only run in Actions. This workflow builds a throwaway MEDS dataset, runs the
+# action in extract-only mode to produce a baseline, then runs it again in comparison mode -- once
+# where it must pass and once, against a deliberately corrupted baseline, where it must fail.
+
+name: Action self-test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  selftest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup package
+        uses: ./.github/actions/setup
+        with:
+          python-version: "3.12"
+
+      - name: Build a throwaway MEDS dataset
+        run: |
+          uv run build_sample_MEDS_dataset \
+            seed=1 N_subjects=200 do_overwrite=False \
+            output_dir=sample_dataset dataset_spec/data_generator=sample
+
+      - name: Extract a baseline
+        id: baseline
+        uses: ./
+        with:
+          meds-dir: sample_dataset
+          output: baseline.json
+          package-spec: .
+          upload-artifacts: "false"
+
+      - name: Baseline was produced
+        env:
+          STATS_PATH: ${{ steps.baseline.outputs.stats-path }}
+        run: test -s "$STATS_PATH"
+
+      - name: Compare against the baseline (must pass)
+        id: clean
+        uses: ./
+        with:
+          meds-dir: sample_dataset
+          baseline: baseline.json
+          output: current.json
+          package-spec: .
+          artifact-name: selftest-clean
+
+      - name: Comparison reported a pass
+        env:
+          STATUS: ${{ steps.clean.outputs.status }}
+          FAILED: ${{ steps.clean.outputs.failed }}
+        run: |
+          echo "status=$STATUS failed=$FAILED"
+          test "$STATUS" = "pass"
+          test "$FAILED" = "false"
+
+      - name: Corrupt the baseline
+        run: |
+          uv run python -c "
+          import json, pathlib
+          p = pathlib.Path('corrupted.json')
+          stats = json.loads(pathlib.Path('baseline.json').read_text())
+          stats['counts']['n_subjects'] = int(stats['counts']['n_subjects'] * 0.5)
+          p.write_text(json.dumps(stats))
+          "
+
+      - name: Compare against the corrupted baseline (must fail)
+        id: dirty
+        continue-on-error: true
+        uses: ./
+        with:
+          meds-dir: sample_dataset
+          baseline: corrupted.json
+          output: current2.json
+          report: report2.json
+          markdown: report2.md
+          package-spec: .
+          artifact-name: selftest-dirty
+
+      - name: Regression was detected and failed the step
+        env:
+          OUTCOME: ${{ steps.dirty.outcome }}
+          STATUS: ${{ steps.dirty.outputs.status }}
+        run: |
+          echo "outcome=$OUTCOME status=$STATUS"
+          test "$OUTCOME" = "failure"
+          test "$STATUS" = "fail"
+          grep -q "counts.n_subjects" report2.json
+
+      - name: fail-on never reports the regression without failing
+        id: advisory
+        uses: ./
+        with:
+          meds-dir: sample_dataset
+          baseline: corrupted.json
+          output: current3.json
+          report: report3.json
+          markdown: report3.md
+          fail-on: never
+          package-spec: .
+          artifact-name: selftest-advisory
+
+      - name: Advisory mode still reports the failure status
+        env:
+          STATUS: ${{ steps.advisory.outputs.status }}
+          FAILED: ${{ steps.advisory.outputs.failed }}
+        run: |
+          test "$STATUS" = "fail"
+          test "$FAILED" = "false"

meds_summary_stats-0/.github/workflows/code-quality-main.yaml

@@ -0,0 +1,28 @@
+# Same as `code-quality-pr.yaml` but triggered on commit to main branch
+# and runs on all files (instead of only the changed ones)
+
+name: Code Quality Main
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  code-quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup package
+        uses: ./.github/actions/setup
+        with:
+          python-version: "3.12"
+
+      - name: Run pre-commits
+        run: uv run pre-commit run --all-files --show-diff-on-failure

meds_summary_stats-0/.github/workflows/code-quality-pr.yaml

@@ -0,0 +1,46 @@
+# This workflow finds which files were changed, prints them,
+# and runs `pre-commit` on those files.
+
+# Inspired by the sktime library:
+# https://github.com/alan-turing-institute/sktime/blob/main/.github/workflows/test.yml
+
+name: Code Quality PR
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  code-quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup package
+        uses: ./.github/actions/setup
+        with:
+          python-version: "3.12"
+
+      - name: Find modified files
+        id: file_changes
+        uses: tj-actions/changed-files@v47.0.6
+
+      - name: List all changed files
+        env:
+          ALL_CHANGED_FILES: ${{ steps.file_changes.outputs.all_changed_files }}
+        run: echo "$ALL_CHANGED_FILES"
+
+      - name: Run pre-commits
+        env:
+          ALL_CHANGED_FILES: ${{ steps.file_changes.outputs.all_changed_files }}
+        run: |
+          # Intentional word splitting: the action output is a space-separated
+          # list of file paths.
+          # shellcheck disable=SC2086
+          uv run pre-commit run --show-diff-on-failure --files $ALL_CHANGED_FILES

meds_summary_stats-0/.github/workflows/meds-stats-regression.yaml

@@ -0,0 +1,184 @@
+# Reusable workflow: run the MEDS summary-stats regression check as its own job.
+#
+# Use this when you want the check to have separate logs, its own runner, and its own summary panel.
+# Use the composite action in `action.yml` instead when you want it as a step inside a job that has
+# already built the dataset. See docs/github-action.md.
+#
+# This invokes the CLIs directly rather than reusing `action.yml`. A reusable workflow cannot
+# reference an action from its own repository at the ref it was called with -- it would have to
+# hardcode one -- so calling this at a tag would silently run `main`'s action. Invoking the
+# published package via `package-spec` keeps the version under the caller's control instead.
+
+name: MEDS summary-stats regression
+
+on:
+  workflow_call:
+    inputs:
+      meds-dir:
+        description: Root of the MEDS dataset to summarize.
+        required: true
+        type: string
+      baseline:
+        description: Path to the baseline stats JSON. Leave empty to extract only.
+        required: false
+        default: ""
+        type: string
+      build-command:
+        description: >-
+          Shell command run before extraction, to produce the dataset (an ETL invocation, a
+          download, a decrypt). Leave empty if `meds-dir` already exists in the checkout.
+        required: false
+        default: ""
+        type: string
+      policy:
+        description: Path to a YAML comparison policy.
+        required: false
+        default: ""
+        type: string
+      extract-config:
+        description: Path to a YAML extraction config.
+        required: false
+        default: ""
+        type: string
+      fail-on:
+        description: "Minimum severity that fails the job: error, warning, or never."
+        required: false
+        default: error
+        type: string
+      on-dataset-version-change:
+        description: "ignore, warn, error, or relax."
+        required: false
+        default: warn
+        type: string
+      package-spec:
+        description: What to install, e.g. 'meds_summary_stats==0.1.0'. Pin it for reproducible CI.
+        required: false
+        default: meds_summary_stats
+        type: string
+      python-version:
+        description: Python version used to run the tool.
+        required: false
+        default: "3.12"
+        type: string
+      runs-on:
+        description: Runner label.
+        required: false
+        default: ubuntu-latest
+        type: string
+      timeout-minutes:
+        description: Job timeout.
+        required: false
+        default: 60
+        type: number
+    outputs:
+      status:
+        description: "pass, warn, or fail -- what was found."
+        value: ${{ jobs.check.outputs.status }}
+      failed:
+        description: "'true' if the findings breached fail-on -- what the policy makes of it."
+        value: ${{ jobs.check.outputs.failed }}
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ${{ inputs.runs-on }}
+    timeout-minutes: ${{ inputs.timeout-minutes }}
+    outputs:
+      status: ${{ steps.compare.outputs.status }}
+      failed: ${{ steps.compare.outputs.failed }}
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@v7.0.0
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+          cache-suffix: meds-summary-stats
+
+      - name: Build the dataset
+        if: inputs.build-command != ''
+        shell: bash
+        env:
+          BUILD_COMMAND: ${{ inputs.build-command }}
+        run: bash -euo pipefail -c "$BUILD_COMMAND"
+
+      # Inputs reach the shell through `env:` rather than `${{ }}` interpolation, so a value
+      # containing shell metacharacters is data, not code.
+      - name: Extract summary statistics
+        shell: bash
+        env:
+          MEDS_DIR: ${{ inputs.meds-dir }}
+          EXTRACT_CONFIG: ${{ inputs.extract-config }}
+          PACKAGE_SPEC: ${{ inputs.package-spec }}
+        run: |
+          set -euo pipefail
+          args=("$MEDS_DIR" --output meds-summary-stats.json)
+          if [[ -n "$EXTRACT_CONFIG" ]]; then args+=(--config "$EXTRACT_CONFIG"); fi
+          uvx --from "$PACKAGE_SPEC" extract_MEDS_summary_stats "${args[@]}"
+
+      - name: Compare against baseline
+        id: compare
+        if: inputs.baseline != ''
+        shell: bash
+        env:
+          BASELINE: ${{ inputs.baseline }}
+          POLICY: ${{ inputs.policy }}
+          FAIL_ON: ${{ inputs.fail-on }}
+          ON_VERSION_CHANGE: ${{ inputs.on-dataset-version-change }}
+          PACKAGE_SPEC: ${{ inputs.package-spec }}
+        run: |
+          set -uo pipefail
+
+          if [[ ! -f "$BASELINE" ]]; then
+            echo "::error::Baseline file not found: $BASELINE"
+            exit 1
+          fi
+
+          args=("$BASELINE" meds-summary-stats.json
+                --output meds-summary-stats-report.json
+                --markdown meds-summary-stats-report.md
+                --fail-on "$FAIL_ON"
+                --on-dataset-version-change "$ON_VERSION_CHANGE")
+          if [[ -n "$POLICY" ]]; then args+=(--config "$POLICY"); fi
+
+          # The tool writes its markdown to $GITHUB_STEP_SUMMARY and its verdict to $GITHUB_OUTPUT
+          # itself. `set -e` is off deliberately: exit 1 means "regression found", which must not
+          # abort before artifacts upload. Anything above 1 is a genuine tool failure.
+          uvx --from "$PACKAGE_SPEC" compare_MEDS_summary_stats "${args[@]}"
+          code=$?
+          if (( code > 1 )); then
+            echo "::error::compare_MEDS_summary_stats exited with code $code"
+            exit "$code"
+          fi
+
+      - name: Upload artifacts
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: meds-summary-stats
+          path: |
+            meds-summary-stats.json
+            meds-summary-stats-report.json
+            meds-summary-stats-report.md
+          if-no-files-found: warn
+          retention-days: 90
+
+      - name: Fail on regression
+        if: steps.compare.outputs.failed == 'true'
+        shell: bash
+        env:
+          STATUS: ${{ steps.compare.outputs.status }}
+          N_ERRORS: ${{ steps.compare.outputs.n_errors }}
+          N_WARNINGS: ${{ steps.compare.outputs.n_warnings }}
+        run: |
+          echo "::error::MEDS summary-stats comparison reported '${STATUS}'" \
+               "(${N_ERRORS} errors, ${N_WARNINGS} warnings). See the job summary for details."
+          exit 1

meds_summary_stats-0/.github/workflows/python-build.yaml

@@ -0,0 +1,112 @@
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+
+on: push
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/meds_summary_stats
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.0
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+      - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write # IMPORTANT: mandatory for sigstore
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.4.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          REF_NAME: ${{ github.ref_name }}
+          REPOSITORY: ${{ github.repository }}
+        run: >-
+          gh release create
+          "$REF_NAME"
+          --repo "$REPOSITORY"
+          --generate-notes
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          REF_NAME: ${{ github.ref_name }}
+          REPOSITORY: ${{ github.repository }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          "$REF_NAME" dist/**
+          --repo "$REPOSITORY"

meds_summary_stats-0/.github/workflows/tests.yaml

@@ -0,0 +1,71 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests_ubuntu:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+
+    timeout-minutes: 30
+
+    # `secrets` is not among the contexts available to a step-level `if`, so the token is hoisted
+    # into the job environment where the Codecov steps can test it.
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup package
+        uses: ./.github/actions/setup
+        with:
+          python-version: "3.12"
+
+      # No `--ignore=docs` here, unlike the template: this project's docs are hand-written and
+      # doctested, so skipping them in CI would let a documented example drift from real output.
+      - name: Run tests
+        run: >
+          uv run pytest -v
+          --cov=src
+          --cov-report=xml:coverage.xml
+          --cov-report=term
+          --junitxml=junit.xml
+
+      # Skip Codecov when there is no token to use. Two cases: Dependabot runs do not get
+      # repository secrets (a deliberate GitHub security policy), and a freshly created repository
+      # has not had its token configured yet. In both, uploading is impossible rather than broken,
+      # so failing the run would be reporting the wrong problem. `fail_ci_if_error` stays on, so a
+      # genuine upload failure with a token present is still loud.
+      - name: Upload coverage to Codecov
+        if: env.CODECOV_TOKEN != '' && github.actor != 'dependabot[bot]'
+        uses: codecov/codecov-action@v7.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          fail_ci_if_error: true
+          verbose: true
+          # Install the Codecov CLI from PyPI rather than downloading the prebuilt binary. The
+          # binary path GPG-verifies the download against a key fetched from a keyserver, and that
+          # fetch fails on GitHub-hosted runners ("gpg: no valid OpenPGP data found" ->
+          # "Can't check signature: No public key"), taking the whole job down with it. PyPI
+          # installation is verified by the index instead and does not depend on keyserver
+          # reachability.
+          use_pypi: true
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() && env.CODECOV_TOKEN != '' && github.actor != 'dependabot[bot]' }}
+        uses: codecov/test-results-action@v1.2.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: junit.xml

meds_summary_stats-0/.github/zizmor.yml

@@ -0,0 +1,29 @@
+# zizmor configuration. See https://docs.zizmor.sh/configuration/
+#
+# `unpinned-uses`: zizmor's default policy requires every action reference to be
+# a 40-char commit SHA. That is the strictest stance but high friction even with
+# Dependabot. We relax it to allow tag-pinning (`ref-pin`) for publishers we
+# explicitly trust, and require commit-hash-pinning (`hash-pin`) for everything
+# else. Dependabot (.github/dependabot.yml) keeps the tag pins current.
+rules:
+  unpinned-uses:
+    config:
+      policies:
+        # First-party GitHub-owned actions.
+        actions/*: ref-pin
+        github/*: ref-pin
+        # Astral (uv, ruff, ty).
+        astral-sh/*: ref-pin
+        # Codecov (coverage + test results upload).
+        codecov/*: ref-pin
+        # PyPA (Python Packaging Authority).
+        pypa/*: ref-pin
+        # Sigstore (Linux Foundation).
+        sigstore/*: ref-pin
+        # Pre-commit hook authors used in this repo's workflows.
+        rhysd/*: ref-pin
+        # tj-actions/changed-files (had a March-2025 supply-chain compromise;
+        # consider tightening to hash-pin if you want stricter security).
+        tj-actions/*: ref-pin
+        # Default for everything else: require commit-hash pinning.
+        "*": hash-pin