Merge main into next

CONTRIBUTING.md

@@ -287,9 +287,9 @@ Note that office hours are not recorded.
 | 2026-02-27 | 15.30 - 16.30 | ✅ Complete |
 | 2026-03-27 | 10.30 - 11.30 | ✅ Complete |
 | 2026-04-24 | 15.30 - 16.30 | ✅ Complete |
-| 2026-05-29 | 10.30 - 11.30 | Planned     |
-| 2026-06-26 | 15.30 - 16.30 | Planned     |
-| 2026-07-31 | 10.30 - 11.30 | Planned     |
+| 2026-05-29 | 10.30 - 11.30 | ✅ Complete |
+| 2026-06-26 | 15.30 - 16.30 | ✅ Complete |
+| 2026-07-31 | 10.30 - 11.30 | ✅ Complete |
 | 2026-08-28 | 15.30 - 16.30 | Planned     |
 | 2026-09-25 | 10.30 - 11.30 | Planned     |
 | 2026-10-30 | 15.30 - 16.30 | Planned     |

docs/program/ecosystem.md

@@ -0,0 +1,49 @@
+# ProtVista adoption & ecosystem
+
+_A curated record of who uses, re-implements, deploys, or cites ProtVista. This single
+hand/LLM-maintained table is the source of truth; its **git history** is the point-in-time record._
+
+- **Type:** `package consumer` | `ProtVista-type viewer` | `fork` | `commercial/private` | `unclear`.
+- **Evidence:** the strongest public pointer (repo / paper / live site), or
+  `private — under agreement` where there is no public artifact.
+- **Since / Until:** when the project's ProtVista relationship began and, if it has, ended. The
+  *kind* of date is written in each cell because it means different things per type:
+  - **package consumer:** `(dep added)` the dependency entered package.json, or `(repo created)`;
+    Until `(dep removed)` / `(archived)`.
+  - **fork / ProtVista-type viewer:** `(repo created)` or `(paper)` when their viewer first appeared;
+    Until is usually `—` (no dependency to remove).
+  - **commercial/private:** `(interest)` when engagement began; Until when it ended.
+  - **unclear:** `(paper)` / `(UI mention)`.
+  - `—` in *Since* means the date is not yet filled (run `protvista_ecosystem.py --backfill-dates` to
+    fill repo-created dates); `—` in *Until* means the relationship is ongoing / not applicable.
+- **Status:** current liveness (active / dormant / archived); **Last activity:** last repo push.
+- Package consumers are refreshed by `scripts/protvista_ecosystem.py`; everything else is human-curated.
+- **Out of scope:** generic use of individual `@nightingale-elements/*` track components for unrelated
+  purposes (but a ProtVista-style feature viewer built on nightingale counts as a `ProtVista-type viewer`).
+- **Consent / PII:** name a commercial/private partner only with recorded consent — otherwise
+  `Commercial adopter (<sector>)`. Never add an unconsented name to this file.
+
+## Ecosystem entities
+
+| Project / repo | Type | Evidence | Since | Until | Status | Last activity | Note |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| UniProt website (`ebi-uniprot/uniprot-website`) | package consumer | https://github.com/ebi-uniprot/uniprot-website | 2020-04-29 (dep added) | — | active | 2026-04-30 | ProtVista's largest embedder (UniProtKB) |
+| GIFTS curation tool (`ebi-uniprot/gifts-curation-tool`) | package consumer | https://github.com/ebi-uniprot/gifts-curation-tool | 2021-10-11 (dep added) | — | active | 2025-12-09 | EBI |
+| JCVI Human Salivary Proteome Wiki (`JCVenterInstitute/HSPW-V3`) | package consumer | https://github.com/JCVenterInstitute/HSPW-V3 | 2023-05-10 (dep added) | — | active | 2026-02-04 | — |
+| `KSerditov/ProteinSearch` | package consumer | https://github.com/KSerditov/ProteinSearch | 2023-07-22 (dep added) | — | dormant | 2024-02-10 | independent developer |
+| `ekondrashkov/proteins` | package consumer | https://github.com/ekondrashkov/proteins | 2024-12-09 (dep added) | — | dormant | 2024-12-10 | independent developer |
+| OTPSS (`maniexcelra/OTPSS`) | package consumer | https://github.com/maniexcelra/OTPSS | 2022-06-10 (dep added) | — | dormant | 2024-09-16 | personal Open Targets-derived repo (not official OT); two package.json manifests |
+| Open Targets Platform (`opentargets-archive/platform-app`) | package consumer | https://github.com/opentargets-archive/platform-app | 2019-10-08 (dep added) | — (archived) | dormant | 2022-06-22 | historical — Open Targets no longer uses the package |
+| Open Targets Genetics (`opentargets-archive/genetics-app`) | package consumer | https://github.com/opentargets-archive/genetics-app | 2025-01-31 (when repo was archived) | — (archived) | dormant | 2025-01-31 | historical — Open Targets no longer uses the package; adoption/archive dates uncertain (archived repo — likely a late commit, verify) |
+| GlyGen (`glygener/glygen-frontend`) | unclear | https://www.glygen.org | 2021 (paper) | — | — | — | live `<protvista-uniprot>` deployment via CDN per bioRxiv 10.1101/2021.06.17.448729 (not declared in package.json); current use unverified |
+| Pharos / TCRD (`ncats/protvista-viewer`) | fork | https://github.com/ncats/protvista-viewer | 2021-02-09 (repo created) | — | dormant | 2024-08-01 | verified: shares git history with upstream; publishes `ncats-protvista-uniprot` on npm |
+| PDBe (`PDBeurope/protvista-pdb`) | ProtVista-type viewer | https://doi.org/10.1101/2022.07.22.500790 | 2022 (paper) | — | active | 2025-07-08 | independent re-implementation (no shared git history) |
+| RCSB Saguaro 1D Feature Viewer (`rcsb/rcsb-saguaro`) | ProtVista-type viewer | https://github.com/rcsb/rcsb-saguaro | — (repo created) | — | active | — | RCSB PDB's own 1D sequence-feature viewer (TypeScript); independent — does NOT use protvista or nightingale; the RCSB 1D tools paper (2020) cites the ProtVista paper |
+| InterMine BlueGenes (`intermine/bluegenesProtVista`) | ProtVista-type viewer | https://github.com/intermine/bluegenesProtVista | 2018-08-17 (repo created) | — | dormant | 2020-07-10 | independent re-implementation |
+| ProteomicsDB (`wilhelm-lab/protvista-proteomicsdb`) | ProtVista-type viewer | https://github.com/wilhelm-lab/protvista-proteomicsdb | 2021-09-18 (repo created) | — | dormant | 2023-08-30 | independent re-implementation |
+| 3DBIONOTES (`3dbionotes-community/myProtVista`) | ProtVista-type viewer | https://github.com/3dbionotes-community/myProtVista | 2019-02-14 (repo created) | — | dormant | 2020-07-06 | appears ProtVista-derived; unverified |
+| MolArt (`davidhoksza/protvista`) | fork | https://github.com/davidhoksza/protvista | 2017-08-30 (repo created) | — | — | — | fork of the original ProtVista (pre-`protvista-uniprot` rename); basis of the MolArt molecular-annotation tool. Run --backfill-dates for Since |
+| ProKinO | ProtVista-type viewer | https://pubmed.ncbi.nlm.nih.gov/38077442/ | 2021 (paper) | — | — | — | no public repo; derivative of PDBe's protvista-pdb; npm `protvista-prokino` (last publish 2021) |
+| InterPro (EBI) | ProtVista-type viewer | https://www.ebi.ac.uk/interpro/ | — (date unknown) | — | active | — | builds its own ProtVista-style protein feature viewer (nightingale-based) |
+| ENACTdb | ProtVista-type viewer | https://www.iscbglab.in/enactdb/ | 2024 (paper) | — | active | — | ProtVista-style viewer (nightingale-based), live at iscbglab.in/enactdb; described in Bioinformatics Advances (vbae157) |
+| ProteInfer (Google Research) | unclear | https://google-research.github.io/proteinfer/ | — (UI mention) | — | — | — | UI label mentions ProtVista; does not unambiguously demonstrate use of the library |

