name: "scvi_knn"
namespace: "workflows/annotation"
scope: "public"
description: |
  "Cell type annotation workflow that performs scVI integration of reference and query dataset followed by KNN label transfer. 
  The query and reference datasets are expected to be pre-processed in the same way, for example with the `process_samples` workflow of OpenPipeline.
  Note that this workflow will integrate the reference dataset from scratch and integrate the query dataset in the same embedding space. 
  The workflow does not currently output the trained SCVI reference model."
authors:
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ author, maintainer ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]
info:
  name: "scVI Annotation"
  test_dependencies:
    - name: scvi_knn_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. 
        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: "--input_layer"
        type: string
        example: counts
        description: The layer of the input dataset containing the raw counts if .X is not to be used.
      - name: "--input_layer_lognormalized"
        type: string
        example: log_normalized
        description: The layer of the input dataset containing the lognormalized counts if .X is not to be used.
      - name: "--input_obs_batch_label"
        type: string
        description: "The .obs field in the input (query) dataset containing the batch labels."
        example: "sample"
        required: true
      - name: "--input_var_gene_names"
        type: string
        required: false
        description: |
          The .var field in the input (query) dataset containing gene names; if not provided, the .var index will be used.
      - name: "--input_reference_gene_overlap"
        type: integer
        default: 100
        min: 1
        description: | 
          The minimum number of genes present in both the reference and query datasets.
      - name: "--overwrite_existing_key"
        type: boolean_true
        description: If provided, will overwrite existing fields in the input dataset when data are copied during the reference alignment process.
      - 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.
        example: reference.h5mu
      - name: "--reference_layer"
        type: string
        example: counts
        description: The layer of the reference dataset containing the raw counts if .X is not to be used.
      - name: "--reference_layer_lognormalized"
        type: string
        example: log_normalized
        description: The layer of the reference dataset containing the lognormalized counts if .X is not to be used.
      - name: "--reference_obs_target"
        type: string
        example: cell_type
        required: true
        description: The `.obs` key(s) of the target labels to transfer.
      - name: "--reference_var_gene_names"
        type: string
        required: false
        description: |
          The .var field in the reference dataset containing gene names; if not provided, the .var index will be used.
      - name: "--reference_obs_batch_label"
        type: string
        description:  "The .obs field in the reference dataset containing the batch labels."
        example: "sample"
        required: true

  - name: "HVG subset arguments"
    arguments:
      - name: "--n_hvg"
        type: integer
        default: 2000
        description: |
          Number of highly variable genes to subset for.

  - name: scVI integration options
    arguments:
      - name: "--scvi_early_stopping"
        required: false
        type: boolean
        description: "Whether to perform early stopping with respect to the validation set."
      - name: "--scvi_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: "--scvi_early_stopping_patience"
        type: integer
        min: 1
        default: 45
        description: "Number of validation epochs with no improvement after which training will be stopped."
      - name: "--scvi_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: "--scvi_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: "--scvi_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: "--scvi_lr_factor"
        description: "Factor to reduce learning rate."
        type: double
        default: 0.6
        min: 0
      - name: "--scvi_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 query data in .h5mu format with predicted labels predicted from the classifier trained on the reference.
        example: output.h5mu
      - name: "--output_obs_predictions"
        type: string
        required: false
        multiple: true
        description: |
          In which `.obs` slots to store the predicted cell labels.
          If provided, must have the same length as `--reference_obs_targets`.
          If empty, will default to the `reference_obs_targets` combined with the `"_pred"` suffix.
      - name: "--output_obs_probability"
        type: string
        required: false
        multiple: true
        description: |
          In which `.obs` slots to store the probability of the predictions.
          If provided, must have the same length as `--reference_obs_targets`.
          If empty, will default to the `reference_obs_targets` combined with the `"_probability"` suffix.
      - name: "--output_obsm_integrated"
        type: string
        default: "X_integrated_scvi"
        required: false
        description: "In which .obsm slot to store the integrated embedding."

dependencies:
  - name: workflows/integration/scvi_leiden
    alias: scvi_leiden_workflow
  - name: labels_transfer/knn
  - name: workflows/multiomics/split_h5mu
  - name: dataflow/concatenate_h5mu
  - name: feature_annotation/align_query_reference
  - name: feature_annotation/highly_variable_features_scanpy
  - name: transform/delete_layer
  - name: workflows/multiomics/split_modalities
  - name: dataflow/merge

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

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

runners:
  - type: nextflow
