Python API

The Python API is organized into preprocessing, deconvolution, model, statistical and visualization components.

The main workflow is:

1. Load annotated single-cell data and bulk expression data.
2. Create reference profiles and simulated training bulks.
3. Train the HIDE model.
4. Apply domain-transfer and library-size corrections where required.
5. Predict cell-type proportions.
6. Analyze and visualize the resulting compositions.

Public API

The package-level convenience function is:

hide_deconv.deconvolution(adata, bulk, celltype_cols=None, n_genes=5000, n_train_bulks=10000, n_cells_per_bulk=100, n_iter=1000, domain_transfer=True, library_size_correction=True, seed=42)

Run preprocessing, training and deconvolution in one call.

Parameters:

Name	Type	Description	Default
adata	AnnData	Annotated single-cell input data.	required
bulk	DataFrame	Bulk expression with genes as rows and samples as columns.	required
celltype_cols	list[str]	Cell type annotation columns in adata.obs. The first column is treated as the finest cell type layer. If no columns are specified, column cell_type is used.	None
n_genes	int	Number of genes used for training and deconvolution.	5000
n_train_bulks	int	Number of training bulks generated for training.	10000
n_cells_per_bulk	int	Number of cells sampled per training bulk.	100
n_iter	int	Number of training iterations.	1000
domain_transfer	bool	Correct for domain transfer between Single Cell and Bulk data.	True
library_size_correction	bool	Correct for library size differences between Single Cell and Bulk data.	True
seed	int	Random seed for the simulated training bulks.	42

Returns:

Type	Description
list[DataFrame]	List of estimated composition, same order as the celltype_cols list.

Source code in src/hide_deconv/pipelines/lazy_deconvolution_pipeline.py

def deconvolution(
    adata: ad.AnnData,
    bulk: pd.DataFrame,
    celltype_cols: list[str] | tuple[str, ...] | str | None = None,
    n_genes: int = 5000,
    n_train_bulks: int = 10000,
    n_cells_per_bulk: int = 100,
    n_iter: int = 1000,
    domain_transfer: bool = True,
    library_size_correction: bool = True,
    seed: int = 42,
) -> list[pd.DataFrame]:
    """
    Run preprocessing, training and deconvolution in one call.

    Parameters
    ----------
    adata : anndata.AnnData
        Annotated single-cell input data.
    bulk : pd.DataFrame
        Bulk expression with genes as rows and samples as columns.
    celltype_cols : list[str], default=None
        Cell type annotation columns in adata.obs. The first column is treated as
        the finest cell type layer. If no columns are specified, column cell_type is used.
    n_genes : int, default=5000
        Number of genes used for training and deconvolution.
    n_train_bulks : int, default=10000
        Number of training bulks generated for training.
    n_cells_per_bulk : int, default=100
        Number of cells sampled per training bulk.
    n_iter : int, default=1000
        Number of training iterations.
    domain_transfer : bool, default=True
        Correct for domain transfer between Single Cell and Bulk data.
    library_size_correction: bool, default = True
        Correct for library size differences between Single Cell and Bulk data.
    seed : int, default=42
        Random seed for the simulated training bulks.

    Returns
    -------
    list[pd.DataFrame]
        List of estimated composition, same order as the celltype_cols list.
    """

    celltype_cols = normalize_celltype_cols(celltype_cols)
    validate_required_columns(adata, celltype_cols)

    bulk = normalize_bulk_to_cpm(bulk)
    adata.obs["library_size"] = np.asarray(adata.X.sum(axis=1)).ravel()
    library_sizes = (
        adata.obs.groupby(celltype_cols[0])["library_size"]
        .median()
        .rename("Median_Library_Size")
    )
    common_genes = get_common_genes(adata, bulk)
    if len(common_genes) == 0:
        raise ValueError("No shared genes found between adata and bulk.")

    adata = adata[:, common_genes].copy()

    model, adata, library_sizes = setup_model(
        adata,
        celltype_cols,
        n_genes,
        n_train_bulks,
        n_cells_per_bulk,
        n_iter,
        seed,
        library_sizes=library_sizes,
    )

    bulk = bulk.loc[model.gene_labels]

    if not library_size_correction:
        library_sizes = None

    predictions, _ = predict_deconvolution_results(
        model,
        adata,
        bulk,
        celltype_cols[0],
        n_cells_per_bulk,
        domain_transfer=domain_transfer,
        library_size_correction=library_sizes,
    )

    return predictions

The lower-level API is grouped by responsibility:

• Preprocessing
• Deconvolution
• Models
• Statistics
• Visualization