single_cell/parallel_subtyping

Description

Cell subtyping of h5mu file annotated with major types.

The input is expected to already carry a major cell-type annotation in
.obs (--obs_major_cell_type) on the modality to be subtyped (--modality).
Each major cell type is then subtyped independently, so that the annotation
is tailored to the cells within that group rather than the dataset as a
whole. The reference is likewise split by its matching major cell-type
annotation (--reference_obs_major_cell_type) so that each major cell type is
subtyped only against the reference cells of that same type. The resulting
subtype labels are combined back into a single output h5mu, preserving all
original modalities and cells.

The annotation methods and per-method options are those of the
parallel_annotation workflow and are applied identically to every major
cell type.

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 with a major cell-type annotation. Must be preprocessed in the same way as the reference.
--modality	string	Which modality to subtype. Must match the modality in --reference. Other modalities present in the input are passed through unaltered and merged back into the output.
--obs_major_cell_type	string required	The .obs column of --modality holding the major cell-type labels to split on. The target modality is split by this column and each major cell type is subtyped independently.
--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

--obs_major_cell_type

string

required

--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 on each major cell type.

Name

Type & Properties

--annotation_methods

string

required

multiple

Reference

Name	Type & Properties	Description
--reference	file required	Reference h5mu file with labeled observations. Used by all annotation methods (celltypist, harmony_knn, scanvi_scarches and scvi_knn).
--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 (sub)cell-type labels.
--reference_obs_major_cell_type	string required	The .obs column in --reference holding the major cell-type labels, matching the label set in --obs_major_cell_type. The reference is split by this column and each query major cell type is subtyped against the matching subset of the reference.
--allow_missing_reference_cell_type	boolean_true	Controls what happens when a query major cell type has no matching subset in the reference. When false (default), the workflow errors. When true, such cell types are passed through unannotated and merged back into the output alongside the subtyped cell types.
--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 and scanvi_scarches to subset features if provided.
--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

required

--reference_layer

string

--reference_layer_lognormalized

string

--reference_obs_target

string

--reference_obs_major_cell_type

string

required

--allow_missing_reference_cell_type

boolean_true

--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_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_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

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 for the consensus predicted cell type. Defaults to consensus_pred_<reference_obs_target>.
--consensus_obs_score	string	.obs slot for the consensus score, defined as the fraction of total weight assigned to the winning cell type. Defaults to consensus_score_<reference_obs_target>.
--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 slot naming

Name	Type & Properties	Description
--celltypist_obs_predictions	string	.obs column for CellTypist predicted labels. Defaults to celltypist_pred_<reference_obs_target>.
--celltypist_obs_probability	string	.obs column for CellTypist probabilities. Defaults to celltypist_probability_<reference_obs_target>.
--harmony_knn_obs_predictions	string	.obs column for harmony_knn predicted labels. Defaults to harmony_knn_pred_<reference_obs_target>.
--harmony_knn_obs_probability	string	.obs column for harmony_knn probabilities. Defaults to harmony_knn_probability_<reference_obs_target>.
--harmony_knn_obsm_integrated	string
--scanvi_scarches_obs_predictions	string	.obs column for scanvi_scarches predicted labels. Defaults to scanvi_pred_<reference_obs_target>.
--scanvi_scarches_obs_probability	string	.obs column for scanvi_scarches probabilities. Defaults to scanvi_probability_<reference_obs_target>.
--scanvi_scarches_obsm_integrated	string
--scvi_knn_obs_predictions	string	.obs column for scvi_knn predicted labels. Defaults to scvi_knn_pred_<reference_obs_target>.
--scvi_knn_obs_probability	string	.obs column for scvi_knn probabilities. Defaults to scvi_knn_probability_<reference_obs_target>.
--scvi_knn_obsm_integrated	string
--singler_obs_predictions	string	.obs column for SingleR predicted labels. Defaults to singler_pred_<reference_obs_target>.
--singler_obs_probability	string	.obs column for SingleR probabilities. Defaults to singler_probability_<reference_obs_target>.
--singler_obs_delta_next	string	.obs column for the SingleR delta-next score. Defaults to singler_delta_next_<reference_obs_target>.
--singler_obs_pruned_predictions	string	.obs column for SingleR pruned predicted labels. Defaults to singler_pruned_labels_<reference_obs_target>.
--singler_obsm_scores	string	.obsm key for the SingleR per-label score matrix. Defaults to singler_scores_<reference_obs_target>.

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

Output

Name	Type & Properties	Description
--output -o	file required output	Output h5mu file — the input query with each selected method's subtype predictions and embeddings merged into the target modality, and the other modalities merged back in unaltered.
--output_compression	string	Compression format for the output h5mu file.

Name

Type & Properties

--output

-o

file

required

output

--output_compression

string

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 ]  
run_consensus: [ true ]  
consensus_use_probabilities: [ true ]  
harmony_knn_obsm_integrated: [ "X_integrated_harmony" ]  
scanvi_scarches_obsm_integrated: [ "X_integrated_scanvi" ]  
scvi_knn_obsm_integrated: [ "X_integrated_scvi" ]  
output: "$id.$key.output.h5mu"  
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_subtyping/main.nf \  
  -params-file params.yaml

single_cell/parallel_subtyping

Inputs

Methods

Reference

Clustering options

Neighbor classifier options

scVI / scANVI / scArches training options

CellTypist options

harmony_knn options

scvi_knn options

SingleR options

Consensus vote options

Output slot naming

Output

Run this component

Relationships

Used by

Uses