Skip to content

AnnZarro 0.4.0

Choose a tag to compare

@github-actions github-actions released this 06 Oct 07:05
· 804 commits to main since this release
49e2a19

Gene Set Analysis panel

A new panel follows a Gene Table: the genes passing its filter, plus the focused gene. It asks external services about them (functional enrichment, the protein network, gene lookups) and links to the resources that describe each gene. Each service is its own section and fails on its own. Nothing is sent until you press Run (or auto-update is on and consent already covers the services); opening a link, panel set or session sends nothing by itself. Links are built in the browser and work offline and in the desktop app. User guide: https://annzarro.readthedocs.io/en/latest/user-guide/gene-set.html

  • Services: STRING 12.5 (pinned to a versioned host: enrichment, network image with PPI enrichment, partners of the focused gene), g:Profiler g:GOSt and MyGene.info are on by default. Enrichr, Reactome and the Human Protein Atlas are off until turned on; Enrichr and Reactome warn that they keep the lists they are sent. The enrichment background defaults to the dataset's own genes, with the whole genome as an option.
  • Coverage: every section says how many genes the service knew and lists every gene it did not, with Copy. A section whose service knows none of the genes says so and names the species it asked for, and suggests the species the dataset's ids point to. STRING's FDR is labelled "within category" (g:Profiler's "within source"), with a note when categories are shown together; nothing is recomputed in the browser.
  • Consent: decided in the browser, within the server's policy (integrations.external_requests: ask, default; on; off). Order: server off, server on, the user's stored "Never", a share link's consent for exactly its gene selection, the user's "Send"/"Always", else ask. Enrichr and Reactome are asked every time. Requests carry no cookies and no referrer; gene lists travel in request bodies.
  • Species: picked in the panel, set by a link, or inferred: from an uns entry (taxonomy_id, taxid, species, organism) or the id prefixes (ENSG, ENSMUSG, ENSRNOG, ENSDARG, FBgn, WBGene and more), shown as "Auto: Mus musculus (from Ensembl IDs)".
  • Gene identifiers: Auto finds the id column (gene_id, Ensembl and model-organism id columns such as wbgene, gene_name, gene_symbol) and reads the values as symbols, Ensembl or Entrez ids; both choices are saved with the panel.
  • Links: 26 species-gated resources for the focused gene (NCBI Gene, Ensembl, UniProt, STRING, GeneCards, HPA, GTEx, Open Targets, OMIM, ClinVar, KEGG, Reactome, the model-organism databases, PubMed, ...); set links for the whole selection, a paged list with one link per resource, CSV export and Copy ids.
  • Limits: a list over a service's limit (STRING network 2,000; enrichments 3,000; gene lookup 5,000) is not sent and never cut down; the section shows the limit and a "Try anyway" button.
  • Config: new integrations.external_requests (and the ANNZARRO_EXTERNAL_REQUESTS environment variable), integrations.gene_set.services, integrations.gene_set.timeout_ms (20000). integrations.string_db.base_url is now https://version-12-5.string-db.org/api and integrations.string_db.version "12.5". ui.enabled_panel_types includes gene-set.

Fixes

  • Log colour scales: Min/Max under Log are taken as data values (links from v0.3 open unchanged), and the colour bar gets 1-2-5 ticks, also inside a single decade.
  • Colour bar: titled with a readable label instead of the raw key, and each sequential colour map says which way it runs.
  • Recolouring: a remote recolour shows busy until the new colours are drawn, and clears at that draw.
  • Counts: "1 gene", not "1 genes", in coverage lines and counts.
  • Refreshing a changed dataset:
    • Every user can refresh a changed dataset (POST /api/v1/data/refresh), in every worker. Cache reset stays admin-only.
    • Each dataset has a generation, shared by the ETag and the result cache. A cache reset or refresh moves it, and a server restart starts a new one, so a restart can no longer answer 304 with old data.
    • The browser drops its cached replies for the dataset, and a panel's Refresh reloads its data, as documented.
    • The h5ad reader's cache is cleared on reset too, and with zarr 2 a store's root metadata is now cleared with its dataset (it could be served stale after a change).
    • A store whose consolidated metadata is out of date is read past it, with a notice. The finding survives a following cache reset.
    • Refresh is bounded: one walk per dataset at a time, at most every 10 s (refresh_min_interval_s), 3 s per walk ("partial" for huge stores). A request is never answered with a walk older than itself.
  • Faster first plot: the Map colour swatch is resolved only when it is on screen. This saves an off-screen draw at panel setup, about 0.09 s on a 1M-cell plot.

HTTP API and link changes

  • New: POST /api/v1/data/refresh?dataset_path=..., open to every user who may read the dataset (401 anonymous, 403 outside the data directory, 400 without dataset_path, 404 not found). It walks the store's files (3 s budget) and moves the dataset's generation only if they changed; within server.refresh_min_interval_s (default 10 s) it waits for the shared walk. Reply: {result, status: "full"|"partial"|"remote", changed, checked, waited_s, shared?, message?, consolidated_metadata}; partial does not move the generation.
  • Changed: POST /api/v1/cache/reset (still admin-only when hosted) also clears the h5ad reader and moves the generation, so every worker drops the dataset's cached reads.
  • Changed: an ETag now includes a freshness token (file fingerprint, per-dataset generation, global generation, shared by every process on the host under $ANNZARRO_HOME/freshness). Tags change after a reset, after a refresh that found a change, and for every dataset at server start. The server's result cache uses the same token.
  • Changed: a 404 key_not_found or 500 stale_metadata caused by out-of-date consolidated metadata becomes 200 after a refresh (the store is then read without its consolidated metadata, with a notice); the stale_metadata message text changed. New field dataset_structure.consolidated_metadata.
  • Links and panel sets: plot configs carry colorRangeUnits: "data", and colorMin/colorMax are data values also under Log. Configs without the marker and with color.log: true are read as log10 bounds, as v0.3 wrote them, so old links open unchanged.

Documentation

  • The paper pages are named by topic (old figN addresses redirect). New pages cover the scale figure (Tahoe-100M deep links) and the procedure figure. There is a connectome view in the cell-by-cell page.
  • The bone-marrow demo store, its showcase fields and the C. elegans connectome store now build from public scripts in docs/_tools/datasets/.

Full changes: v0.3.1...v0.4.0

Desktop apps

Desktop apps for Windows, macOS and Linux. The builds are not signed with a developer identity (the macOS app is ad-hoc signed, not notarized), so the first launch needs one extra step. macOS 15 and 26: macOS says "AnnZarro" Not Opened; click Done, then System Settings > Privacy & Security > Security > Open Anyway, and confirm (once). macOS 14 and earlier: right-click the app > Open. Windows: More info > Run anyway. Details: https://annzarro.readthedocs.io/en/latest/getting-started/desktop-app.html (First launch). Verify downloads against SHA256SUMS.txt.