name: filter_with_quantile
namespace: "filter"
scope: "public"
description: |
  Filter observations or features from an .h5mu file based on quantile thresholds of numeric values.
  
  This component removes observations or features that fall outside specified quantile ranges in .obs or .var. columns.
  
  For example, you can filter out observations with total UMI counts in the bottom 5% (quantile < 0.05) or 
  top 5% (quantile > 0.95), or retain an intermediate range (0.1 < quantile < 0.9).

authors:
  - __merge__: /src/authors/dorien_roosen.yaml
    roles: [ author ]

argument_groups:
  - name: Inputs
    arguments:
      - name: "--input"
        type: file
        description: Input h5mu file
        direction: input
        required: true
        example: input.h5mu
      - name: "--modality"
        description: |
          Which modality from the input MuData file to process.
        type: string
        default: "rna"
        required: false
      - name: "--obs_column"
        type: string
        description: |
          Name of the column in .obs to use for quantile-based filtering.
          If not specified, no .obs filtering will be performed.
        example: "total_counts"
        required: false
      - name: "--var_column"
        type: string
        description: |
          Name of the column in .var to use for quantile-based filtering.
          If not specified, no .var filtering will be performed.
        example: "mean_counts"
        required: false


  - name: Filters
    arguments:
      - name: "--do_subset"
        type: boolean_true
        description: Whether to subset before storing the output.
      - name: "--obs_log1p_transform"
        type: boolean
        default: true
        description: |
          Apply log1p transformation to the obs_column values before calculating quantiles.
          The transformed values will be stored as 'log1p_{obs_column}' in .obs.
          This is useful for highly skewed data where log transformation can improve quantile-based filtering.
        required: false
      - name: "--obs_min_quantile"
        type: double
        description: |
          Minimum quantile threshold for .obs filtering. Observations with values below this quantile will be removed.
          Value should be between 0.0 and 1.0.
        min: 0
        max: 1
        example: 0.05
        required: false
      - name: "--obs_max_quantile"
        type: double
        description: |
          Maximum quantile threshold for .obs filtering. Observations with values above this quantile will be removed.
          Value should be between 0.0 and 1.0.
        min: 0
        max: 1
        example: 0.95
        required: false
      - name: "--var_log1p_transform"
        type: boolean
        default: true
        description: |
          Apply log1p transformation to the var_column values before calculating quantiles.
          The transformed values will be stored as 'log1p_{var_column}' in .var.
          This is useful for highly skewed data where log transformation can improve quantile-based filtering.
        required: false
      - name: "--var_min_quantile"
        type: double
        description: |
          Minimum quantile threshold for .var filtering. Features with values below this quantile will be removed.
          Value should be between 0.0 and 1.0.
        min: 0
        max: 1
        example: 0.01
        required: false
      - name: "--var_max_quantile"
        type: double
        description: |
          Maximum quantile threshold for .var filtering. Features with values above this quantile will be removed.
          Value should be between 0.0 and 1.0.
        min: 0
        max: 1
        example: 0.99
        required: false
      - name: "--min_values_for_quantile"
        type: integer
        description: |
          Minimum number of values required to apply quantile filtering. If fewer values are present,
          quantile filtering will be skipped to prevent data loss. 
        default: 10
        min: 2
        required: false
  
  - name: Outputs
    arguments:
      - name: "--output"
        type: file
        description: Output h5mu file.
        direction: output
        example: output.h5mu
      - name: "--obs_name_filter"
        type: string
        default: "filter_with_quantile"
        description: In which .obs slot to store a boolean array corresponding to which observations should be removed.
      - name: "--obs_log1p_column"
        type: string
        description: |
          Name for the column where log1p transformed obs values will be stored.
          If not provided, defaults to 'log1p_{obs_column}'.
        example: "log1p_total_counts"
      - name: "--var_log1p_column"
        type: string
        description: |
          Name for the column where log1p transformed var values will be stored.
          If not provided, defaults to 'log1p_{var_column}'.
        example: "log1p_total_counts"
      - name: "--var_name_filter"
        type: string
        default: "filter_with_quantile"
        description: In which .var slot to store a boolean array corresponding to which variables should be removed.
    __merge__: [., /src/base/h5_compression_argument.yaml]

resources:
  - type: python_script
    path: script.py
  - path: /src/utils/setup_logger.py
  - path: /src/utils/compress_h5mu.py
test_resources:
  - type: python_script
    path: test.py
  - path: /resources_test/pbmc_1k_protein_v3/pbmc_1k_protein_v3_filtered_feature_bc_matrix.h5mu

engines:
- type: docker
  image: python:3.13-slim
  setup:
    - type: apt
      packages: 
        - procps
    - type: python
      __merge__: /src/base/requirements/anndata_mudata.yaml
  __merge__: [ /src/base/requirements/python_test_setup.yaml, .]

runners:
- type: executable
- type: nextflow
  directives:
    label: [singlecpu, lowmem]