Methods (Built-in Steps)¶

These are the pre-configured processor steps exported from sclab.methods.

Base Classes¶

ProcessorStepBase¶

The base class for all processor steps — subclass this to create custom steps.

ProcessorStepBase ¶

ProcessorStepBase(parent: Processor, fixed_params: dict[str, Any], variable_controls: dict[str, DescriptionWidget | ValueWidget], results: _Results | None = None)

Bases: EventClient

Base class for interactive processor steps in the SCLab dashboard.

Subclass this to create a custom analysis step that integrates with the :class:~sclab.dataset.processor.Processor panel. Each step exposes a widget-based control panel and publishes events when it starts and finishes running.

Subclasses must define the following class attributes:

name (str): Unique step identifier (e.g. "my_step").
description (str): Human-readable label shown in the UI.

Subclasses must override:

:meth:function: The analysis logic to execute when the step is run.

Parameters:

Name	Type	Description	Default
`parent`	`Processor`	The parent :class:`~sclab.dataset.processor.Processor` that owns this step.	required
`fixed_params`	`dict`	Parameters that are fixed at construction time and passed directly to :meth:`function` at runtime (not exposed as widgets).	required
`variable_controls`	`dict`	Mapping of parameter names to ipywidgets (:class:`~ipywidgets.widgets.widget_description.DescriptionWidget` or :class:`~ipywidgets.widgets.valuewidget.ValueWidget`). Each widget's `.value` is passed to :meth:`function` at runtime under its key.	required
`results`	`_Results or None`	Optional results panel to display after the step runs. If provided, it is registered with the parent's results panel. Default is None.	`None`

Attributes:

Name	Type	Description
`name`	`str`	Step identifier. Must be set as a class variable in subclasses.
`description`	`str`	Human-readable step name. Must be set as a class variable.
`order`	`int`	Integer used to sort steps in the processor accordion. Lower values appear first. Default is 1000.
`controls`	`VBox`	The assembled widget panel for this step.
`run_button`	`Button`	The button that triggers :meth:`run`.
`output`	`Output`	Widget area for displaying step output messages.

BasicProcessorStep¶

BasicProcessorStep ¶

BasicProcessorStep(parent: Processor, description: str, function: callable, fixed_params: dict[str, Any] = {}, variable_controls: dict[str, DescriptionWidget | ValueWidget] = {}, use_run_button: bool = True)

Bases: EventClient

Lightweight wrapper that registers a plain function as a processor step.

Use this when you have a standalone function that operates on adata and you want to expose it as a runnable step in the :class:~sclab.dataset.processor.Processor panel without subclassing :class:ProcessorStepBase.

Parameters:

Name	Type	Description	Default
`parent`	`Processor`	The parent :class:`~sclab.dataset.processor.Processor`.	required
`description`	`str`	Human-readable label for the step.	required
`function`	`callable`	The function to call when the step runs. It receives the merged `fixed_params` and `variable_params` as keyword arguments.	required
`fixed_params`	`dict`	Parameters passed to `function` at runtime that are not exposed as widgets. Default is `{}`.	`{}`
`variable_controls`	`dict`	Mapping of parameter names to ipywidgets. Each widget's `.value` is passed to `function` under its key at runtime. Default is `{}`.	`{}`
`use_run_button`	`bool`	If True, include a "Run" button in the control panel. Default is True.	`True`

Attributes:

Name	Type	Description
`controls`	`VBox`	The assembled widget panel for this step.

Built-in Steps¶

QC¶

QC ¶

QC(parent: Processor)

Bases: ProcessorStepBase

Quality control step for single-cell RNA-seq data.

Computes per-cell and per-gene QC metrics using the selected counts layer, applies minimum count/gene/cell filters, and optionally restricts analysis to the top-ranked cells. After running, the plotter is updated to show barcode_rank vs total_counts.

Requires scanpy to be installed.

Preprocess¶

Preprocess ¶

Preprocess(parent: Processor)

Bases: ProcessorStepBase

Normalization and scaling step for single-cell RNA-seq data.

Applies a configurable preprocessing pipeline: optional per-group HVG selection, normalization (library size, entropy-weighted, or none), log1p transformation, optional covariate regression, and per-group scaling. The processed matrix is stored in a new named layer and the plotter is updated to show n_genes_by_counts vs total_counts.

Requires scanpy to be installed.

PCA¶

PCA ¶

PCA(parent: Processor)

Bases: ProcessorStepBase

Principal component analysis step.

Fits PCA on all cells or on a reference batch, then projects all cells onto the resulting principal components. Stores the embedding in adata.obsm["X_pca"]. Optionally zero-centers the embedding. A "Plot Variance Ratio" button is enabled after the step runs to inspect the explained variance per component.

Requires scanpy to be installed.

Integration¶

Integration ¶

Integration(parent: Processor)

