name: "scanvi_scarches"
namespace: "workflows/annotation"
scope: "public"
description: "Cell type annotation workflow using ScanVI with scArches for reference mapping."
authors:
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ author, maintainer ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]

info:
  name: "scANVI - scArches workflow"
  test_dependencies:
    - name: scanvi_scarches_test
      namespace: test_workflows/annotation

argument_groups:
  - name: Query Input
    arguments:
      - name: "--id"
        required: true
        type: string
        description: ID of the sample.
        example: foo
      - name: "--input"
        required: true
        type: file
        description: Input dataset consisting of the (unlabeled) query observations. The dataset is expected to be pre-processed in the same way as --reference.
        example: input.h5mu
      - name: "--modality"
        description: Which modality to process. Should match the modality of the --reference dataset.
        type: string
        default: "rna"
        required: false
      - name: "--layer"
        type: string
        description: Which layer to use for integration if .X is not to be used. Should match the layer of the --reference dataset.
      - name: "--input_obs_batch_label"
        type: string
        description: "The .obs field in the input (query) dataset containing the batch labels."
        example: "sample"
        default: "sample_id"
        required: true
      - name: "--input_obs_size_factor"
        type: string
        required: false
        description: |
          Key in adata.obs for size factor information. Instead of using library size as a size factor,
          the provided size factor column will be used as offset in the mean of the likelihood.
          Assumed to be on linear scale.
      - name: "--input_obs_categorical_covariate"
        type: string
        required: false
        multiple: true
        description: |
          Keys in adata.obs that correspond to categorical data. These covariates can be added in
          addition to the batch covariate and are also treated as nuisance factors
          (i.e., the model tries to minimize their effects on the latent space).
          Thus, these should not be used for biologically-relevant factors that you do _not_ want to correct for.
          Important: the order of the categorical covariates matters and should match the order of the covariates in the reference data.
      - name: "--input_obs_continuous_covariate"
        type: string
        required: false
        multiple: true
        description: |
          Keys in adata.obs that correspond to continuous data. These covariates can be added in
          addition to the batch covariate and are also treated as nuisance factors
          (i.e., the model tries to minimize their effects on the latent space). Thus, these should not be
          used for biologically-relevant factors that you do _not_ want to correct for.
          Important: the order of the continuous covariates matters and should match the order of the covariates in the reference data.
      - name: "--input_var_gene_names"
        type: string
        required: false
        description: ".var column containing gene names. By default, use the index."
      - name: "--sanitize_ensembl_ids"
        type: boolean
        description: Whether to sanitize ensembl ids by removing version numbers.
        default: true

  - name: Reference input
    arguments:
      - name: "--reference"
        required: true
        type: file
        description: Reference dataset consisting of the labeled observations to train the KNN classifier on. The dataset is expected to be pre-processed in the same way as the --input query dataset.
        example: reference.h5mu
      - name: "--reference_obs_target"
        type: string
        example: cell_type
        required: true
        description: The `.obs` key containing the target labels.
      - name: "--reference_obs_batch_label"
        type: string
        default: "sample_id"
        description:  "The .obs field in the reference dataset containing the batch labels."
        example: "sample"
        required: true
      - name: "--reference_obs_size_factor"
        type: string
        required: false
        description: |
          Key in adata.obs for size factor information. Instead of using library size as a size factor,
          the provided size factor column will be used as offset in the mean of the likelihood.
          Assumed to be on linear scale.
      - name: "--reference_obs_categorical_covariate"
        type: string
        required: false
        multiple: true
        description: |
          Keys in adata.obs that correspond to categorical data. These covariates can be added in
          addition to the batch covariate and are also treated as nuisance factors
          (i.e., the model tries to minimize their effects on the latent space).
          Thus, these should not be used for biologically-relevant factors that you do _not_ want to correct for.
          Important: the order of the categorical covariates matters and should match the order of the covariates in the query data.
      - name: "--reference_obs_continuous_covariate"
        type: string
        required: false
        multiple: true
        description: |
          Keys in adata.obs that correspond to continuous data. These covariates can be added in
          addition to the batch covariate and are also treated as nuisance factors
          (i.e., the model tries to minimize their effects on the latent space). Thus, these should not be
          used for biologically-relevant factors that you do _not_ want to correct for.
          Important: the order of the continuous covariates matters and should match the order of the covariates in the query data.
      - name: "--unlabeled_category"
        type: string
        default: "Unknown"
        description: | 
          Value in the --reference_obs_batch_label field that indicates unlabeled observations
      - name: "--reference_var_hvg"
        type: string
        default: "filter_with_hvg"
        required: false
        description: ".var column containing highly variable genes. If not provided, genes will not be subset."
      - name: "--reference_var_gene_names"
        type: string
        required: false
        description: ".var column containing gene names. By default, use the index."

  - name: scVI, scANVI and scArches training options
    arguments:
      - name: "--early_stopping"
        required: false
        type: boolean
        description: "Whether to perform early stopping with respect to the validation set."
      - name: "--early_stopping_monitor"
        choices: ["elbo_validation", "reconstruction_loss_validation", "kl_local_validation"]
        default: "elbo_validation"
        type: string
        description: "Metric logged during validation set epoch."
      - name: "--early_stopping_patience"
        type: integer
        min: 1
        default: 45
        description: "Number of validation epochs with no improvement after which training will be stopped."
      - name: "--early_stopping_min_delta"
        min: 0
        type: double
        default: 0.0
        description: "Minimum change in the monitored quantity to qualify as an improvement, i.e. an absolute change of less than min_delta, will count as no improvement."
      - name: "--max_epochs"
        type: integer
        description: "Number of passes through the dataset, defaults to (20000 / number of cells) * 400 or 400; whichever is smallest."
        required: false
      - name: "--reduce_lr_on_plateau"
        description: "Whether to monitor validation loss and reduce learning rate when validation set `lr_scheduler_metric` plateaus."
        type: boolean
        default: True
      - name: "--lr_factor"
        description: "Factor to reduce learning rate."
        type: double
        default: 0.6
        min: 0
      - name: "--lr_patience"
        description: "Number of epochs with no improvement after which learning rate will be reduced."
        type: double
        default: 30
        min: 0

  - name: Leiden clustering options
    arguments:
      - name: "--leiden_resolution"
        type: double
        description: Control the coarseness of the clustering. Higher values lead to more clusters.
        min: 0
        default: [1]
        multiple: true

  - name: Neighbor classifier arguments
    arguments:
      - name: "--knn_weights"
        type: string
        default: "uniform"
        choices: ["uniform", "distance"]
        description: |
          Weight function used in prediction. Possible values are:
          `uniform` (all points in each neighborhood are weighted equally) or 
          `distance` (weight points by the inverse of their distance)
      - name: "--knn_n_neighbors"
        type: integer
        default: 15
        min: 5
        required: false
        description: |
          The number of neighbors to use in k-neighbor graph structure used for fast approximate nearest neighbor search with PyNNDescent. 
          Larger values will result in more accurate search results at the cost of computation time.
  
  - name: "Outputs"
    arguments:
      - name: "--output"
        type: file
        required: true
        direction: output
        description: The annotated output .h5mu file.
        example: output.h5mu
      - name: "--output_obs_predictions"
        type: string
        default: "scanvi_pred"
        description: "In which .obs slot to store the predicted labels."
      - name: "--output_obs_probability"
        type: string
        default: "scanvi_probabilities"
        description: "In which. obs slot to store the probabilities of the predicted labels."
      - name: "--output_obsm_integrated"
        type: string
        default: "X_integrated_scanvi"
        description: "In which .obsm slot to store the integrated embedding."
      - name: "--output_compression"
        type: string
        description: |
          The compression format to be used on the output h5mu object.
        choices: ["gzip", "lzf"]
        required: false
        example: "gzip"
      - name: "--output_model"
        type: file
        direction: output
        description: Path to the resulting scANVI model that was updated with query data.
      
dependencies:
  - name: integrate/scvi
  - name: annotate/scanvi
  - name: integrate/scarches
  - name: workflows/multiomics/neighbors_leiden_umap

resources:
  - type: nextflow_script
    path: main.nf
    entrypoint: run_wf

test_resources:
  - type: nextflow_script
    path: test.nf
    entrypoint: test_wf
  - path: /resources_test/annotation_test_data/TS_Blood_filtered.h5mu
  - path: /resources_test/pbmc_1k_protein_v3/pbmc_1k_protein_v3_mms.h5mu

runners:
  - type: nextflow