Merge method variants into parameterised components

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## BREAKING CHANGES
 
+* Merged the method variant components into parameterised components (PR #142):
+  - `methods/cycombine`, `methods/cytonorm` (with `--controls` and `--target` arguments), `methods/batchadjust` (with `--controls`) and `methods/rpca` (with `--target`) replace the 16 `*_all_controls*`/`*_no_controls*`/`*_one_control*`/`*_to_goal`/`*_to_mid` variant components.
+  - `workflows/run_benchmark` now runs each parameterised method once per named paramset and tags every score with `paramset_name` and `paramset` (`null` for non-parameterised methods), matching the results_v4 schema. The paramsets default to the `info.variants` in the method configs and can be overridden with the new `--paramsets` yaml file argument.
+  - `--methods_include`/`--methods_exclude` can target a single paramset as `<method_id>.<paramset_name>`.
+
 * Updated the file schemas (PR #94):
   - `src/api`: The common dataset is now split into two censored datasets: `censored_split1` and `censored_split2`. The method component should now be run twice, once for each split. The control methods return both splits at once. The metrics now receive both splits as input.
   - `src/control_methods`: Control methods now need to return both `integrated_split1` and `integrated_split2`.

scripts/run_benchmark/wehi_hpc/images.txt

@@ -2,26 +2,14 @@ docker://ghcr.io/openproblems-bio/openproblems/utils/extract_uns_metadata:build_
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/control_methods/no_integration:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/control_methods/perfect_integration:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/control_methods/shuffle_integration_globally:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/batchadjust_all_controls:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/batchadjust_one_control:build_setup_run_hpc
+docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/batchadjust:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/combat:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine_all_controls_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine_all_controls_to_mid:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine_no_controls_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine_no_controls_to_mid:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine_one_control_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine_one_control_to_mid:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm_all_controls_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm_all_controls_to_mid:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm_no_controls_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm_no_controls_to_mid:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm_one_control_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm_one_control_to_mid:build_setup_run_hpc
+docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cycombine:build_setup_run_hpc
+docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/cytonorm:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/gaussnorm:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/harmonypy:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/limma_remove_batch_effect:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/rpca_to_goal:build_setup_run_hpc
-docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/rpca_to_mid:build_setup_run_hpc
+docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/methods/rpca:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/metrics/average_batch_r2:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/metrics/emd:build_setup_run_hpc
 docker://ghcr.io/openproblems-bio/task_cyto_batch_integration/metrics/flowsom_mapping_similarity:build_setup_run_hpc

src/methods/batchadjust_one_control/config.vsh.yaml → src/methods/batchadjust/config.vsh.yaml

@@ -7,23 +7,24 @@ __merge__: ../../api/comp_method.yaml
 
 # A unique identifier for your component (required).
 # Can contain only lowercase letters or underscores.
-name: batchadjust_one_control
+name: batchadjust
 # A relatively short label, used when rendering visualisations (required)
-label: Batchadjust with one control
-# A one sentence summary of how this method works (required). Used when 
+label: Batchadjust
+# A one sentence summary of how this method works (required). Used when
 # rendering summary tables.
-summary: "Batchadjust with all control sample."
+summary: "CytofBatchAdjust batch correction using control samples as anchors, parameterised by control usage."
 # A multi-line description of how this component works (required). Used
 # when rendering reference documentation.
 description: |
   CytofBatchadjust corrects batch effects across cytometry data by aligning signal intensity peaks for each channel across batches.
-  The algorithm uses technical replicates included in each barcode set as reference points to anchor each batch. 
-  Adjustments factors are calibrated using anchor samples representing each barcode set, then applied to all samples composing a batch. 
+  The algorithm uses technical replicates included in each barcode set as reference points to anchor each batch.
+  Adjustments factors are calibrated using anchor samples representing each barcode set, then applied to all samples composing a batch.
 
-  This implementation uses samples only from one group as control samples.
+  This component is parameterised by `--controls`: `all` uses control samples from every
+  group as anchors, `one` uses control samples from a single group only.
 
 references:
-  doi: 
+  doi:
     - 10.3389/fimmu.2019.02367
   bibtex:
     - |
@@ -42,10 +43,22 @@ links:
   # URL to the code repository for this method (required).
   repository: https://github.com/CUHIMSR/CytofBatchAdjust
 
-
+info:
+  variants:
+    all_controls:
+      controls: all
+    one_control:
+      controls: one
 
 # Component-specific parameters (optional)
 argument_groups:
+  - name: "Parameter set"
+    arguments:
+      - type: string
+        name: --controls
+        choices: [all, one]
+        default: all
+        description: Which control samples to use as anchors. `all` uses control samples from every group, `one` keeps only the first control group.
   - name: "Parameters"
     arguments:
       - name: "--percentile"

src/methods/batchadjust_one_control/script.R → src/methods/batchadjust/script.R

@@ -4,12 +4,13 @@ library(flowCore)
 par <- list(
   input = "resources_test/task_cyto_batch_integration/mouse_spleen_flow_cytometry_subset/censored_split1.h5ad",
   output = "resources_test/debug/batchadjust/output.h5ad",
+  controls = "all",
   percentile = as.integer('80')
 )
 meta <- list(
-  name = "batchadjust_one_control",
-  temp_dir = "resources_test/tmp_batchadjust_one_control",
-  resources_dir = "src/methods/batchadjust_one_control"
+  name = "batchadjust",
+  temp_dir = "resources_test/tmp_batchadjust",
+  resources_dir = "src/methods/batchadjust"
 )
 source("src/utils/anndata_to_fcs.R")
 source("src/utils/helper_functions.R")
@@ -41,8 +42,12 @@ on.exit(clean_temp_dir(tmp_dir))
 
 
 cat("Reading input files\n")
-input <- anndata::read_h5ad(par[["input"]]) |> 
-  subset_onecontrol()
+input <- anndata::read_h5ad(par[["input"]])
+
+# keep only the first control group when using one control
+if (par[["controls"]] == "one") {
+  input <- subset_onecontrol(input)
+}
 
 #use Original_ID column to restore cell order after I/O operations
 # input$layers["preprocessed"][, "Original_ID"] <- seq(1, dim(input)[1])
@@ -52,8 +57,8 @@ original_id_in_var <- "Original_ID" %in% input$var_names
 input <- add_original_id(input)
 
 cat("Split cells\n")
-input_controls <- input[input$obs$is_control == 1, ]
-input_no_controls <- input[input$obs$is_control != 1, ]
+input_controls <- input[input$obs$is_control != 0, ]
+input_no_controls <- input[input$obs$is_control == 0, ]
 
 print("Cells in control sample:")
 print(unique(input_controls$obs$sample))
@@ -78,24 +83,23 @@ non_control_has_batch <- any(grepl("Batch", input_no_controls$obs$sample))
 if (!non_control_has_batch) {
   cat(
     "Non control samples do not have batch info in sample names!\n",
-    "Sample names before modification: ", 
+    "Sample names before modification: ",
     paste0(unique(input_no_controls$obs$sample), collapse = ", "), "\n",
     "Modifying sample names to include batch info!\n"
   )
 
   input_no_controls$obs$sample <- paste0(input_no_controls$obs$sample, "_Batch", input_no_controls$obs$batch, "_")
 
   cat(
-    "Sample names after modification:\n", 
-    paste0(unique(input_no_controls$obs$sample), collapse = ", "), 
+    "Sample names after modification:\n",
+    paste0(unique(input_no_controls$obs$sample), collapse = ", "),
     "\n"
   )
 }
 
 # make sure there is _ after the batch1 or batch2, otherwise batchadjust won't find the fcs files.
 input_no_controls$obs$sample <- sapply(input_no_controls$obs$sample, fix_batch_underscore_anynum)
 
-
 cat("Writing control FCS files\n")
 anndata_to_fcs(input_controls, out_dir = tmp_dir)
 cat("Writing non-control FCS files\n")
@@ -124,17 +128,19 @@ BatchAdjust(
   plotDiagnostics = FALSE
 )
 
+print("Corrected files:")
 print(list.files(output_dir))
+
 cat("Reading FCS files\n")
 fs <- read.flowSet(path = output_dir, pattern = "*.fcs")
 fs_all <- as(fs, "flowFrame")
 corrected_matrix <- as.data.frame(exprs(fs_all))
-#Remove column created when converting to flowframe
+# Remove column created when converting to flowframe
 corrected_matrix$Original <- NULL
 colnames(corrected_matrix) <- input$var_names
 
 cat("Converting to Anndata + ordering check\n")
-#Sort cells and check order
+# Sort cells and check order
 corrected_matrix <- corrected_matrix[order(corrected_matrix$Original_ID), ]
 order_check <- corrected_matrix$Original_ID == input$layers[['preprocessed']][, 'Original_ID']
 if (FALSE %in% order_check) {
@@ -155,6 +161,7 @@ output <- anndata::AnnData(
     dataset_id = input$uns$dataset_id,
     method_id = meta$name,
     parameters = list(
+      controls = par[["controls"]],
       percentile = par[["percentile"]]
     )
   )
@@ -163,4 +170,4 @@ output <- anndata::AnnData(
 print(output)
 output$write_h5ad(par[["output"]], compression = "gzip")
 
-cat("Written anndata of shape ", dim(output), " to file: ", par[["output"]], "\n")
+cat("Written anndata of shape ", dim(output), " to file: ", par[["output"]], "\n")