Fix control methods (#109)

* improve description and enabling all control methods

* update changelog again

* re-enabling the shuffle by batch

Author: ghar1821

CHANGELOG.md

@@ -155,6 +155,8 @@
 
 * Fix missing anndata in yaml file and set the base_r docker image version to 1 instead of 1.0.0 (PR #89).
 
-* Fix bug in control methods (PR #107 and PR #108).
+* Fix bug in control methods (PR #107, #108, #109).
+  * All control methods are updated to cater the new schema.
+  * All control methods are re-enabled. Selectively disable them when running the pipeline using method exclude.
 
 

src/control_methods/shuffle_integration/config.vsh.yaml

@@ -1,9 +1,20 @@
 __merge__: /src/api/comp_control_method.yaml
 name: shuffle_integration
-label: Shuffle integration
-summary: Integrations are randomly permuted
-description: Integrations are randomly permuted
-status: disabled
+label: Shuffle Integration
+summary: Randomly shuffle cells in the whole dataset.
+description: |
+  This negative control randomly permutes cell-to-sample (hence batch)
+  assignments while keeping each cell's measured markers unchanged. 
+  This destroys any biological and batch specific structure but preserves marker expression.
+
+  Purpose:
+  - Provide a baseline to verify that integration methods outperform
+    random assignment of cells to batches.
+  
+  Example:
+    - A cell from a KO sample in batch 1 may be reassigned to any sample in the whole data.
+    It may be reassigned to another KO sample in batch 1 or 2, or to a WT sample in batch 1 or 2.
+# status: disabled
 resources:
   - type: python_script
     path: script.py

src/control_methods/shuffle_integration_by_batch/config.vsh.yaml

@@ -1,8 +1,20 @@
 __merge__: /src/api/comp_control_method.yaml
 name: shuffle_integration_by_batch
-label: Shuffle integration by batch
-summary: Integrations are randomly permuted within each batch
-description: Integrations are randomly permuted within each batch
+label: Shuffle Integration — within batches
+summary: Randomly reassign cells to any samples within the same batch.
+description: | 
+  This negative-control method randomly permutes cell-to-cell type assignments.
+  Cells remain assigned to their original batch (batch effects preserved).
+  Within each batch, cells are reassigned to random samples, destroying
+  biological/sample-specific structure (e.g., KO vs WT differences).
+
+  Purpose:
+  - Evaluate whether an integration method preserves differences between samples
+    and biological groups while removing batch effects.
+
+  Example:
+  - A cell from a KO sample in batch 1 may be reassigned to any sample in batch 1
+    (KO or WT), but it will never be moved to batch 2.
 # status: disabled
 resources:
   - type: python_script

src/control_methods/shuffle_integration_by_cell_type/config.vsh.yaml

@@ -1,8 +1,19 @@
 __merge__: /src/api/comp_control_method.yaml
 name: shuffle_integration_by_cell_type
-label: Shuffle integration by cell type
-summary: Integrations are randomly permuted within each cell type
-description: Integrations are randomly permuted within each cell type
+label: Shuffle Integration — within cell type
+summary: Randomly reassign cells to any cell types
+description: | 
+  This negative-control method randomly permutes cell-to-cell type assignments.
+  Cells will be assigned to any cell types, regardless of their original cell type
+  or sample of origin or batch of origin.
+
+  Purpose:
+  - Evaluate whether an integration method preserves differences between cell types
+  while removing batch effects.
+
+  Example:
+  - A Neutrophil from a KO sample in batch 1 may be reassigned to any cell type
+    (B cell, T cell, Monocyte, etc.) from any sample in any batch.
 # status: disabled
 resources:
   - type: python_script

src/workflows/run_benchmark/config.vsh.yaml

@@ -82,7 +82,7 @@ resources:
 dependencies:
   - name: utils/extract_uns_metadata
     repository: op
-  # - name: control_methods/shuffle_integration
+  - name: control_methods/shuffle_integration
   - name: control_methods/shuffle_integration_by_batch
   - name: control_methods/shuffle_integration_by_cell_type
   - name: control_methods/no_integration

src/workflows/run_benchmark/main.nf

@@ -9,7 +9,7 @@ workflow auto {
 
 // construct list of methods and control methods
 methods = [
-  // shuffle_integration,
+  shuffle_integration,
   shuffle_integration_by_batch,
   shuffle_integration_by_cell_type,
   harmonypy,