MIRACLE API

MIRACLE API#

Public Import#

Use the current explicit module import:

from scmiracle.model import MIRACLE

The top-level shortcut scmiracle.MIRACLE is not exported by the current package initializer.

High-Level Workflow Methods#

class scmiracle.model.MIRACLE(*, batch_key: str = 'batch', configs: dict | None = None, batch_size: int = 128, save_model_path: str = './saved_models/miracle')[source]#

Bases: object

High-level MuData wrapper around MIDAS for continual multimodal learning.

Parameters:

None.

Returns:

None.

static attach_feature_and_label_metadata(mdata: MuData, *, feature_paths_by_mod: Dict[str, Sequence[Path | str]] | None = None, labels: Sequence[str] | None = None, label_key: str = 'label') → MuData[source]#

Attach feature names and optional labels to a MuData object.

Parameters:

  • mdata – Input MuData object to annotate.

  • feature_paths_by_mod – Optional mapping from modality name to one or more CSV files containing feature names.

  • labels – Optional cell labels aligned to observations.

  • label_key – Observation column name used for labels.

Returns:

The same MuData object with updated feature and label metadata.

static attach_replay_metadata(mdata: MuData, metadata: Dict)[source]#

Attach replay-specific metadata under the private MIRACLE namespace.

Parameters:

  • mdata – MuData object to annotate.

  • metadata – Metadata mapping to merge into the replay namespace.

Returns:

The same MuData object with updated replay metadata.

static batch_key_static() → str[source]#

Return the default batch annotation key used by this wrapper.

Parameters:

None.

Returns:

The default batch observation key.

build_replay(replay_size: int = 2000, source_mdata: MuData | None = None, latent: ndarray | None = None, *, strategy: Literal['subsample', 'full'] = 'subsample')[source]#

Build a replay MuData object from the current source data.

Parameters:

  • replay_size – Target number of replay observations to keep.

  • source_mdata – Source MuData used to build replay. Defaults to the current task data bound to the helper.

  • latent – Optional latent representation aligned to source_mdata. Required only to avoid recomputing embeddings for subsampling.

  • strategy – Replay construction strategy. subsample selects a compact subset, while full keeps all observations.

Returns:

A MuData object representing replay memory.

static export_mudata_metadata(mdata: MuData, path: str, *, replay_strategy: str)[source]#

Export compact metadata needed to reconstruct replay context later.

Parameters:

  • mdata – MuData object whose metadata should be exported.

  • path – Output JSON path.

  • replay_strategy – Replay construction strategy label to store.

Returns:

The metadata dictionary that was written to disk.

classmethod get_latent_from_checkpoint(mdata: MuData, model_dir: Path | str, *, kind: str = 'joint', batch_size: int = 128, batch_key: str = 'batch') → ndarray[source]#

Load a checkpoint and immediately compute latent representations.

Parameters:

  • mdata – MuData object to encode.

  • model_dir – Checkpoint directory containing model.pt.

  • kind – Latent representation kind passed through to MIDAS.

  • batch_size – Batch size used for inference.

  • batch_key – Observation column used as the batch identifier.

Returns:

A NumPy array containing latent embeddings.

get_latent_representation(mdata: MuData | None = None, *, kind: str = 'joint')[source]#

Extract latent representations from the active model.

Parameters:

  • mdata – Optional MuData object to encode. When omitted, MIDAS uses the data bound to the active model.

  • kind – Latent representation kind passed through to MIDAS.

Returns:

A NumPy array containing latent embeddings.

static get_obs_series(mdata: MuData, key: str) → Series[source]#

Resolve an observation annotation from top-level or modality-specific columns.

Parameters:

  • mdata – Input MuData object.

  • key – Observation key such as batch or label.

Returns:

A top-level observation series aligned to mdata.obs_names.

classmethod load_model_from_checkpoint_for_mdata(mdata: MuData, model_dir: Path | str, *, batch_size: int = 256, batch_key: str = 'batch')[source]#

Load a checkpoint into a fresh helper bound to a specific MuData object.

Parameters:

  • mdata – MuData object whose feature space should match the checkpoint.

  • model_dir – Checkpoint directory containing model.pt.

  • batch_size – Batch size used for subsequent inference.

  • batch_key – Observation column used as the batch identifier.

Returns:

A MIRACLE helper with a loaded MIDAS model.

classmethod load_mtx_dir_as_mudata(data_dir: Path | str, *, label_path: str | Path | None = None, batch_prefix: str | None = None, batch_key: str = 'batch', label_key: str = 'label') → MuData[source]#

Load an original MIRACLE mtx-format directory and convert it into MuData.

