Return a dataset-specific result object from `set_input_anndata`

[thonzyk]

Return a dataset-specific result object from set_input_anndata

Problem

Currently, scUnveil stores both the loaded model and the state associated with the most recently processed AnnData.

Calling:

sc_unveil.set_input_anndata(adata)

mutates the sc_unveil instance and stores dataset-specific values on it, including:

• input_anndata
• _input_obs
• var_map_matrix
• raw_embeddings
• pca_embeddings
• gene_mapping_summary

Calling set_input_anndata() again replaces this state. Therefore, users cannot retain multiple processed datasets while sharing a single loaded scUNVEIL model.

Proposed API

Make set_input_anndata() return a dataset-specific result object:

sc_unveil = scUnveil()

result_a = sc_unveil.set_input_anndata(adata_a, batch_size=1_000)
result_b = sc_unveil.set_input_anndata(adata_b, batch_size=1_000)

embeddings_a = result_a.get_embeddings(n_features=512)
embeddings_b = result_b.get_embeddings(n_features=512)

The scUnveil instance should own reusable model-level resources, such as:

• The loaded checkpoint and TensorFlow models
• The reference gene vocabulary
• The PCA projection
• Other model configuration and metadata

Each result object should own the state associated with one processed dataset:

• The input AnnData, or a documented reference to it
• Copied observation metadata
• The variable mapping matrix
• Raw embeddings
• PCA-projected embeddings
• The gene mapping summary

The result object should retain a reference to its originating scUnveil instance. This would allow dataset-dependent operations to reuse the decoder and model metadata without copying or loading the model again.

For example:

result = sc_unveil.set_input_anndata(adata, batch_size=1_000)

result.input_anndata
result.gene_mapping_summary

result.get_raw_embeddings()
result.get_embeddings(n_features=512)
result.get_all_genes_imputation(batch_size=1_000)
result.get_specific_genes_imputation(["CD4", "CD8A"])
result.get_fully_enriched_h5ad()

Model-only operations could remain on scUnveil:

sc_unveil.get_genes_embeddings()
sc_unveil.generate_cells(...)

Motivation

This separation would:

• Allow multiple processed datasets to coexist
• Avoid silently overwriting earlier results
• Reuse the relatively expensive loaded model
• Clarify ownership of dataset-specific state
• Reduce mutable state on the central model object
• Make interactive and multi-dataset workflows easier to reason about

Expected behavior

sc_unveil = scUnveil()

pbmc_result = sc_unveil.set_input_anndata(pbmc_adata)
tumor_result = sc_unveil.set_input_anndata(tumor_adata)

# Both results remain usable and share the same model.
pbmc_embeddings = pbmc_result.get_embeddings()
tumor_embeddings = tumor_result.get_embeddings()

assert pbmc_result.sc_unveil is sc_unveil
assert tumor_result.sc_unveil is sc_unveil

Processing should remain transactional: if validation or inference fails, no partially initialized result should be returned, and existing result objects should remain unaffected.

Acceptance criteria

• set_input_anndata() returns a documented result type.
• Multiple result objects created from one scUnveil instance can coexist.
• Creating a new result does not modify or invalidate earlier results.
• Dataset-dependent retrieval and imputation methods operate on the corresponding result.
• The underlying TensorFlow model and checkpoint data are shared rather than copied.
• The processed input data and gene-mapping summary can be retrieved from the result.
• Tests cover two different inputs processed by the same model and queried independently.
• The README and examples demonstrate the returned result object.
• A backward-compatibility or deprecation strategy is documented if the existing stateful API is removed.