single_cell/parallel_annotation

Description

Run multiple annotation methods from OpenPipeline in parallel on the same
preprocessed query h5mu input, then merge each method's predictions
(predicted labels and probabilities in .obs, and integrated embeddings in
.obsm for the integration-based methods) back into a single output h5mu.

These are label-projection (reference-based) methods: they transfer labels from
a labelled --reference onto the query (CellTypist can alternatively use a
pretrained --celltypist_model). The reference is expected to be preprocessed in
the same way as the query.

Available annotation methods:

CellTypist
ScanVI with scArches
SingleR
SCVI integration followed by KNN label transfer
Harmony integration followed by KNN label transfer

Inputs

Name	Type & Properties	Description
--id	string required	ID of the sample.
--input	file required	Input query h5mu file. Must be preprocessed in the same way as the reference (raw counts and log-normalized counts available).
--modality	string	Which modality to process. Must match the modality in --reference.
--input_layer	string	The layer of the input query containing raw counts. Required by celltypist (which log-normalizes internally), scanvi_scarches and scvi_knn (which model raw counts directly). If not provided, .X will be used.
--input_layer_lognormalized	string	The layer of the input query containing log-normalized counts. Required by harmony_knn and scvi_knn.
--input_obs_batch_label	string	.obs column in the input query containing batch labels. Required by harmony_knn, scanvi_scarches and scvi_knn.
--input_var_gene_names	string	.var column containing gene names. By default the .var index is used.
--input_reference_gene_overlap	integer	Minimum number of genes required to overlap between query and reference.
--sanitize_ensembl_ids	boolean	Whether to sanitize ensembl gene ids by removing version numbers. Read by celltypist, scanvi_scarches, scvi_knn and singler.
--input_obs_categorical_covariates	string multiple	.obs column(s) in the input query with categorical covariates for scanvi_scarches to correct for in addition to the batch label. Treated as nuisance factors; their order must match --reference_obs_categorical_covariates. None by default.
--input_obs_numerical_covariates	string multiple	.obs column(s) in the input query with continuous (numerical) covariates for scanvi_scarches to correct for in addition to the batch label. Treated as nuisance factors; their order must match --reference_obs_numerical_covariates. None by default.

Name

Type & Properties

--id

string

required

--input

file

required

--modality

string

--input_layer

string

--input_layer_lognormalized

string

--input_obs_batch_label

string

--input_var_gene_names

string

--input_reference_gene_overlap

integer

--sanitize_ensembl_ids

boolean

--input_obs_categorical_covariates

string

multiple

--input_obs_numerical_covariates

string

multiple

Methods

Name	Type & Properties	Description
--annotation_methods	string required multiple	Annotation methods to run in parallel.

Name

Type & Properties

--annotation_methods

string

required

multiple

Reference

Name	Type & Properties	Description
--reference	file	Reference h5mu file with labeled observations. Required by harmony_knn, scanvi_scarches, scvi_knn, and by celltypist when --celltypist_model is not provided.
--reference_layer	string	Layer of the reference containing raw counts. If not provided, .X will be used.
--reference_layer_lognormalized	string	Layer of the reference containing log-normalized counts.
--reference_obs_target	string	.obs column in the reference containing the target cell-type labels.
--reference_obs_batch_label	string	.obs column in the reference containing batch labels.
--reference_var_gene_names	string	.var column in the reference containing gene names. Defaults to the .var index.
--reference_var_input	string	.var column in the reference flagging highly-variable genes (boolean). Used by celltypist (--reference_var_input) and scanvi_scarches (mapped to --reference_var_hvg) to subset features.
--reference_obs_categorical_covariates	string multiple	.obs column(s) in the reference with categorical covariates for scanvi_scarches to correct for in addition to the batch label. Treated as nuisance factors; their order must match --input_obs_categorical_covariates. None by default.
--reference_obs_numerical_covariates	string multiple	.obs column(s) in the reference with continuous (numerical) covariates for scanvi_scarches to correct for in addition to the batch label. Treated as nuisance factors; their order must match --input_obs_numerical_covariates. None by default.
--reference_obs_label_unlabeled_category	string	Value in --reference_obs_target that indicates unlabeled observations.

Name

Type & Properties

--reference

file

--reference_layer

string

--reference_layer_lognormalized

string

--reference_obs_target

string

--reference_obs_batch_label

string

--reference_var_gene_names

string

--reference_var_input

string

--reference_obs_categorical_covariates

string

multiple

--reference_obs_numerical_covariates

string

multiple

--reference_obs_label_unlabeled_category

string

Clustering options

Name	Type & Properties	Description
--leiden_resolution	double multiple	Leiden clustering resolution(s). Higher values lead to more clusters.

Name

Type & Properties

--leiden_resolution

double

multiple

Neighbor classifier options

Name	Type & Properties	Description
--knn_weights	string	Weight function for KNN classifier.
--knn_n_neighbors	integer	Number of neighbors for the KNN classifier.

Name

Type & Properties

--knn_weights

string

--knn_n_neighbors

integer

scVI / scANVI / scArches training options

