Auto-discover AnnData fields and support validated gsMap trait queries

[Ganten-Hornby]

Summary

• Share AnnData field discovery between CLI and notebook APIs: spatialvista --input data.h5ad and spatialvista.vis(adata) work without listing common coordinate/annotation keys.
• Add validated uns["gsmap"] metadata and a searchable Query Traits interface with trait labels and −log10(P) units, separate from ordinary Query Continuous fields.
• Handle missing annotations, missing numeric values, constant scores and late-arriving notebook data; retain annotation filters in continuous/trait views.
• Document AnnData conventions, overrides and gsMap report exports. Include rebuilt standalone and notebook bundles.

Data convention

Precedence: explicit CLI/Python options → validated gsMap metadata → ordinary AnnData inference.

Content	Convention
Coordinates	Recognized obsm keys, starting with spatial; finite real (n_obs, 2 or 3) arrays. UMAP is not silently used as tissue coordinates.
Annotations	Categorical/boolean obs fields, or string fields with limited cardinality. Numeric category codes should be categorical or explicitly selected.
Continuous fields	Real numeric obs fields with at least one finite value, excluding selected annotation/color/section fields.
Sections	Recognized section keys, including section, slice_id, and sample_name.
gsMap traits	Numeric columns explicitly mapped in uns["gsmap"]["traits"]; no prefix guessing.

adata.uns["gsmap"] = {
    "schema_version": 1,
    "value_scale": "neg_log10_p",
    "spatial_key": "spatial",
    "section_key": "sample_name",  # optional
    "annotation_keys": ["celltype", "region"],
    "default_annotation": "celltype",
    "traits": {
        "gsMap_logp_IQ": "IQ",
        "gsMap_logp_AF": "Atrial fibrillation",
    },
}

All declared columns must exist and follow the same observation order. gsMap coordinates must be finite (n_obs, 3); observation IDs must be unique and nonempty. Traits must be real, nonnegative already-transformed −log10(P) with at least one finite value per trait. NaNs remain missing/transparent, not zero. Invalid declarations, infinities and declared raw-P scales are rejected. Exporters remain responsible for the correct scale: numerical validation cannot detect mislabeled raw P values.

No expression matrix or gsMap dependency is required. This changes the package's CLI/notebook viewer, not the separately deployed SpatialVista portal.

Behavior changes and controls

• Omitted annotation/continuous/section options now discover fields automatically.
• --continuous "" / continuous=[] disables numeric discovery; --annotations "" / annotations=[] disables extra annotations; --section "" / section="" disables section discovery.
• Explicit options override defaults. Malformed gsMap metadata remains an error unless deliberately ignored with --ignore-gsmap-metadata / ignore_gsmap_metadata=True.
• Without annotations, display an “All cells” category without modifying the input AnnData.
• Expression export remains opt-in via --genes / genes=.
• Exporting all result spots to H5AD does not guarantee interactive browser performance for millions of points.

Validation

• python -m pytest -q tests: 34 passed.
• Bundled frontend/tests/gsmap_colors.test.ts: 4 checks passed (NaN, maximum, constant, annotation colors).
• Production Vite builds passed for widget and standalone targets. Fresh bundle SHA-256 hashes exactly match committed assets. The loaders.gl browser-external spawn warning remains.
• python -m mkdocs build --strict: passed.
• Real E11.5 export: 6,609,635 spots across 84 sections, IQ/AF/LDL traits, spatial-domain/manual annotations. All rows were compared against the source report (IDs, coordinates, sections, labels and float32 scores). The full H5AD passed SpatialVista auto-discovery/validation. This is a data-contract test, not a full-size browser-rendering benchmark.

The two generated src/spatialvista/_widget/*.mjs files account for most diff volume; source changes can be reviewed separately.