name: scanvi
namespace: "annotate"
scope: "public"
description: |
  scANVI () is a semi-supervised model for single-cell transcriptomics data. scANVI is an scVI extension that can leverage the cell type knowledge for a subset of the cells present in the data sets to infer the states of the rest of the cells.
  This component will instantiate a scANVI model from a pre-trained scVI model, integrate the data and perform label prediction.

authors:
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ maintainer ]
  - __merge__: /src/authors/jakub_majercik.yaml
    roles: [ author ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]
argument_groups:
  - name: Inputs
    arguments:
      - name: "--input"
        alternatives: ["-i"]
        type: file
        description: Input h5mu file. Note that this needs to be the exact same dataset as the --scvi_model was trained on.
        direction: input
        required: true
      - name: "--modality"
        description: |
          Which modality from the input MuData file to process.
        type: string
        default: "rna"
        required: false
      - name: "--input_layer"
        type: string
        required: false
        description: "Input layer to use. If None, X is used"
      - name: "--var_input"
        type: string
        required: false
        description: ".var column containing highly variable genes that were used to train the scVi model. By default, do not subset genes."
      - name: "--var_gene_names"
        type: string
        required: false
        description: ".var column containing gene names. By default, use the index."
      - name: "--obs_labels"
        type: string
        required: true
        description: ".obs field containing the labels"
      - name: "--unlabeled_category"
        type: string
        default: "Unknown"
        description: | 
          Value in the --obs_labels field that indicates unlabeled observations
      - name: "--sanitize_ensembl_ids"
        type: boolean
        description: Whether to sanitize ensembl ids by removing version numbers.
        default: true

  - name: scVI Model
    arguments:
      - name: "--scvi_model"
        type: file
        description: "Pretrained SCVI reference model to initialize the SCANVI model with."
        example: scvi_model.pt
        direction: input
        required: true
  
  - name: Outputs
    arguments:
      - name: "--output"
        alternatives: ["-o"]
        type: file
        description: Output h5mu file.
        direction: output
        required: true
      - name: "--output_model"
        type: file
        description: Folder where the state of the trained model will be saved to.
        required: false
        direction: output
      - name: "--obsm_output"
        type: string
        default: "X_scanvi_integrated"
        required: false
        description: "In which .obsm slot to store the resulting integrated embedding."
      - name: "--obs_output_predictions"
        type: string
        default: scanvi_pred
        description: "In which .obs slot to store the predicted labels."
      - name: "--obs_output_probabilities"
        type: string
        default: scanvi_proba
        description: "In which. obs slot to store the probabilities of the predicted labels."
    __merge__: [., /src/base/h5_compression_argument.yaml]
 
  - name: "scANVI training arguments"
    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

resources:
  - type: python_script
    path: script.py
  - path: /src/utils/subset_vars.py
  - path: /src/utils/compress_h5mu.py
  - path: /src/utils/set_var_index.py
  - path: /src/utils/setup_logger.py
test_resources:
  - type: python_script
    path: test.py
  - path: /resources_test/annotation_test_data/scvi_model/
  - path: /resources_test/annotation_test_data/TS_Blood_filtered.h5mu
  - path: /resources_test/pbmc_1k_protein_v3/pbmc_1k_protein_v3_mms.h5mu

engines:
- type: docker
  image: pytorch/pytorch:2.9.1-cuda12.8-cudnn9-runtime
  setup:
    - type: python
      __merge__: [/src/base/requirements/anndata_mudata.yaml, /src/base/requirements/scanpy.yaml, .]
    - type: python
      packages:
        - scvi-tools[cuda]~=1.4.1
  test_setup:
    - type: python
      __merge__: [ /src/base/requirements/viashpy.yaml, .]

runners:
- type: executable
  # docker_run_args: ["--gpus all"]
- type: nextflow
  directives:
    label: [midcpu, midmem, gpu, highdisk]
