name: pseudobulk_deseq2
namespace: workflows/differential_expression
scope: public
description: |
  Performs pseudobulk generation and subsequent differential expression analysis using DESeq2.
authors:
  - __merge__: /src/authors/jakub_majercik.yaml
    roles: [ author ]
  - __merge__: /src/authors/weiwei_schultz.yaml
    roles: [ contributor ]
info:
  test_dependencies:
    - name: pseudobulk_deseq2_test
      namespace:  test_workflows/differential_expression
argument_groups:
  - name: Inputs
    arguments:
      - name: --input
        type: file
        required: true
        description: Input h5mu file.
        example: /path/to/input_file.h5mu
      - name: --modality
        type: string
        default: rna
        description: Which modality from the input MuData file to process.
      - name: --input_layer
        type: string
        required: false
        description: Input layer to use. If None, X is used. This layer must contain raw counts.
      - name: --obs_cell_group
        type: string
        required: true
        description: |
          .obs field containing the variable to group on. Typically this field contains cell groups such as annotated cell types or clusters.
          If provided, will generate DESeq2 analysis per cell group.
        example: cell_type
      - name: --obs_groups
        type: string
        multiple: true
        description: .obs fields containing the experimental condition(s) to create pseudobulk samples for.
        example: ["treatment", "disease"]
      - name: "--var_gene_names"
        type: string
        description: |
          Name of the .var field that contains gene symbols. If not provided, .var.index will be used.
        required: false
        example: "gene_symbol"
  
  - name: Pseudobulk Options
    arguments:
      - name: --aggregation_method
        type: string
        choices: ["sum", "mean"]
        default: sum
        description: Method to aggregate the raw counts for pseudoreplicates. Either sum or mean.
      - name: --random_state
        type: integer
        min: 0
        default: 0
        description: The random seed for sampling.

  - name: Filtering options
    arguments:
      - name: --min_obs_per_sample
        type: integer
        min: 1
        default: 30
        description: Minimum number of observations per pseudobulk sample.
      - name: --filter_genes_min_samples
        type: integer
        min: 1
        description: |
          Minimum number of samples a gene must be expressed in to be included in the analysis.
          If None, no filtering is applied.
      - name: --filter_gene_patterns
        type: string
        multiple: true
        example: ["MIR\\d+", "AL\\d+", "LINC\\d+", "AC\\d+", "AP\\d+"]
        description: |
          List of regex patterns to filter out genes.
          Genes matching any of these patterns will be excluded from the analysis.
        required: false

  - name: DGEA options
    arguments:
      - name: --design_formula
        type: string
        required: true
        description: |
          Design formula for DESeq2 analysis in R-style format.
          Specifies the statistical model to account for various factors.
        example: "~ cell_type + disease + treatment"
      - name: --contrast_column
        type: string
        required: true
        description: |
          Column in the metadata to use for the contrast.
          This column should contain the conditions to compare.
        example: "treatment"
      - name: --contrast_values
        type: string
        multiple: true
        required: true
        description: |
          Values to compare in the contrast column.
          First value is baseline, following values are different treatments.
        example: ["ctrl", "stim"]
      - name: --p_adj_threshold
        type: double
        default: 0.05
        description: |
          Adjusted p-value threshold for significance.
          Genes with adjusted p-values below this threshold will be considered significant.
        required: false
      - name: --log2fc_threshold
        type: double
        default: 0.0
        description: |
          Log2 fold change threshold for significance.
          Genes with absolute log2 fold change above this threshold will be considered significant.
        required: false

  - name: Outputs
    arguments:
      - name: "--output"
        alternatives: ["-o"]
        type: file
        description: |
          Output directory for DESeq2 results, containing one CSV file per cell group (as defined by `--obs_cell_group`) 
        direction: output
        required: true
      - name: "--output_prefix"
        type: string
        description: |
          Prefix for output CSV files: files will be named "{prefix}_{cell_group}.csv"
        default: "deseq2_analysis"
        required: false

dependencies:
  - name: differential_expression/create_pseudobulk
  - name: differential_expression/deseq2
  - name: filter/filter_with_counts
  - name: filter/filter_with_pattern
  - name: filter/delimit_counts
  - name: filter/do_filter

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

runners:
  - type: nextflow