name: scarches
namespace: "integrate"
scope: "public"
description: "Performs reference mapping with scArches"
authors:
  - __merge__: /src/authors/vladimir_shitov.yaml
    roles: [ author ]
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ maintainer ]
argument_groups:
  - name: Inputs
    description: Arguments related to the input (query) dataset
    arguments:
      - name: "--input"
        alternatives: ["-i"]
        type: file
        description: Input h5mu file to use as a query
        direction: input
        required: true
        example: input.h5mu
      - name: "--layer"
        type: string
        description: Layer to be used for scArches, if .X is not to be used.
        required: false
      - name: "--modality"
        description: |
          Which modality from the input MuData file to process.
        type: string
        default: "rna"
        required: false
      - name: "--input_obs_batch"
        type: string
        description: Name of the .obs column with batch information.
        required: false
      - name: "--input_obs_label"
        type: string
        description: Name of the .obs column with celltype information.
        required: false
      - name: "--input_var_gene_names"
        type: string
        description: Name of the .var column with gene names, if the var .index is not to be used.
        required: false
      - 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 trained reference model.
      - 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 trained reference model.
      - name: "--sanitize_ensembl_ids"
        type: boolean
        description: Whether to sanitize ensembl ids by removing version numbers.
        default: true

  - name: Reference
    arguments:
      - name: "--reference"
        alternatives: ["-r"]
        type: file
        description: Path to the directory with reference model or a web link.
        required: true
        example: path/to/reference/
      - name: "--reference_class"
        type: string
        required: false
        description: 
          For legacy models; the type of model (where the type of model was not saved with it; e.g. when they were generated with scvi-tools versions < 0.15).
        example: SCANVI

  - name: Outputs
    arguments:
      - name: "--output"
        alternatives: ["-o"]
        type: file
        description: Output h5mu file.
        direction: output
        required: true
        example: output.h5mu
      - name: "--model_output"
        type: file
        default: "model"
        direction: output
        description: Output directory for model
        example: path/to/output_model/
      - name: "--obsm_output"
        type: string
        default: "X_integrated_scanvi"
        required: false
        description: "In which .obsm slot to store the resulting integrated embedding."
      - name: "--obs_output_predictions"
        type: string
        default: "scanvi_pred"
        required: false
        description: "In which .obs slot to store the resulting label predictions. Only relevant if a scANVI model was provided."
      - name: "--obs_output_probabilities"
        type: string
        default: "scanvi_proba"
        required: false
        description: "In which .obs slot to store the probabilities of the label predictions. Only relevant if a scANVI model was provided."
    __merge__: [., /src/base/h5_compression_argument.yaml]

  - name: "Early stopping 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: "Learning parameters"
    arguments:
      - 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/setup_logger.py
  - path: /src/utils/compress_h5mu.py
  - path: /src/utils/set_var_index.py
test_resources:
  - type: python_script
    path: test.py
  - path: /resources_test/annotation_test_data/scanvi_model
  - path: /resources_test/annotation_test_data/scanvi_covariate_model
  - path: /resources_test/annotation_test_data/scvi_model
  - path: /resources_test/pbmc_1k_protein_v3/pbmc_1k_protein_v3_mms.h5mu
  - path: /resources_test/HLCA_reference_model/HLCA_reference_model.zip

engines:
- type: docker
  image: pytorch/pytorch:2.9.1-cuda12.8-cudnn9-runtime
  setup:
    - type: python
      __merge__: [/src/base/requirements/anndata_mudata.yaml, .]
      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: [highmem, highcpu, highdisk, gpu]
