Skip to content

Cellestial 0.60.0 (first-class MuData support)

Latest
Latest

Choose a tag to compare

View all tags
@Zaf4 Zaf4 released this 06 Aug 11:08
v0.60.0
3d6e1bf

What's changed

Cellestial now speaks multimodal. MuData containers are a first-class input
across the library: pass one straight to a plot, color by a feature from any
modality, and plot joint embeddings such as WNN or MOFA without unpacking the
object yourself.

import cellestial as cl

data = cl.datasets.pbmc_cite()

# a protein on the joint WNN embedding
cl.dimensional(data, dimensions="wnn_umap", key="prot:CD3_TotalSeqB")

# a bare gene name, resolved to the modality that owns it
cl.violin(data, key="MS4A1", fill="leiden")

# genes and proteins on one axis, grouped by a joint clustering
cl.dotplot(data, keys=["MS4A1", "prot:CD3_TotalSeqB"], group_by="leiden")

Added

  • Multimodal (MuData) support. Frames and the dimensional, distribution,
    scatter and heatmap plot families accept a multimodal container directly,
    reading metadata and embeddings at the container level.
    • Variables resolve to the modality that owns them. A bare name works when it
      is unique across modalities, and modality:name disambiguates otherwise,
      raising AmbiguousVariableError rather than silently picking one.
    • Observations absent from a modality surface as NaN, aligned through the
      container's observation map.
  • A modality parameter on markers, marker_genes, marker_genes_dict,
    volcano, volcanos, elbow, highest_expressed_genes, heatmap,
    dotplot, stacked_violin and annotated_heatmap, selecting which modality's
    stored analysis results to use. Required for a multimodal object holding more
    than one modality, and not accepted otherwise.
  • cellestial.datasets.pbmc_cite(), a small CITE-seq multimodal dataset, and an
    extension parameter on from_url so it can serve .h5mu files.
  • AmbiguousVariableError.

Fixed

  • A variable name matching more than one column is rejected instead of producing
    wrong values. Slicing on a duplicated name yielded an interleaving of the
    matching columns for multimodal inputs, and an opaque pandas
    InvalidIndexError for AnnData; both now raise AmbiguousVariableError.
  • A key stored on both axes no longer silently selects the wrong one. Metrics
    such as total_counts are written per observation and per variable, and the
    variables axis always won, so violin(data, key="total_counts", fill="leiden")
    built a variables frame that could not contain the grouping column. The
    grouping and aesthetic keys of the same call now break the tie. Affects AnnData
    as well as multimodal inputs.
  • group_by is validated before use, so an unknown value raises
    KeyNotFoundError instead of a raw polars ColumnNotFoundError naming the
    narrowed frame. When the name exists on a modality, the error suggests the
    qualified form (rna:celltype). Affects AnnData as well as multimodal inputs.
  • Type annotations admit multimodal inputs. Every plotting function that accepts
    one at runtime was still annotated AnnData, so type checkers rejected valid
    calls.
  • dimensions widened from Literal["umap", "pca", "tsne"] to also accept any
    other embedding name. Non-standard names always worked at runtime, and joint
    embeddings such as wnn_umap make the narrow annotation untenable.
  • Variable names containing colons resolve. A qualified modality:name key is
    still tried first, but a key that does not match that reading is now matched
    literally, so ATAC peak names (chr1:1000-2000) and datasets storing variable
    names already prefixed (rna:SAMD11) work. Previously every variable in such a
    dataset was unreachable.
  • Embeddings stored as a DataFrame rather than an array no longer fail with
    InvalidIndexError when materialised into a frame. Affects AnnData as well as
    multimodal inputs.
  • Marker-derived plots (heatmap, dotplot, stacked_violin) read the group
    column a stored ranking was computed on as the container names it. A ranking
    records that column under the modality's own name, so a container carrying both
    a global leiden and a modality's rna:leiden previously grouped the ranked
    genes by the wrong clustering. Passing the container name explicitly as
    group_by is accepted too.

Notes

  • Spatial plots do not accept a multimodal object, because spot coordinates and
    tissue images live in a modality rather than on the container. The error names
    the single-modality form, and the composition that colours spots by a variable
    from another modality:
    spatial(data['rna'], key='prot:CD3', frame=build_frame(data, variable_keys=['prot:CD3'])).
  • Only containers whose modalities share observations (axis=0) are supported.

No breaking changes.

Install: pip install -U cellestial

Full changelog: v0.59.0...v0.60.0

Assets 2
Loading