name: "scvi_leiden"
namespace: "workflows/integration"
scope: "public"
description: "Run scvi integration followed by neighbour calculations, leiden clustering and run umap on the result."
authors:
  - __merge__: /src/authors/dries_schaumont.yaml
    roles: [ author ]
info:
  test_dependencies:
argument_groups:
  - name: "Inputs"
    arguments:
      - name: "--input"
        type: file
        description: Path to the sample. Mutually exclusive with the 'input_uri' argument.
        example: dataset.h5mu
      - name: "--tiledb_input_uri"
        type: string
        description: "A URI containing the TileDB-SOMA objects. Mutually exclusive with the 'input' argument."
        example: "s3://bucket/path"
      - name: "--tiledb_s3_region"
        type: string
        description: |
          Region where the TileDB-SOMA database is hosted.
        type: string
        example: "us-west-2"
      - name: "--tiledb_endpoint"
        type: string
        description: |
          Custom endpoint to use to connect to S3
        required: false
      - name: "--tiledb_s3_no_sign_request"
        description: | 
          Do not sign S3 requests. Credentials will not be loaded if this argument is provided.
        type: boolean
        default: false
  - name: Input slots
    arguments:
      - name: "--layer"
        type: string
        description: use specified layer for expression values instead of the .X object from the modality.
        required: false
      - name: "--modality"
        description: Which modality to process.
        type: string
        default: "rna"
        required: false
      - name: "--sanitize_ensembl_ids"
        type: boolean
        description: Whether to sanitize ensembl ids by removing version numbers.
        default: true

  - name: "Outputs"
    arguments:
      - name: "--output"
        type: file
        required: true
        direction: output
        description: Destination path to the output.
        example: output.h5mu
      - name: "--output_model"
        type: file
        description: Folder where the state of the trained model will be saved to.
        required: true
        direction: output
        example: output_dir/
      - name: "--output_tiledb"
        type: file
        direction: output
        description: |
          Output the TileDB database to the specified directory instead of adding it to the existing database.
        required: false

  - name: Neighbour calculation
    arguments:
      - name: "--uns_neighbors"
        type: string
        default: scvi_integration_neighbors
        description: In which .uns slot to store various neighbor output objects.
      - name: "--obsp_neighbor_distances"
        type: string
        default: "scvi_integration_distances"
        description: "In which .obsp slot to store the distance matrix between the resulting neighbors."
      - name: "--obsp_neighbor_connectivities"
        type: string
        default: "scvi_integration_connectivities"
        description: "In which .obsp slot to store the connectivities matrix between the resulting neighbors."
  - name: Scvi integration options
    arguments:
      - name: "--obs_batch"
        type: string
        description: Column name discriminating between your batches.
        required: true
      - name: "--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: "--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.
      - name: "--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.
      - name: "--obsm_output"
        type: string
        default: "X_scvi_integrated"
        required: false
        description: "In which .obsm slot to store the resulting integrated embedding."
      - name: "--var_input"
        type: string
        required: false
        description: ".var column containing highly variable genes. By default, do not subset genes."
      - 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: Clustering options
    arguments:
      - name: "--obs_cluster"
        type: string
        description: |
          Prefix for the .obs keys under which to add the cluster labels. Newly created columns in .obs will 
          be created from the specified value for '--obs_cluster' suffixed with an underscore and one of the resolutions
          resolutions specified in '--leiden_resolution'.
        default: "scvi_integration_leiden"
      - name: "--leiden_resolution"
        type: double
        description: Control the coarseness of the clustering. Higher values lead to more clusters.
        default: [1]
        multiple: true
  - name: Umap options
    arguments:
      - name: "--obsm_umap"
        type: string
        default: "X_scvi_umap"
        required: false
        description: "In which .obsm slot to store the resulting UMAP embedding."
dependencies:
  - name: integrate/scvi
  - name: workflows/multiomics/neighbors_leiden_umap
  - name: convert/from_tiledb_to_h5mu
  - name: tiledb/move_mudata_obsm_to_tiledb
  - name: tiledb/move_mudata_obs_to_tiledb

resources:
  - type: nextflow_script
    path: main.nf
    entrypoint: run_wf
  - type: file
    path: /src/workflows/utils/
test_resources:
  - type: nextflow_script
    path: test.nf
    entrypoint: test_wf
  - type: nextflow_script
    path: test.nf
    entrypoint: test_tiledb_wf
  - path: /resources_test/pbmc_1k_protein_v3
runners:
  - type: nextflow