Name	Type & Properties	Description
--scvi_early_stopping	boolean	Whether to perform early stopping with respect to the validation set.
--scvi_early_stopping_monitor	string	Metric logged during validation set epoch.
--scvi_early_stopping_patience	integer	Number of validation epochs with no improvement after which training stops.
--scvi_early_stopping_min_delta	double	Minimum change in the monitored metric to qualify as an improvement.
--scvi_max_epochs	integer	Number of training passes through the dataset.
--scvi_reduce_lr_on_plateau	boolean	Reduce learning rate when validation metric plateaus.
--scvi_lr_factor	double	Factor by which to reduce learning rate.
--scvi_lr_patience	double	Number of epochs with no improvement after which lr is reduced.

Name

Type & Properties

--scvi_early_stopping

boolean

--scvi_early_stopping_monitor

string

--scvi_early_stopping_patience

integer

--scvi_early_stopping_min_delta

double

--scvi_max_epochs

integer

--scvi_reduce_lr_on_plateau

boolean

--scvi_lr_factor

double

--scvi_lr_patience

double

CellTypist options

Name	Type & Properties	Description
--celltypist_model	file	Pretrained CellTypist model in .pkl format. If not provided, the model is trained on --reference.
--celltypist_majority_voting	boolean	Refine predicted labels by majority voting after over-clustering.
--celltypist_feature_selection	boolean	Whether to perform feature selection during training.
--celltypist_C	double	Inverse of regularization strength in logistic regression.
--celltypist_max_iter	integer	Maximum iterations before reaching the cost-function minimum.
--celltypist_use_SGD	boolean	Whether to use stochastic gradient descent.
--celltypist_min_prop	double	Minimum proportion of cells in a sub-cluster supporting a label for majority voting; only relevant if --celltypist_majority_voting is set.

Name

Type & Properties

--celltypist_model

file

--celltypist_majority_voting

boolean

--celltypist_feature_selection

boolean

--celltypist_C

double

--celltypist_max_iter

integer

--celltypist_use_SGD

boolean

--celltypist_min_prop

double

harmony_knn options

Name	Type & Properties	Description
--harmony_knn_n_hvg	integer	Number of highly-variable genes to keep for harmony_knn.
--harmony_knn_pca_num_components	integer	Number of principal components to compute for harmony_knn.
--harmony_knn_theta	double multiple	Diversity clustering penalty for harmony.

Name

Type & Properties

--harmony_knn_n_hvg

integer

--harmony_knn_pca_num_components

integer

--harmony_knn_theta

double

multiple

scvi_knn options

Name	Type & Properties	Description
--scvi_knn_n_hvg	integer	Number of highly-variable genes to keep for scvi_knn.

Name

Type & Properties

--scvi_knn_n_hvg

integer

SingleR options

Name	Type & Properties	Description
--singler_input_obs_clusters	string	.obs column with cluster identities. If provided, SingleR annotates the aggregated cluster profiles; otherwise it annotates per observation.
--singler_de_method	string	Method to detect differentially expressed genes between pairs of labels.
--singler_de_n_genes	integer	Number of differentially expressed genes per label pair to use as markers. Defaults to a SingleR heuristic based on the number of labels.
--singler_quantile	double	Quantile of the correlation distribution used to score each label.
--singler_fine_tune	boolean	Whether to fine-tune label assignment after the initial classification.
--singler_fine_tuning_threshold	double	Maximum difference from the maximum correlation to use in fine-tuning.
--singler_prune	boolean	Whether to prune low-quality labels (replaced with NA in the pruned predictions output).

Name

Type & Properties

--singler_input_obs_clusters

string

--singler_de_method

string

--singler_de_n_genes

integer

--singler_quantile

double

--singler_fine_tune

boolean

--singler_fine_tuning_threshold

double

--singler_prune

boolean

Output slot naming

Name	Type & Properties	Description
--celltypist_obs_predictions	string
--celltypist_obs_probability	string
--harmony_knn_obs_predictions	string
--harmony_knn_obs_probability	string
--harmony_knn_obsm_integrated	string
--scanvi_scarches_obs_predictions	string
--scanvi_scarches_obs_probability	string
--scanvi_scarches_obsm_integrated	string
--scvi_knn_obs_predictions	string
--scvi_knn_obs_probability	string
--scvi_knn_obsm_integrated	string
--singler_obs_predictions	string
--singler_obs_probability	string
--singler_obs_delta_next	string
--singler_obs_pruned_predictions	string
--singler_obsm_scores	string

Name

Type & Properties

--celltypist_obs_predictions

string

--celltypist_obs_probability

string

--harmony_knn_obs_predictions

string

--harmony_knn_obs_probability

string

--harmony_knn_obsm_integrated

string

--scanvi_scarches_obs_predictions

string

--scanvi_scarches_obs_probability

string

--scanvi_scarches_obsm_integrated

string

--scvi_knn_obs_predictions

string

--scvi_knn_obs_probability

string

--scvi_knn_obsm_integrated

string

--singler_obs_predictions

string

--singler_obs_probability

string

--singler_obs_delta_next

string

--singler_obs_pruned_predictions

string

--singler_obsm_scores

string

