Skip to content

Serve the 2026-09 release from Cameo and execute all docs notebooks against it - #126

Merged
tjduigna merged 30 commits into
major_refactorfrom
release-date-prefix
Oct 9, 2026
Merged

tjduigna merged 30 commits into
major_refactorfrom
release-date-prefix

Conversation

@tjduigna

@tjduigna tjduigna commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

The current 2026-09 dataset is hotfixed on the Cameo file server. This PR makes the package use that release directly by default, so users can install this branch and get the current data without a hosting override.

Release access

  • DEFAULT_RELEASE = "2026-09"; remote releases use https://cameo3d.org/plinder/PLINDER-<YYYY-MM>/. The local cache stays at <mount>/<bucket>/<YYYY-MM>/.
  • Replace the R2 manifest client with direct HTTP directory listing and HEAD metadata. No separately generated manifest or cloud credentials are required. PLINDER_MIRROR_URL can select another file-server root with the same layout and directory indexes.
  • Refresh listings and metadata on every download API call. Reuse cached files only when size and Last-Modified match; fetch same-size server hotfixes when their timestamp changes. After successful directory downloads, remove cached Parquet fragments that the server no longer lists.
  • Keep streaming transfers, eight download workers, atomic replacement, interrupted-transfer retries, offline mode, and path containment. Metadata and directory requests also retry transient errors. Failed transfers preserve existing cached files.
  • Update the README, dataset/getting-started pages, download notebook, and hosting documentation. Remove the unused R2 manifest builder.

Cameo does not publish per-file checksums. Transfers validate HTTP Content-Length rather than MD5. Publishers must update Last-Modified when replacing a file; a same-size change preserving that timestamp requires data.force_update=true.

Other changes retained in this branch

  • Includes ci: drop Docker, run tests directly on the runner #127: runner-based CI and uv installation, replacing the old Docker environment.
  • Merges fix/major-refactor-bugs, including monomer search support and public-release staging.
  • Fixes lazy ligand-similarity reconstruction by fetching the matching protein-score shard, and avoids CIGAR decoding when custom alignments already contain residue numbers.
  • Handles empty monomer databases through generation, asset resolution, and public-release preparation; includes pandas 3 compatibility fixes.
  • Executes all eight documentation notebooks against the package's default public release, without release overrides or a notebook skip list.

Validation for the Cameo change

  • Focused HTTP/config suite: 54 passed. Covers a server without a manifest, nested/encoded directory paths, same-size hotfixes, cache reuse, removed Parquet fragments, forced refresh, offline behavior, retries, truncated transfers, and preservation of cached files after failure.
  • Core suite: 304 passed, 1 skipped.
  • All pre-commit checks passed; CI-style mypy passed for all 93 source files.
  • Live Cameo smoke tests from fresh temporary caches: downloaded/read index/entry_sources.parquet (259,015 rows), downloaded/read both protein_clusters files (1,093,677 rows each), traversed release and nested export directories, and confirmed that unchanged cached files are not transferred again.
  • GitHub CI passed on 2026-10-09: 1,357 tests passed, 1 skipped, coverage 81.72%; code quality passed; the documentation build succeeded with all eight notebooks executed against the default Cameo release.

@tjduigna tjduigna changed the title fix: serve 2026-09 from R2 without a release-number prefix fix: serve date-stamped (YYYY-MM) releases from R2 without a release-number prefix Sep 30, 2026
- restore the original physical schema when DuckDB rewrites a patched
  alignment shard (DuckDB writes string; pandas 3 writes large_string)
- assert missing string values with isna() so the query test holds for
  pandas 2 (None) and pandas 3 (NaN)
…nts_data.txt

- dev dependency group is the complete CI/dev environment (adds plots
  extra and semver); networkit must come from a wheel via no-build-package
- commit uv.lock and install with uv sync --locked into the Conda env
  that provides the conda-only tools (openstructure, mmseqs2, foldseek)
- build release distributions with uv build
- pin the project Python to 3.12 with .python-version
…tion

Published CIGAR shards omit alignment scores, so Scorer.load_alignments reads
the matching exports/protein_similarity_scores shard. prefetch only downloaded
the CIGAR shards, so reconstruct_similarity_scores failed on a lazily
populated cache. Register the score shard as a release path and fetch it when
include_protein_scores=True (used by ligand reconstruction only).
- drop the PLINDER_RELEASE=2026-07 / PLINDER_RELEASE_NUMBER=1 overrides so
  notebooks use the default release and download lazily from R2
