loupepy 0.1.0

A python package for generating 10x cloupe files from anndata objects

from loupepy import get_count_matrixWhile this tool is independently maintained and not officially supported by 10x Genomics, it relies on code from LoupeR, an R package developed by 10x Genomics. LoupeR is licensed for use only in connection with data generated from 10x Genomics products. For more information, please refer to the 10x End User Software License. By using the setup function of this tool, you will need to agree to this license with an interactive prompt.

Main Functions

create_loupe_from_anndata(anndata, output_cloupe="cloupe.cloupe", layer=None, ...)

Creates a Loupe Browser compatible .cloupe file from an AnnData object.

Parameters:

• anndata: AnnData object containing single-cell data
• output_cloupe: Path to save the output file (default: "cloupe.cloupe")
• layer: Layer in AnnData to use for counts (default: None, uses .X)
• dims: List of dimension reduction keys from adata.obsm (default: None, uses all valid projections)
• obs_keys: List of categorical annotations from adata.obs to include (default: None, uses all valid categories)
• strict_checking: Whether to strictly validate inputs (default: False)
• tmp_file: Temporary file path for intermediate data (default: 'tmp.h5')
• dims: List of dimension reduction keys from adata.obsm to include (default: None, uses all valid projections)
• obs_keys: List of categorical annotations from adata.obs to include (default: None, uses all valid categories)
• loupe_converter_path: Path to the Loupe converter binary (default: None, uses default installation path)
• clean_tmp_file: Whether to delete the temporary file after creation (default: True)
• force: Whether to overwrite existing cloupe file (default: False)
• test_mode: Whether to run in test mode. Will not create a cloupe file.

Example:

import scanpy as sc
import loupepy
from scipy.sparse import diags

# Load data
adata = sc.datasets.pbmc3k_processed().raw.to_adata()
# Revert to raw counts, as loupee converter only takes raw counts
n_counts = adata.obs["n_counts"].values
counts_matrix = adata.X.expm1()
counts = diags(n_counts) * counts_matrix
adata.X = counts

# Create Loupe file with default settings
loupepy.create_loupe_from_anndata(adata, "my_results.cloupe")

# Create with specific dimensions and annotations
loupepy.create_loupe_from_anndata(
    adata,
    "my_custom_results.cloupe",
    dims=["X_umap"],
    obs_keys=["leiden"]
)

Utility Functions

get_obs(anndata, obs_keys=None, strict=False)

Extracts categorical observation data from an AnnData object.

Parameters:

• anndata: AnnData object containing the data
• obs_keys: List of keys to extract from adata.obs (default: None, uses all valid categories)
• strict: Whether to strictly validate the keys. If true will throw errors on invalid keys instead of dropping (default: False)

get_obsm(anndata, obsm_keys=None, strict=False)

Extracts dimensional reduction data from an AnnData object. Parameters:

• anndata: AnnData object containing the data
• obsm_keys: List of keys to extract from adata.obsm (default: None, uses all valid dimension reductions)
• strict: Whether to strictly validate the keys. If true will throw errors on invalid keys instead of dropping (default: False)

get_count_matrix(anndata, layer=None)

Gets the count matrix from an AnnData object in the format required for Loupe.

Parameters:

• anndata: AnnData object containing the data
• layer: Layer in AnnData to use for counts (default: None, uses .X)

---

create_loupe(mat, obs, var, obsm, tmp_file, ...)

Lower-level function to create a Loupe file from raw data components.

Parameters:

• mat: CSC matrix of counts (shape: n_features × n_cells)
• obs: DataFrame of categorical cell annotations
• var: DataFrame of gene/feature information
• obsm: Dictionary of dimension reduction embeddings
• tmp_file: Path for temporary file
• output_path: Path to save the output file
• strict_checking: Whether to strictly validate inputs (default: False)
• loupe_converter_path: Path to the Loupe converter binary (default: None, uses default installation path)'
• clean_tmp_file: Whether to delete the temporary file after creation (default: True)
• force: Whether to overwrite existing cloupe file (default: False)
• test_mode: Whether to run in test mode. Will not create a cloupe file.

Example:

import scanpy as sc
import loupepy
from scipy.sparse import diags

# Load data
adata = sc.datasets.pbmc3k_processed().raw.to_adata()
# Revert to raw counts, as loupee converter only takes raw counts
n_counts = adata.obs["n_counts"].values
counts_matrix = adata.X.expm1()
counts = diags(n_counts) * counts_matrix
adata.X = counts

mat = loupepy.get_count_matrix(adata)
obs = loupepy.get_obs(adata, obs_keys=["leiden"])
var = adata.var
obsm = loupepy.get_obsm(adata, obsm_keys=["X_umap"])
loupepy.create_loupe(mat,obs,var,obsm,"my_results.cloupe")

Setup Functions

setup(path=None)

Downloads and installs the Loupe converter binary.

Parameters:

• path: Installation directory path (default: None, uses OS-specific default location)

Example:

import loupepy

# Install the Loupe converter to the default location
loupepy.setup()

eula(path=None)

Parameters:

• path: Installation path (default: None, uses OS-specific default install location. Usually same path as setup)

eula_reset(path=None)

Resets the EULA agreement and removes the installed Loupe converter binary.