Consensus vote options

Name	Type & Properties	Description
--run_consensus	boolean	Run a final consensus vote combining the per-method predictions. Only takes effect when more than one --annotation_methods is selected.
--consensus_obs_predictions	string	.obs slot in which to store the consensus predicted cell type.
--consensus_obs_score	string	.obs slot in which to store the consensus score, defined as the fraction of total weight assigned to the winning cell type.
--consensus_use_probabilities	boolean	Scale each method's vote by its per-cell prediction probability. When false, every method votes with equal weight regardless of confidence.
--consensus_tie_label	string	Label to assign when two or more cell types receive equal votes. If not provided, tied cells are assigned a missing value.

Name

Type & Properties

--run_consensus

boolean

--consensus_obs_predictions

string

--consensus_obs_score

string

--consensus_use_probabilities

boolean

--consensus_tie_label

string

Output

Name	Type & Properties	Description
--output -o	file required output	Output h5mu file — the input query with each selected method's predictions and embeddings merged into the target modality.
--output_compression	string	Compression format for the output h5mu file.
--output_scanvi_model	file output	Output folder with the trained scANVI/scArches model. Only produced when scanvi_scarches is among the selected --annotation_methods.

Name

Type & Properties

--output

-o

file

required

output

--output_compression

string

--output_scanvi_model

file

output

Run this component

Run the following command to execute this component with Nextflow:

cat > params.yaml <<'EOM'  
id: "run"  
modality: [ "rna" ]  
input_layer_lognormalized: [ "log_normalized" ]  
input_obs_batch_label: [ "sample_id" ]  
input_reference_gene_overlap: [ 100 ]  
sanitize_ensembl_ids: [ true ]  
reference_layer_lognormalized: [ "log_normalized" ]  
reference_obs_batch_label: [ "sample_id" ]  
reference_var_input: [ "filter_with_hvg" ]  
reference_obs_label_unlabeled_category: [ "Unknown" ]  
leiden_resolution: [ 1 ]  
knn_weights: [ "uniform" ]  
knn_n_neighbors: [ 15 ]  
scvi_early_stopping_monitor: [ "elbo_validation" ]  
scvi_early_stopping_patience: [ 45 ]  
scvi_early_stopping_min_delta: [ 0 ]  
scvi_reduce_lr_on_plateau: [ true ]  
scvi_lr_factor: [ 0.6 ]  
scvi_lr_patience: [ 30 ]  
celltypist_majority_voting: [ false ]  
celltypist_feature_selection: [ false ]  
celltypist_C: [ 1 ]  
celltypist_max_iter: [ 1000 ]  
celltypist_use_SGD: [ false ]  
celltypist_min_prop: [ 0 ]  
harmony_knn_n_hvg: [ 2000 ]  
harmony_knn_theta: [ 2 ]  
scvi_knn_n_hvg: [ 2000 ]  
singler_de_method: [ "classic" ]  
singler_quantile: [ 0.8 ]  
singler_fine_tune: [ true ]  
singler_fine_tuning_threshold: [ 0.05 ]  
singler_prune: [ true ]  
celltypist_obs_predictions: [ "celltypist_pred" ]  
celltypist_obs_probability: [ "celltypist_probability" ]  
harmony_knn_obs_predictions: [ "harmony_knn_pred" ]  
harmony_knn_obs_probability: [ "harmony_knn_probability" ]  
harmony_knn_obsm_integrated: [ "X_integrated_harmony" ]  
scanvi_scarches_obs_predictions: [ "scanvi_pred" ]  
scanvi_scarches_obs_probability: [ "scanvi_probability" ]  
scanvi_scarches_obsm_integrated: [ "X_integrated_scanvi" ]  
scvi_knn_obs_predictions: [ "scvi_knn_pred" ]  
scvi_knn_obs_probability: [ "scvi_knn_probability" ]  
scvi_knn_obsm_integrated: [ "X_integrated_scvi" ]  
singler_obs_predictions: [ "singler_pred" ]  
singler_obs_probability: [ "singler_probability" ]  
singler_obs_delta_next: [ "singler_delta_next" ]  
singler_obs_pruned_predictions: [ "singler_pruned_labels" ]  
singler_obsm_scores: [ "singler_scores" ]  
run_consensus: [ true ]  
consensus_obs_predictions: [ "consensus_pred" ]  
consensus_obs_score: [ "consensus_score" ]  
consensus_use_probabilities: [ true ]  
output: "$id.$key.output.h5mu"  
output_scanvi_model: "$id.$key.output_scanvi_model.scanvi_model"  
publish_dir: "output/"  
EOM

nextflow run https://packages.viash-hub.com/vsh/openpipeline_composed.git \  
  -revision v0.3.0 \  
  -main-script target/nextflow/single_cell/parallel_annotation/main.nf \  
  -params-file params.yaml

single_cell/parallel_annotation

Inputs

Methods

Reference

Clustering options

Neighbor classifier options

scVI / scANVI / scArches training options

CellTypist options

harmony_knn options

scvi_knn options

SingleR options

Output slot naming

Consensus vote options

Output

Run this component

Relationships

Used by

Uses