Bases: ProcessorStepBase

Batch integration step for multi-sample single-cell data.

Corrects batch effects in a cell embedding by applying one of three integration algorithms: CCA (canonical correlation analysis), Harmony, or Scanorama. The corrected embedding is stored under a new obsm key named {use_rep}_{flavor} and selected in the plotter.

Available flavors:

"cca" — canonical correlation analysis via :func:~sclab.preprocess.cca_integrate.
"harmony" — Harmony via :func:~sclab.preprocess.harmony_integrate.
"scanorama" — Scanorama via :func:scanpy.external.pp.scanorama_integrate.

Neighbors¶

Neighbors ¶

Neighbors(parent: Processor)

Bases: ProcessorStepBase

k-nearest-neighbor graph construction step.

Builds the cell neighborhood graph using a selected embedding (use_rep) and a specified range of dimensions. Supports standard k-NN (via :func:scanpy.pp.neighbors) and batch-aware BBKNN graph construction when group_by_batch is enabled and the dashboard has a batch_key.

Requires scanpy to be installed.

UMAP¶

UMAP ¶

UMAP(parent: Processor)

Bases: ProcessorStepBase

UMAP dimensionality reduction step.

Computes a 2D or 3D UMAP embedding using the precomputed neighbor graph and stores it in adata.obsm under the key X_{n_components}Dumap (e.g. "X_2Dumap"). Optionally zero-centers the embedding. The plotter is updated to display the new embedding.

Requires scanpy to be installed.

Cluster¶

Cluster ¶

Cluster(parent: Processor)

Bases: ProcessorStepBase

Leiden graph-based clustering step.

Partitions cells into clusters using the Leiden algorithm on the precomputed neighbor graph. The resulting cluster labels are stored in adata.obs["leiden"] and published to the plotter as a metadata change.

Requires scanpy (≥1.9 with igraph flavor support) to be installed.

DoubletDetection¶

DoubletDetection ¶

DoubletDetection(parent: Processor)

Bases: ProcessorStepBase

Doublet detection step.

Identifies putative doublet cells using Scrublet. Scores and binary labels ("singlet" / "doublet") are added to adata.obs under keys {flavor}_score and {flavor}_label.

Requires the scrublet package to be installed (pip install scrublet).

GeneExpression¶

GeneExpression ¶

GeneExpression(parent: Processor)

Bases: ProcessorStepBase

Interactive gene expression visualization step.

Lets users search for a gene by name and immediately visualize its expression on the current plot. Expression can be shown on the 2D/3D scatter (colored by gene expression) or as a scatter plot against any numeric metadata column (e.g. pseudotime). The plot updates reactively whenever the gene, layer, axis, or color scale selection changes.

DifferentialExpression¶

DifferentialExpression ¶

DifferentialExpression(parent: Processor)

Bases: ProcessorStepBase

Differential gene expression analysis step.

Runs :func:scanpy.tl.rank_genes_groups to score genes for each selected group relative to a reference group. Results are stored in adata.uns and immediately displayed in a dedicated :class:DifferentialExpressionResults panel.

Multiple analyses can be run with different names and parameters; each is stored separately and accessible from the results dropdown.

Requires scanpy to be installed.

GuidedPseudotime¶

GuidedPseudotime ¶

GuidedPseudotime(parent: Processor)

Bases: ProcessorStepBase

Interactive pseudotime inference guided by a user-drawn path.

Enables the user to draw a trajectory directly on the scatter plot by clicking "Start Drawing" and tracing a path with the mouse. The drawn path is projected onto the selected cell embedding to assign a pseudotime value (0–1) to each cell. An SNR (signal-to-noise ratio) threshold filters embedding dimensions used for fitting.

Workflow

Select an embedding (use_rep) from the dropdown.
Click Start Drawing and draw a path on the scatter plot. Click again to finish drawing.
(Optional) Click Plot Signal to inspect the per-dimension fit.
Click Compute Pseudotime to run the pseudotime inference.
For periodic (circular) trajectories, click Estimate Pseudotime Start to align the start of the cycle.

Alternatively, click Automatic Drawing to infer a circular path automatically from the 2D layout.

Results are stored in adata.obs[key_added] and the fitted path coordinates in adata.obsm["{key_added}_path"].

TransferMetadata¶

TransferMetadata ¶

TransferMetadata(parent: Processor)

Bases: ProcessorStepBase

Metadata transfer step using the k-nearest-neighbor graph.

Propagates a metadata column from a labeled source group to all other cells using neighbor-weighted interpolation. Supports numeric, categorical, and boolean columns. For periodic numeric values (e.g. pseudotime on a circular trajectory), a periodic aggregation mode is available that accounts for border conditions.

Results are stored in adata.obs as a new transferred_{column} column (and an associated error/proportion column).

Requires a precomputed neighbor graph (run the Neighbors step first).