scglue Documentation

A GLUE model is a modular PyTorch-based framework composed of four primary components. When extending the framework, you will likely interact with these abstractions:

• Data Encoders: Receive data input $x$ and return a distribution corresponding to the data posterior (cell embeddings) $q(u|x)$. There is typically one encoder per domain.
• Data Decoders: Receive cell embedding input $u$ and feature embedding input $v$, and return a distribution corresponding to the data likelihood $p(x|u, v)$. There is typically one decoder per domain.
• Graph Encoder: Receives graph input $\mathcal{G}$ (edge index, edge weight, and edge sign) and returns a distribution corresponding to the graph posterior (feature embeddings) $q(v|\mathcal{G})$.
• Graph Decoder: Receives feature embedding input $v$ and a subset of query edges (edge index and edge sign), returning a distribution corresponding to the likelihood of these query edges $p(\mathcal{G}|v)$.

Existing implementations are located in scglue.models.sc.

To implement a custom decoder, inherit from the DataDecoder class.

Constructor Requirements: Your __init__ should accept out_features (output dimensionality) and n_batches (number of batches to account for batch effects).

The forward method: You must implement the forward method, which accepts the following four arguments:

• u: Cell embeddings
• v: Feature embeddings
• b: Batch index
• l: Library size (computed by the encoder)

The method must return a likelihood distribution (e.g., a distribution object from scglue.models.prob).

Example of a Negative Binomial decoder using batch-specific trainable parameters:

class NBDataDecoder(DataDecoder):

    def __init__(self, out_features: int, n_batches: int = 1) -> None:
        super().__init__(out_features, n_batches=n_batches)
        self.scale_lin = torch.nn.Parameter(torch.zeros(n_batches, out_features))
        self.bias = torch.nn.Parameter(torch.zeros(n_batches, out_features))
        self.log_theta = torch.nn.Parameter(torch.zeros(n_batches, out_features))

    def forward(
            self, u: torch.Tensor, v: torch.Tensor,
            b: torch.Tensor, l: torch.Tensor
    ) -> D.NegativeBinomial:
        scale = F.softplus(self.scale_lin[b])
        logit_mu = scale * (u @ v.t()) + self.bias[b]
        mu = F.softmax(logit_mu, dim=1) * l
        log_theta = self.log_theta[b]
        return D.NegativeBinomial(
            log_theta.exp(),
            logits=(mu + EPS).log() - log_theta
        )

To support new data modalities, you can define a custom encoder by inheriting from the DataEncoder class. The base class provides an MLP implementation, but you must implement two abstract methods:

1. compute_l(self, x: torch.Tensor) -> torch.Tensor: Computes the library size from the input data.
2. normalize(self, x: torch.Tensor, l: torch.Tensor) -> torch.Tensor: Normalizes the input data (potentially using the computed library size $l$) before it is passed to the MLP.

Example of a Negative Binomial (NB) encoder that performs row normalization to a constant size and applies a log-transform:

class NBDataEncoder(DataEncoder):

    TOTAL_COUNT = 1e4

    def compute_l(self, x: torch.Tensor) -> torch.Tensor:
        return x.sum(dim=1, keepdim=True)

    def normalize(
            self, x: torch.Tensor, l: torch.Tensor
    ) -> torch.Tensor:
        return (x * (self.TOTAL_COUNT / l)).log1p()

Data preparation for GLUE involves two main steps: downloading/preprocessing raw resource directories and formatting single-cell data into h5ad files.

1. Download and Preprocess Resources

Several directories require manual data acquisition and preprocessing. For each of the following directories, you must download the files specified in their respective README files and then execute the preprocess.sh script located within that directory:

• genome
• conservation
• download/ (includes datasets like 10x-ATAC-Brain5k, 10x-Multiome-Pbmc10k, Cao-2020, Chen-2019, Domcke-2020, Luo-2017, Ma-2020, Saunders-2018)
• eqtl/GTEx-v8
• hic/Javierre-2016
• chip/ENCODE/TF-human
• database/TRRUST-v2

2. Format Single-Cell Data

Once the resources are preprocessed, use snakemake to collect the single-cell data into a unified h5ad format. This will generate a dataset directory containing *.h5ad files.

snakemake -j4 -prk