- remove the notebook execution skip list
- install docs builds with uv sync --locked --extra docs into the Conda env
  (OpenStructure and MMseqs2 are needed by the evaluation and search notebooks)
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown

Coverage report

Click to see where and how coverage changed

FileStatementsMissingCoverageCoverage
(new stmts)
Lines missing
  src/plinder/core/scores
  custom.py 235, 371, 379, 1176, 1180, 1245-1251, 1259-1272, 2094-2101, 2160, 2183, 2189, 2845, 2856-2875, 3164, 3175-3192
  protein.py
  reconstruct.py 58
  search.py
  src/plinder/core/utils
  config.py
  cpl.py 59, 82, 120
  http.py 57, 119, 132, 138, 178, 215, 220
  src/plinder/data
  clusters.py 619, 635, 824, 3140, 3146, 3157-3161
  databases.py
  monomer_similarity.py 41, 55, 70-72, 122-126, 174-233, 247, 274, 277, 295-317, 321
  src/plinder/data/annotations
  cif_utils.py
  get_similarity_scores.py 2763
  src/plinder/data/pipeline
  pipeline.py
  public_release.py 46, 51, 64, 72, 75, 103, 110, 114, 136-139, 144, 149-162, 166
  score.py 3417, 7565
  tasks.py 662, 2640
  update_release.py 300, 325, 331, 552, 1095, 1113, 2448, 2453
  updates.py 266, 273
  utils.py 46-47
Project Total  

This report was generated by python-coverage-comment-action

…numbers

Custom-scoring alignments keep their CIGAR column but are already mapped to
query/target residue numbers. load_alignments only checked for decoded
positions, so it tried to decode them, which needs a release chain lookup the
custom scorer doesn't have (ValueError: CIGAR alignments require a chain
lookup). Found by executing docs/examples/custom_scoring.ipynb.
@tjduigna tjduigna changed the title fix: serve date-stamped (YYYY-MM) releases from R2 without a release-number prefix Serve the 2026-09 release from R2 and execute all docs notebooks against it Oct 1, 2026
tjduigna and others added 14 commits October 2, 2026 10:06
CI now tests the dependency set users get from pip, catching upstream
breakage early rather than through a lockfile that must be refreshed.
…lease-date-prefix

# Conflicts:
#	src/plinder/core/release.py
- make_sub_dbs now also builds monomer databases whenever holo is built; when
  no monomer chains exist (e.g. the end-to-end test entry) linclust segfaults
  on the empty database. Skip monomer databases with no chains; downstream
  bundling already treats them as optional.
- check query_batch_index is not None so mypy can narrow the batch slice.
The end-to-end entry has monomer chains, but none are selected into the
MMseqs sub-database, so the chain-count check in make_sub_dbs never fired and
linclust still crashed. Check the selected database instead and skip
clustering an empty monomer universe; revert the earlier chain-count check.
- README, getting-started and migration pages now point at 2026-09 on
  plinderdata.org instead of 2024-06/v2 and the release-number layout
- regenerate the release tree in docs/dataset.md from the published manifest
  (adds protein_clusters, ligand_pocket_residues, apo/interface_apo CIGARs and
  the manifest; drops ligand_archives/manifest.json and per-fragment
  ligand_scores)
- document the manifest builder's prefix argument and the publish order /
  Cache-Control needed for manifest updates
- directory downloads drop cached Parquet files the release no longer lists,
  so dataset readers never mix removed fragments (e.g. the 290 old
  ligand_scores files removed from 2026-09) with their replacements
- skipping an empty monomer sub-database also retires an earlier build, so a
  stale monomer target is never published as current
- custom scoring treats monomer search databases as optional per backend, and
  public_release no longer requires monomer artifacts, matching the pipeline
- monomer chain masks cast fillna results to bool for pandas 3
- build_r2_manifest skips a root folder placeholder; clarify its prefix
  argument
@tjduigna tjduigna changed the title Serve the 2026-09 release from R2 and execute all docs notebooks against it Serve the 2026-09 release from Cameo and execute all docs notebooks against it Oct 8, 2026
@tjduigna
tjduigna requested a review from Ninjani October 9, 2026 13:21
@tjduigna
tjduigna merged commit e6add68 into major_refactor Oct 9, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants