bindsight 0.3.5__tar.gz

bindsight-0.3.5/.dockerignore

@@ -0,0 +1,14 @@
+.git
+.github
+.venv
+.snakemake
+site/
+runs/
+results/
+data/
+**/__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+paper/

bindsight-0.3.5/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yaml,yml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

bindsight-0.3.5/.gitattributes

@@ -0,0 +1,17 @@
+* text=auto eol=lf
+
+*.py text diff=python
+*.md text
+*.yaml text
+*.yml text
+*.toml text
+*.cff text
+Snakefile text
+
+# Binary-y data
+*.parquet binary
+*.tar.gz binary
+*.gz binary
+*.zip binary
+*.cif binary
+*.pdb binary

bindsight-0.3.5/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change is reviewed by the maintainer.
+*       @mikhaeelatefrizk

bindsight-0.3.5/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: Bug report
+description: Something does not work, or works differently from what the docs say.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. The most useful bug reports for this project say
+        what you ran, what happened, and whether it happens on a clean clone —
+        that last one matters, because the defect class this repository keeps
+        finding is code that works only on the machine that wrote it.
+
+  - type: textarea
+    id: what-you-ran
+    attributes:
+      label: The command you ran
+      description: Paste it exactly, including flags and the config file if there was one.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Paste the error or the wrong output. Full traceback if there is one.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-expected
+    attributes:
+      label: What you expected instead
+      description: If a document told you to expect something else, link it.
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: "Output of `bindsight --version`."
+      placeholder: "0.3.5"
+    validations:
+      required: true
+
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`bindsight doctor` output"
+      description: >-
+        This reports your dependencies, caches and vendored data, and resolves
+        most environment questions in one paste.
+      render: shell
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: How you installed it
+      options:
+        - "git clone + pip install -e"
+        - "conda/mamba from envs/discover.yaml"
+        - "Docker"
+        - "Other"
+    validations:
+      required: true
+
+  - type: input
+    id: platform
+    attributes:
+      label: OS and Python version
+      placeholder: "Windows 11, Python 3.12"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: clean-clone
+    attributes:
+      label: Does it happen on a clean clone?
+      options:
+        - label: >-
+            I tried it in a fresh clone with a fresh virtualenv (or I cannot,
+            and have said why above).

bindsight-0.3.5/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,9 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question about using bindsight
+    url: https://github.com/mikhaeelatefrizk/bindsight/discussions
+    about: >-
+      How do I do X, will it work on my data, what does this number mean.
+  - name: Security vulnerability
+    url: https://github.com/mikhaeelatefrizk/bindsight/security/policy
+    about: Please report privately rather than in a public issue.

bindsight-0.3.5/.github/ISSUE_TEMPLATE/reproducibility.yml