docs/program/npm_downloads.csv

@@ -0,0 +1,20 @@
+# npm downloads for protvista-uniprot. Raw HTTP fetch events — inflated by CI/mirror/bot traffic and dominated by UniProt's builds; a baseline trend, NOT an adoption count.
+month,package,downloads
+2025-01,protvista-uniprot,999
+2025-02,protvista-uniprot,780
+2025-03,protvista-uniprot,1149
+2025-04,protvista-uniprot,381
+2025-05,protvista-uniprot,767
+2025-06,protvista-uniprot,1683
+2025-07,protvista-uniprot,1601
+2025-08,protvista-uniprot,732
+2025-09,protvista-uniprot,1106
+2025-10,protvista-uniprot,2127
+2025-11,protvista-uniprot,1038
+2025-12,protvista-uniprot,2336
+2026-01,protvista-uniprot,1080
+2026-02,protvista-uniprot,1043
+2026-03,protvista-uniprot,1079
+2026-04,protvista-uniprot,1423
+2026-05,protvista-uniprot,1298
+2026-06,protvista-uniprot,1101

scripts/README.md

@@ -0,0 +1,115 @@
+# ProtVista metrics & adoption tooling
+
+Small, dependency-light tools that maintain ProtVista's **adoption / usage metrics**.
+Three deliberately independent artifacts — a curated *entity table*, an auto
+*download series*, and an ad-hoc *citation number* — kept as separate files and read
+individually, never merged into one.
+
+## Requirements
+
+| Need | For | Notes |
+| --- | --- | --- |
+| `python3` (≥ 3.8) | all | standard library only |
+| `gh` (authenticated) | ecosystem discovery | `gh auth status`; GitHub code search + contents |
+| network | npm + citations | npm downloads API, OpenAlex API |
+
+No `pip install` step.
+
+## The tools
+
+| Script | What it does | Run |
+| --- | --- | --- |
+| `update_metrics.sh` | runs all three of the below in sequence (continues if one fails) | `bash scripts/update_metrics.sh` |
+| `protvista_ecosystem.py` | discover new `package.json` dependents → append rows to `ecosystem.md`, flag fell-out | `python3 scripts/protvista_ecosystem.py` |
+| `npm_downloads.py` | update the committed monthly download CSV | `python3 scripts/npm_downloads.py` |
+| `protvista_citation_count.py` | print the citing-works count (ad-hoc; writes nothing) | `python3 scripts/protvista_citation_count.py` |
+| `test_ecosystem_tools.py` | unit tests (offline) | `python3 scripts/test_ecosystem_tools.py` |
+
+## 1. The ecosystem table — `../docs/program/ecosystem.md`
+
+A single hand/LLM-curated Markdown table: **this file is the source of truth**, and
+its **git history** is the point-in-time record (no timestamped copies). Columns:
+**Project / repo · Type · Evidence · Since · Until · Status · Last activity · Note**.
+
+- **Type** — `package consumer` | `ProtVista-type viewer` | `fork` | `commercial/private` | `unclear`.
+- **Evidence** — the strongest public pointer (repo / paper / live site), or
+  `private — under agreement` where there is no public artifact. The Type says what
+  it is, the Evidence is a checkable link, the Note carries any caveat
+  (`verified: shares git history`, `appears derived; unverified`).
+- **Since / Until** — when the project's ProtVista relationship began and (if it has)
+  ended. Each cell names the *kind* of date because it differs by type: `(dep added)` /
+  `(dep removed)` for package consumers, `(repo created)` or `(paper)` for forks &
+  viewers, `(interest)` for commercial, `(paper)` / `(UI mention)` for unclear. A `—`
+  in *Since* means not yet filled; a `—` in *Until* means ongoing / not applicable.
+
+`protvista_ecosystem.py` automates only the tedious part — finding GitHub package
+consumers. It searches public `package.json` files, **verifies the exact dependency
+key** (so look-alikes like `protvista-uniprot-entry-adapter` are rejected), and:
+
+- **appends** a stub row for any verified repo not already in the table (with
+  *Since* pre-filled from the repo's GitHub `created_at`);
+- **prints** (does not edit) any package-consumer row whose repo no longer appears
+  in the search, so you can fill its *Until*.
+
+You then **review `git diff docs/program/ecosystem.md`**, refine Project / Type /
+dates, and curate. Re-running with no real change makes no diff (dedup is on the
+repo). Forks, viewers, deployments, commercial/private and unclear entries are added
+by hand. `--backfill-dates` fills any blank (`—`) *Since* cell of a github-repo row
+from its `created_at` (handy after seeding rows without dates).
+
+**Consent / no-PII:** never type an unconsented partner name into `ecosystem.md`. A
+commercial row reads `Commercial adopter (<sector>)` until consent is recorded;
+discovery only ever finds public package consumers, never commercial entries.
+
+## 2. npm downloads — `../docs/program/npm_downloads.csv`
+
+`npm_downloads.py` maintains a committed monthly time series for `protvista-uniprot`
+since 2025 (`month,package,downloads`). It is an append-only cache: completed months
+are written once and kept; each run only re-fetches the current month and the
+previous one (to correct a partial→complete month) plus any months missing from the
+file. **Caveat:** npm counts are raw fetch events — inflated by CI/mirror/bot traffic
+and dominated by UniProt's own builds; report them as a baseline trend, never an
+adoption headline (the caveat travels as a comment line in the CSV too).
+
+## 3. Citations — print-only, not saved
+
+`protvista_citation_count.py` prints the count of works citing the foundational
+ProtVista paper (OpenAlex). It writes **nothing** to the repo — citations to a 2017
+paper move too slowly to track per period, so just read off the current number when
+you need it. `--as-of YYYY-MM-DD` for an as-of count, `--list` for the per-work table,
+`--mailto you@example.org` for OpenAlex's faster pool.
+
+## Refreshing the metrics
+
+**Shortcut — run all three at once:** `bash scripts/update_metrics.sh`, then review the
+`ecosystem.md` diff, curate, and commit. Or step by step:
+
+```bash
+# 1. Refresh discovered package consumers, then REVIEW and curate the diff.
+python3 scripts/protvista_ecosystem.py          # (or --dry-run to preview)
+git diff docs/program/ecosystem.md              # fill Project/Type/dates; mark removals
+#    Add any new fork / viewer / deployment / commercial entry by hand.
+
+# 2. Update the npm download series.
+python3 scripts/npm_downloads.py
+
+# 3. Read off the current citation number (writes nothing).
+python3 scripts/protvista_citation_count.py
+
+# 4. Commit the table + CSV.
+git add docs/program/ecosystem.md docs/program/npm_downloads.csv
+git commit -m "metrics: refresh"
+```
+
+Adoption figures move slowly — a stable period is a healthy, maintained baseline, not
+a regression.
+
+## Notes
+
+- Hardcoded to `protvista-uniprot` (renamed to `protvista` in v5; the series will
+  eventually split across both names).
+- Out of scope: consumers of the underlying `@nightingale-elements/*` track
+  components rather than ProtVista itself (e.g. InterPro).
+- The two GA4 page-view scripts live in `protvista/documents/`, not here: they need
+  `pandas` + `google-analytics-data` and a separate project, and query UniProt's
+  private analytics.