Parameters:

  • data_dir – Dataset directory containing feat/ and subset_* folders in the original MIRACLE input layout.

  • label_path – Optional CSV file containing cell labels indexed by cell name. When provided, labels are attached to each modality and to the top-level mdata.obs.

  • batch_prefix – Optional prefix added to each subset batch name after loading, for example ref or query.

  • batch_key – Observation column used for batch labels.

  • label_key – Observation column used for cell labels.

Returns:

A MuData object ready to be used with MIRACLE.setup_mudata or MIRACLE.setup_continual.

static load_replay(path: str) → MuData[source]#

Load a replay MuData file from disk.

Parameters:

path – Path to a replay .h5mu file.

Returns:

The loaded MuData object.

static load_replay_with_metadata(path: str, meta_path: str | None = None) → MuData[source]#

Load replay data and merge JSON metadata when available.

Parameters:

  • path – Path to a replay .h5mu file.

  • meta_path – Optional JSON metadata path. Defaults to the same stem as path with a .json suffix.

Returns:

The loaded MuData object with replay metadata attached when found.

static prefix_batch_and_obs_names(mdata: MuData, *, batch_key: str = 'batch', batch_prefix: str | None = None, obs_prefix: str | None = None, label_key: str = 'label') → MuData[source]#

Prefix batch labels and observation names while preserving top-level metadata.

Parameters:

  • mdata – Input MuData object.

  • batch_key – Observation column containing batch labels.

  • batch_prefix – Optional prefix added to each batch label.

  • obs_prefix – Optional prefix added to each observation name.

  • label_key – Observation column containing labels.

Returns:

A copied MuData object with prefixed identifiers.

static read_named_csv_column(path: Path | str, column: str = 'x') → List[str][source]#

Read a named column from a CSV file, with a fallback to the last column.

Parameters:

  • path – CSV file path.

  • column – Preferred column name to read.

Returns:

A list of string values from the requested column.

save(dir_path: str | None = None, overwrite: bool = True)[source]#

Save the current model checkpoint and remember the output directory.

Parameters:

  • dir_path – Optional output directory. Uses save_model_path when omitted.

  • overwrite – Whether to overwrite an existing checkpoint directory.

Returns:

The directory path used for saving.

setup_continual(current_mdata: MuData, *, replay_mdata: MuData, prev_model_dir: str, save_model_path: str | None = None, inherit_dsc: bool = True, lazy: bool = True)[source]#

Prepare a continual model from replay data, current data, and a previous checkpoint.

Parameters:

  • current_mdata – MuData for the current continual-learning step.

  • replay_mdata – Replay MuData sampled from previous steps.

  • prev_model_dir – Directory containing the previous step checkpoint.

  • save_model_path – Optional checkpoint directory overriding the instance default.

  • inherit_dsc – Whether to initialize the discriminator from the previous checkpoint when compatible weights are available.

  • lazy – Build batch datasets directly from replay/current matrices without materializing a merged expression matrix. Defaults to True. Set to False for the legacy eager behavior.

Returns:

The current MIRACLE instance.

setup_mudata(mdata: MuData, *, save_model_path: str | None = None)[source]#

Prepare a step-1 MIDAS model from a single MuData object.

Parameters:

  • mdata – Current-task MuData used for the first training step.

  • save_model_path – Optional checkpoint directory overriding the instance default.

Returns:

The current MIRACLE instance.

train(**kwargs)[source]#

Train the currently configured MIDAS model.

Parameters:

**kwargs – Keyword arguments forwarded to MIDAS.train.

Returns:

The current MIRACLE instance.

Continual Sampling#

class scmiracle.model.ReplayCurrentAlternatingSampler(dataset: ConcatDataset, replay_dataset_count: int, batch_size: int)[source]#

Bases: Sampler

Alternate replay and current-task batches from a concatenated dataset.

Parameters:

None.

Returns:

None.

__iter__()[source]#

Yield indices that alternate between current and replay subsets.

Parameters:

None.

Returns:

An iterator of dataset indices for one sampling epoch.

__len__()[source]#

Return the number of sampled indices produced in one epoch.

Parameters:

None.

Returns:

The total number of sample indices generated per epoch.

Dataset Download Utilities#

scmiracle.download_data.download(data, data_path)[source]#

Downloads and extracts a specified dataset to the given data_path. Includes a progress bar for downloads.

Parameters:

  • data (str) – The dataset name, e.g. ‘DOTEA_mudata’.

  • data_path (str) – The base directory where the data should be stored.

scmiracle.download_data.list_available_datasets()[source]#

Displays a list of all datasets that can be downloaded.