@@ -0,0 +1,68 @@
+name: A published number does not reproduce
+description: You followed the documented steps and got a different figure.
+labels: ["reproducibility", "bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This project's whole argument is that its claims are checkable, so a
+        number that does not reproduce is a serious bug, not a support question.
+        Please report it even if you suspect you did something wrong — an
+        instruction that is easy to follow incorrectly is also a defect.
+
+  - type: input
+    id: figure
+    attributes:
+      label: Which number
+      description: The figure as published, and where you read it.
+      placeholder: "recall@20 = 1 of 17, in benchmarks/study/RESULTS.md"
+    validations:
+      required: true
+
+  - type: input
+    id: got
+    attributes:
+      label: What you got instead
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Exactly what you ran
+      description: >-
+        Every command, in order. If you followed a document, link it and say
+        which step you started from.
+      render: shell
+    validations:
+      required: true
+
+  - type: dropdown
+    id: tier
+    attributes:
+      label: Which reproduction tier
+      description: See "Reproducing the results" in the README.
+      options:
+        - "1 — regenerate a published page from committed artifacts (offline)"
+        - "2 — re-run the rediscovery study (network, CPU-hours)"
+        - "3 — re-run the binder design (GPU)"
+    validations:
+      required: true
+
+  - type: input
+    id: commit
+    attributes:
+      label: Commit you ran at
+      description: "Output of `git rev-parse --short HEAD`."
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: >-
+        `bindsight doctor` output, plus the GPU if tier 3. For tier 2, whether
+        `data/gdc_cache/` was already populated — a stale cache is the most
+        common cause of a moved number.
+      render: shell

bindsight-0.3.5/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## What this changes
+
+<!-- One paragraph. What was wrong or missing, and what the change does about it. -->
+
+## Why
+
+<!-- The reasoning, not a restatement of the diff. If it fixes a defect, say how
+     the defect could happen; if it adds a claim, say what backs it. -->
+
+## Checks
+
+- [ ] `python -m pytest -q` passes
+- [ ] `ruff check bindsight tests scripts benchmarks` and
+      `ruff format --check bindsight tests scripts benchmarks` pass
+- [ ] `mypy bindsight scripts benchmarks` passes
+- [ ] If it changes a published number, the artifact was regenerated and the
+      generator produces no diff
+- [ ] If it adds a guard, the guard was **mutation-tested**: the defect
+      reintroduced, the guard confirmed to fail, the tree restored
+
+## If this touches a claim
+
+- [ ] Every surface stating the affected figure is updated, not just the one I
+      was reading
+- [ ] Any withdrawn figure still travels with its withdrawal
+
+<!-- The failure this project keeps finding is a change that is correct in the
+     file it was made in and leaves five other files asserting the old thing. -->

bindsight-0.3.5/.github/dependabot.yml

@@ -0,0 +1,50 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    groups:
+      dev-tooling:
+        patterns: ["ruff", "mypy", "pytest*", "types-*"]
+    # The scientific stack is pinned with upper bounds on purpose: these are the
+    # libraries whose release can move a number a run reports. Their updates
+    # should be deliberate and accompanied by a re-scored artifact, not merged
+    # because CI went green.
+    #
+    # This list is exactly `SCIENTIFIC_STACK - PRESENTATION_ONLY` from
+    # `bindsight/provenance/manifest.py`, which is the project's own declaration
+    # of which distributions move a reported number. It was a hand-written
+    # subset of six, and had silently stopped covering its category: `pyarrow`,
+    # `scikit-learn`, `h5py`, `torch`, `transformers`, `anndata`, `biopython`,
+    # `numcodecs` and `zarr` were all outside it. The bot duly opened pull
+    # requests for three of them, one of which also proposed widening the
+    # `pyarrow<25` bound that exists to keep a published result re-derivable.
+    #
+    # `matplotlib` is deliberately absent: the manifest records it as
+    # presentation-only, so its releases move pixels rather than numbers.
+    #
+    # `tests/test_packaging_pins.py` asserts this list still equals that
+    # declaration, so it cannot quietly fall behind it again.
+    ignore:
+      - dependency-name: "anndata"
+      - dependency-name: "biopython"
+      - dependency-name: "formulaic"
+      - dependency-name: "formulaic-contrasts"
+      - dependency-name: "h5py"
+      - dependency-name: "numcodecs"
+      - dependency-name: "numpy"
+      - dependency-name: "pandas"
+      - dependency-name: "pyarrow"
+      - dependency-name: "pydeseq2"
+      - dependency-name: "scikit-learn"
+      - dependency-name: "scipy"
+      - dependency-name: "torch"
+      - dependency-name: "transformers"
+      - dependency-name: "zarr"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

bindsight-0.3.5/.github/workflows/ci.yml

@@ -0,0 +1,168 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff + mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,discover,report]"
+      - name: Ruff check
+        run: ruff check bindsight tests scripts benchmarks
+      - name: Ruff format
+        run: ruff format --check bindsight tests scripts benchmarks
+      # Blocking. pyproject sets strict = true and CI swallowed the result with
+      # `|| true`, so 53 errors accumulated unnoticed -- including the arity bug
+      # that left the Snakemake front-end dead for five weeks. That front-end is
+      # scripts/, which this step did not check: the justification named a
+      # directory outside its own scope.
+      - name: mypy
+        run: mypy bindsight scripts benchmarks
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        # 3.13 is here because pyproject's classifiers claim it. An interpreter
+        # the project claims and does not test is an untested claim.
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,discover,report]"
+      # The Snakemake front-end is now exercised in CI. It runs offline via
+      # BINDSIGHT_CACHE_DIR and adds ~15 s. Linux only: Snakemake's Windows
+      # support is unreliable, and the test skips itself elsewhere, so this
+      # keeps the signal trustworthy rather than flaky.
+      - name: Install the workflow extra (Linux only)
+        if: runner.os == 'Linux'
+        run: pip install -e ".[workflow]"
+      # Coverage is configured in pyproject and was disabled here by --no-cov,
+      # so it had never actually run. It now runs AND gates: --cov-fail-under
+      # fails the build if coverage regresses below the floor. Kept a couple of
+      # points under the ~77% baseline so ordinary churn doesn't flake, while a
+      # real drop (e.g. a whole module left untested) still trips it.
+      - name: Pytest (no GPU, no slow)
+        run: pytest -m "not gpu and not slow" --maxfail=5 -q --cov-fail-under=75
+
+  # `envs/constraints.txt` calls itself "the exact versions this release was
+  # resolved and tested against". Only the Dockerfile ever applied it; the
+  # matrix above installs unpinned, so the pins governed the container and
+  # nothing else. That is why a Dependabot PR widening a pyproject range was the
+  # only one of four that changed what CI resolved — the others edited a file no
+  # job read.
+  #
+  # The matrix stays unpinned on purpose: it proves the code works across three
+  # Pythons and three platforms. This job proves the *recorded* environment
+  # still resolves and still produces the committed artifacts, which is the
+  # claim the file actually makes.
+  pinned:
+    name: Pinned environment (constraints.txt)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - name: Install exactly what the release records
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c envs/constraints.txt -e ".[dev,discover,report]"
+      - name: The installed versions are the recorded ones
+        run: python scripts/check_pinned_environment.py
+      - name: Regenerating the published pages changes nothing
+        run: |
+          python scripts/build_docs_results.py
+          # Every output the generator writes, assets included. It copies
+          # figures, the twenty predicted complexes, the vendored viewer and its
+          # licence into docs/assets, and the diff once covered only the two
+          # markdown files -- so a benchmark re-run that moved a figure but not
+          # the prose passed this gate while the committed image silently
+          # diverged from the data behind it. The pathspec is the whole
+          # directory rather than a list of its subdirectories, for the same
+          # reason: a list stops covering what is added after it.
+          git diff --exit-code -- docs/results.md docs/glossary.md docs/assets
+          # git diff does not see untracked files, and that mattered the moment
+          # the generator started writing per-design assets: a re-run that
+          # produced a new design would write an uncommitted .cif, the page
+          # would offer it, this gate would stay green, and the published site
+          # would 404 on the one structure nobody had committed.
+          test -z "$(git status --porcelain --untracked-files=all -- docs/assets)"
+
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - name: Install build deps
+        run: pip install build twine
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  gate:
+    # One check for the branch ruleset on `main` to require.
+    #
+    # Naming the nine matrix jobs there instead would pin the ruleset to the
+    # matrix: add a Python version or drop an OS and those contexts no longer
+    # exist, so every merge would wait forever on a check that will never
+    # report, and someone would have to edit the ruleset by hand to recover.
+    # This job's name never changes.
+    #
+    # Which makes `needs` the entire guarantee, so it is held to the rest of
+    # this file by tests/test_packaging_pins.py rather than by memory.
+    name: All CI jobs passed
+    runs-on: ubuntu-latest
+    needs: [lint, test, pinned, build]
+    # Without this the gate is skipped when anything it needs fails, and a
+    # skipped required check never reports -- the merge would block on silence
+    # rather than on the failure, which reads like an outage.
+    if: always()
+    steps:
+      - name: Every job above must have succeeded
+        env:
+          RESULTS: ${{ toJSON(needs) }}
+        run: |
+          printf '%s\n' "$RESULTS"
+          if printf '%s' "$RESULTS" | grep -qE '"result": *"(failure|cancelled|skipped)"'; then
+            echo "::error::a job this gate depends on did not succeed"
+            exit 1
+          fi

