Built-in models

What it is

Status: stable.

This page documents the bundled scDLKit model inventory and the registry used by TaskRunner and create_model(...).

When to use it

Use this page when:

• you want to know which built-in models are available

• you need constructor parameters for a bundled baseline

• you want to check which task a model is intended to support

Most users should still start with TaskRunner or the notebook tutorials rather than constructing models manually.

Minimal example

from scdlkit import create_model

model = create_model(
    "vae",
    input_dim=2000,
    latent_dim=32,
    hidden_dims=(512, 256),
    kl_weight=1e-3,
)

Parameters

• autoencoder, vae, denoising_autoencoder, and transformer_ae are the bundled representation and reconstruction baselines.

• mlp_classifier is the bundled supervised classification baseline.

• constructor parameters vary by model family and are documented below through autodoc.

Input expectations

• bundled models expect feature matrices with cells on the batch dimension and genes/features on the last dimension.

• mlp_classifier expects encoded class labels during training.

• most users should let TaskRunner or prepare_data(...) handle preprocessing and split construction.

Returns / outputs

• encoder-style models expose latent outputs for representation workflows.

• reconstruction-capable models expose reconstructed expression outputs.

• classification models expose logits.

• create_model(...) returns an instantiated bundled model ready for TaskRunner or Trainer.

Failure modes / raises

• create_model(...) raises when the requested model name is unknown or required constructor arguments are missing.

• task mismatches raise when a model is used with an unsupported task.

Notes / caveats

• TaskRunner is the recommended stable path for bundled models.

• the tutorial suite is the best place to see these models in realistic single-cell workflows.

• the experimental scGPT path is intentionally documented elsewhere under Experimental foundation helpers.

Related tutorial(s)

• Scanpy PBMC quickstart

• PBMC model comparison

• PBMC classification

Model registry helpers.

scdlkit.models.registry.create_model(name, **kwargs)

Instantiate a registered model by name.

Return type:

BaseModel

Parameters:

• name (str)

• kwargs (object)

scdlkit.models.registry.register_model(name, *aliases)

Register a model factory under one or more names.

Return type:

Callable[[Callable[..., BaseModel]], Callable[..., BaseModel]]

Parameters:

• name (str)

• aliases (str)

MLP autoencoder baseline.

class scdlkit.models.autoencoder.AutoEncoder(input_dim, latent_dim=32, hidden_dims=(512, 256), dropout=0.1)

Bases: BaseModel

Simple MLP autoencoder.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• input_dim (int)

• latent_dim (int)

• hidden_dims (tuple[int, ...])

• dropout (float)

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

dict[str, Tensor]

Parameters:

x (Tensor)

Variational autoencoder baseline.

class scdlkit.models.vae.VariationalAutoEncoder(input_dim, latent_dim=32, hidden_dims=(512, 256), dropout=0.1, kl_weight=1.0)

Bases: BaseModel

Variational autoencoder with an MLP encoder/decoder.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• input_dim (int)

• latent_dim (int)

• hidden_dims (tuple[int, ...])

• dropout (float)

• kl_weight (float)

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

dict[str, Tensor]

Parameters:

x (Tensor)

Denoising autoencoder baseline.

class scdlkit.models.denoising.DenoisingAutoEncoder(input_dim, latent_dim=32, hidden_dims=(512, 256), dropout=0.1, noise_probability=0.15)

Bases: AutoEncoder

Autoencoder with input masking noise during training.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• input_dim (int)

• latent_dim (int)

• hidden_dims (tuple[int, ...])

• dropout (float)

• noise_probability (float)

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

dict[str, Tensor]

Parameters:

x (Tensor)

Patch-based transformer autoencoder for tabular single-cell inputs.

class scdlkit.models.transformer.TransformerAutoEncoder(input_dim, latent_dim=32, hidden_dims=None, patch_size=16, d_model=128, n_heads=4, n_layers=2, decoder_hidden_dims=(256, 128), dropout=0.1)

Bases: BaseModel

Patch-based transformer autoencoder.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• input_dim (int)

• latent_dim (int)

• hidden_dims (tuple[int, ...] | None)

• patch_size (int)

• d_model (int)

• n_heads (int)

• n_layers (int)

• decoder_hidden_dims (tuple[int, ...])

• dropout (float)

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

dict[str, Tensor]

Parameters:

x (Tensor)

MLP classification baseline.

class scdlkit.models.classifier.MLPClassifier(input_dim, num_classes, hidden_dims=(256, 128), dropout=0.2)

Bases: BaseModel

Simple classifier over preprocessed expression features.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

• input_dim (int)

• num_classes (int)

• hidden_dims (tuple[int, ...])

• dropout (float)

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

dict[str, Tensor]

Parameters:

x (Tensor)