bindsight-0.3.5/.github/workflows/docker.yml

@@ -0,0 +1,65 @@
+name: Docker
+
+# Build the CPU image on every PR (verifies the Dockerfile), and build + push
+# to GHCR on pushes to main / tags.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  IMAGE: ghcr.io/${{ github.repository }}
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v4
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request' && vars.PUBLISH_GHCR == 'true'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build (and push on non-PR)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          # Publishing is opt-in. It needs two account-level settings that
+          # `permissions:` cannot grant: the ghcr.io package must list this
+          # repository under Manage Actions access with role Write (the
+          # package predates the current repository object -- the repository
+          # was recreated on 2026-09-14 -- and nothing re-links them on its
+          # own), and the repository variable PUBLISH_GHCR must be `true`.
+          # Until both were done, every push-to-main run failed on
+          # `denied: permission_denied: write_package` and none on the build,
+          # so a red X reported a settings problem as a code problem on every
+          # commit -- which is how a check stops being read at all. The build
+          # below runs either way, so a broken Dockerfile still fails here.
+          #
+          # Both are in place as of 0.3.1. The `org.opencontainers.image.source`
+          # label in the Dockerfile keeps the package connected to this
+          # repository object from here on.
+          push: ${{ github.event_name != 'pull_request' && vars.PUBLISH_GHCR == 'true' }}
+          # A version tag on tag pushes. The workflow triggers on `v*` and
+          # published only `:latest` and `:<sha>`, so a release produced no
+          # tag anyone could pin to — and `:latest` moved under them instead.
+          tags: |
+            ${{ env.IMAGE }}:latest
+            ${{ env.IMAGE }}:${{ github.sha }}
+            ${{ startsWith(github.ref, 'refs/tags/') && format('{0}:{1}', env.IMAGE, github.ref_name) || '' }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Say so when the image was built but not published
+        if: github.event_name != 'pull_request' && vars.PUBLISH_GHCR != 'true'
+        run: |
+          echo "::notice title=Image built, not published::The image built successfully and was NOT pushed to ghcr.io: the repository variable PUBLISH_GHCR is not 'true'. Publishing also needs the package to list this repository under Manage Actions access with role Write."
+

bindsight-0.3.5/.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Docs
+
+# Build the mkdocs-material site and publish it to GitHub Pages.
+# Enable once in repo Settings → Pages → Source: "GitHub Actions".
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "overrides/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+      # docs/results.md is generated from the committed benchmark results, so a
+      # new benchmark run must republish the site.
+      - "benchmarks/**"
+      - "bindsight/report/showcase.py"
+      - "scripts/build_docs_results.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      # The core install is enough: bindsight.report resolves render_run lazily,
+      # so the results generator reaches report/showcase.py without pulling in
+      # pandas or jinja2. tests/test_report_lazy_import.py guards that.
+      - name: Install docs deps
+        run: pip install -e ".[docs]"   # the extra exists for exactly this; one place holds the bound
+      - name: Regenerate the results page from benchmarks/
+        run: python scripts/build_docs_results.py
+      # --strict fails the build on broken internal links. It caught nine
+      # already-live 404s the first time it was switched on.
+      - name: Build site
+        run: mkdocs build --strict --site-dir site
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v5

bindsight-0.3.5/.github/workflows/draft-pdf.yml

@@ -0,0 +1,59 @@
+name: Draft PDF (JOSS)
+
+on:
+  push:
+    paths:
+      - 'paper/paper.md'
+      - 'paper/paper.bib'
+      - '.github/workflows/draft-pdf.yml'
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Compile JOSS paper.md to PDF
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build draft PDF
+        # Pinned to a commit, not to `@master`: whatever lands on that
+        # branch would otherwise run here unreviewed, in the workflow that
+        # builds the submitted paper. This SHA is what the `v1.0` tag points
+        # at and what `master` pointed at when it was pinned, so it is a
+        # no-op today. (The repository also carries a typo'd `v.1.0` tag
+        # pointing somewhere older -- do not reach for it.)
+        uses: openjournals/openjournals-draft-action@85a18372e48f551d8af9ddb7a747de685fbbb01c  # v1.0
+        with:
+          journal: joss
+          paper-path: paper/paper.md
+      - name: Upload as artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: paper
+          path: paper/paper.pdf
+          if-no-files-found: error
+
+  attach:
+    name: Attach to the release
+    needs: paper
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: paper
+          path: paper
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name }}
+        # Renamed so the asset says which document it is next to the wheel,
+        # the sdist and the bioRxiv manuscript's PDF.
+        run: |
+          cp paper/paper.pdf "bindsight-${TAG}-joss-paper.pdf"
+          gh release upload "$TAG" "bindsight-${TAG}-joss-paper.pdf" --clobber --repo "${{ github.repository }}"