Merge branch 'main' into add-emd-per-matching-sample-metric

openproblems-bio · Feb 6, 2025 · 2627e99 · 2627e99
2 parents 6dc6678 + fdcac67
commit 2627e99
Show file tree

Hide file tree

Showing 10 changed files with 156 additions and 81 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,13 +21,27 @@
 
 ## MAJOR CHANGES
 
-* Improved `metrics/emd_per_samples` component (PR #16)
+* Updated file schema (PR #18): 
+  * Add is_control obs to indicate whether a cell should be used as control when correcting batch effect.
+  * Removed donor_id obs from unintegrated censored.
+  * Removed to_correct var from everything except common_dataset. 
+  All datasets now will only contain markers that need to be corrected.
+
+* Reupdated the file schema (PR #19):
+  * Included changes in PR #21: data Processor component partitions cells between unintegrated(censored) 
+  and validation.
+  * Add back to_correct var to every file except integrated to reflect the real world 
+  batch correction workflow better.
+  * Reverted PR #18 to retain only the 1st two changes (add is_control and remove 
+  donor_id from unintegrated_censored).
 
 ## MINOR CHANGES
 
 * Enabled unit tests (PR #2).
 
 * Added integrated test resource (PR #5).
 
+* Updated file description in yaml file (PR #15).
+
 ## BUGFIXES
 
diff --git a/README.md b/README.md
@@ -73,7 +73,7 @@ Format:
 <div class="small">
 
     AnnData object
-     obs: 'cell_type', 'batch', 'sample', 'donor', 'group'
+     obs: 'cell_type', 'batch', 'sample', 'donor', 'group', 'is_control', 'is_validation'
      var: 'numeric_id', 'channel', 'marker', 'marker_type', 'to_correct'
      layers: 'preprocessed'
      uns: 'dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism'
@@ -91,6 +91,8 @@ Data structure:
 | `obs["sample"]` | `string` | Sample ID. |
 | `obs["donor"]` | `string` | Donor ID. |
 | `obs["group"]` | `string` | Biological group of the donor. |
+| `obs["is_control"]` | `integer` | Whether the sample the cell came from can be used as a control for batch effect correction. 0: cannot be used as a control. \>= 1: can be used as a control. For cells with \>= 1: cells with the same value come from the same donor. Different values indicate different donors. |
+| `obs["is_validation"]` | `boolean` | Whether the cell will be used as validation data or not. If FALSE, then the cell will only be included in unintegrated and unintegrated_censored. If TRUE, then the cell will only be included in validation. |
 | `var["numeric_id"]` | `integer` | Numeric ID associated with each marker. |
 | `var["channel"]` | `string` | The channel / detector of the instrument. |
 | `var["marker"]` | `string` | (*Optional*) The marker name associated with the channel. |
@@ -118,25 +120,30 @@ Arguments:
 | Name | Type | Description |
 |:---|:---|:---|
 | `--input` | `file` | A subset of the common dataset. |
-| `--output_unintegrated_censored` | `file` | (*Output*) Unintegrated dataset. |
-| `--output_unintegrated` | `file` | (*Output*) Unintegrated dataset. |
+| `--output_unintegrated_censored` | `file` | (*Output*) An unintegrated dataset with certain columns (cells metadata), such as the donor information, hidden. These columns are intentionally hidden to prevent bias. The batch correction algorithm should not have to rely on these information to properly integrate different batches. This dataset is used as the input for the batch correction algorithm. The cells therein are identical to those in the unintegrated dataset. |
+| `--output_unintegrated` | `file` | (*Output*) The complete unintegrated dataset, including all cells’ metadata (columns) from the unintegrated_censored dataset. The cells in this dataset are the same to those in the unintegrated_censored dataset. |
 | `--output_validation` | `file` | (*Output*) Hold-out dataset for validation. |
 
 </div>
 
 ## File format: Unintegrated Censored
 
-Unintegrated dataset
+An unintegrated dataset with certain columns (cells metadata), such as
+the donor information, hidden. These columns are intentionally hidden to
+prevent bias. The batch correction algorithm should not have to rely on
+these information to properly integrate different batches. This dataset
+is used as the input for the batch correction algorithm. The cells
+therein are identical to those in the unintegrated dataset.
 
 Example file:
-`resources_test/task_cyto_batch_integration/cxg_mouse_pancreas_atlas/train.h5ad`
+`resources_test/task_cyto_batch_integration/starter_file/unintegrated_censored.h5ad`
 
 Format:
 
 <div class="small">
 
     AnnData object
-     obs: 'batch', 'sample', 'donor'
+     obs: 'batch', 'sample', 'is_control'
      var: 'numeric_id', 'channel', 'marker', 'marker_type', 'to_correct'
      layers: 'preprocessed'
      uns: 'dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism'
@@ -151,7 +158,7 @@ Data structure:
 |:---|:---|:---|
 | `obs["batch"]` | `string` | Batch information. |
 | `obs["sample"]` | `string` | Sample ID. |
-| `obs["donor"]` | `string` | (*Optional*) Donor ID. |
+| `obs["is_control"]` | `integer` | Whether the sample the cell came from can be used as a control for batch effect correction. 0: cannot be used as a control. \>= 1: can be used as a control. For cells with \>= 1: cells with the same value come from the same donor. Different values indicate different donors. |
 | `var["numeric_id"]` | `integer` | Numeric ID associated with each marker. |
 | `var["channel"]` | `string` | The channel / detector of the instrument. |
 | `var["marker"]` | `string` | (*Optional*) The marker name associated with the channel. |
@@ -170,17 +177,19 @@ Data structure:
 
 ## File format: Unintegrated
 
-Unintegrated dataset
+The complete unintegrated dataset, including all cells’ metadata
+(columns) from the unintegrated_censored dataset. The cells in this
+dataset are the same to those in the unintegrated_censored dataset.
 
 Example file:
-`resources_test/task_cyto_batch_integration/cxg_mouse_pancreas_atlas/train.h5ad`
+`resources_test/task_cyto_batch_integration/starter_file/unintegrated.h5ad`
 
 Format:
 
 <div class="small">
 
     AnnData object
-     obs: 'cell_type', 'batch', 'sample', 'donor', 'group'
+     obs: 'cell_type', 'batch', 'sample', 'donor', 'group', 'is_control'
      var: 'numeric_id', 'channel', 'marker', 'marker_type', 'to_correct'
      layers: 'preprocessed'
      uns: 'dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism'
@@ -198,6 +207,7 @@ Data structure:
 | `obs["sample"]` | `string` | Sample ID. |
 | `obs["donor"]` | `string` | Donor ID. |
 | `obs["group"]` | `string` | Biological group of the donor. |
+| `obs["is_control"]` | `integer` | Whether the sample the cell came from can be used as a control for batch effect correction. 0: cannot be used as a control. \>= 1: can be used as a control. For cells with \>= 1: cells with the same value come from the same donor. Different values indicate different donors. |
 | `var["numeric_id"]` | `integer` | Numeric ID associated with each marker. |
 | `var["channel"]` | `string` | The channel / detector of the instrument. |
 | `var["marker"]` | `string` | (*Optional*) The marker name associated with the channel. |
@@ -219,21 +229,29 @@ Data structure:
 Hold-out dataset for validation.
 
 Example file:
-`resources_test/task_cyto_batch_integration/cxg_mouse_pancreas_atlas/solution.h5ad`
+`resources_test/task_cyto_batch_integration/starter_file/validation.h5ad`
 
 Description:
 
-Samples that were held out and will later be used only to assess whether
-the batch integration was successful. E.g. if a donor from batch 2 was
-corrected towards batch 1, but also actually measured in batch 1
-(without being used as input to the algorithm).
+Dataset containing cells from samples that were held out for evaluating
+batch integration output. The cells that are in this dataset belong to
+samples which are not included in the unintegrated or
+unintegrated_censored datasets. For example, if samples from donor A are
+present in batch 1 and 2, the sample from batch 1 may be used as input
+for the batch correction algorithm (and thus present in unintegrated and
+unintegrated_censored datasets). The sample from batch 2, may not be
+included as an input for the batch correction algorithm, but is needed
+to validate whether whether the algorithm managed to correct the batch
+effect in batch 2 towards batch 1. This sample will then be included in
+this dataset (but not in unintegrated and unintegrated_censored
+datasets).
 
 Format:
 
 <div class="small">
 
     AnnData object
-     obs: 'cell_type', 'batch', 'sample', 'donor', 'group'
+     obs: 'cell_type', 'batch', 'sample', 'donor', 'group', 'is_control'
      var: 'numeric_id', 'channel', 'marker', 'marker_type', 'to_correct'
      layers: 'preprocessed'
      uns: 'dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism'
@@ -251,6 +269,7 @@ Data structure:
 | `obs["sample"]` | `string` | Sample ID. |
 | `obs["donor"]` | `string` | Donor ID. |
 | `obs["group"]` | `string` | Biological group of the donor. |
+| `obs["is_control"]` | `integer` | Whether the sample the cell came from can be used as a control for batch effect correction. 0: cannot be used as a control. \>= 1: can be used as a control. For cells with \>= 1: cells with the same value come from the same donor. Different values indicate different donors. |
 | `var["numeric_id"]` | `integer` | Numeric ID associated with each marker. |
 | `var["channel"]` | `string` | The channel / detector of the instrument. |
 | `var["marker"]` | `string` | (*Optional*) The marker name associated with the channel. |
@@ -269,16 +288,16 @@ Data structure:
 
 ## Component type: Method
 
-A method.
+A method for integrating batch effects in cytometry data.
 
 Arguments:
 
 <div class="small">
 
-| Name       | Type   | Description                    |
-|:-----------|:-------|:-------------------------------|
-| `--input`  | `file` | Unintegrated dataset.          |
-| `--output` | `file` | (*Output*) Integrated dataset. |
+| Name | Type | Description |
+|:---|:---|:---|
+| `--input` | `file` | An unintegrated dataset with certain columns (cells metadata), such as the donor information, hidden. These columns are intentionally hidden to prevent bias. The batch correction algorithm should not have to rely on these information to properly integrate different batches. This dataset is used as the input for the batch correction algorithm. The cells therein are identical to those in the unintegrated dataset. |
+| `--output` | `file` | (*Output*) Integrated dataset which batch effect was corrected by an algorithm. |
 
 </div>
 
@@ -290,11 +309,11 @@ Arguments:
 
 <div class="small">
 
-| Name                   | Type   | Description                      |
-|:-----------------------|:-------|:---------------------------------|
-| `--input_unintegrated` | `file` | Unintegrated dataset.            |
-| `--input_validation`   | `file` | Hold-out dataset for validation. |
-| `--output`             | `file` | (*Output*) Integrated dataset.   |
+| Name | Type | Description |
+|:---|:---|:---|
+| `--input_unintegrated` | `file` | The complete unintegrated dataset, including all cells’ metadata (columns) from the unintegrated_censored dataset. The cells in this dataset are the same to those in the unintegrated_censored dataset. |
+| `--input_validation` | `file` | Hold-out dataset for validation. |
+| `--output` | `file` | (*Output*) Integrated dataset which batch effect was corrected by an algorithm. |
 
 </div>
 
@@ -309,18 +328,18 @@ Arguments:
 | Name | Type | Description |
 |:---|:---|:---|
 | `--input_validation` | `file` | Hold-out dataset for validation. |
-| `--input_unintegrated` | `file` | Unintegrated dataset. |
-| `--input_integrated` | `file` | Integrated dataset. |
+| `--input_unintegrated` | `file` | The complete unintegrated dataset, including all cells’ metadata (columns) from the unintegrated_censored dataset. The cells in this dataset are the same to those in the unintegrated_censored dataset. |
+| `--input_integrated` | `file` | Integrated dataset which batch effect was corrected by an algorithm. |
 | `--output` | `file` | (*Output*) File indicating the score of a metric. |
 
 </div>
 
 ## File format: Integrated
 
-Integrated dataset
+Integrated dataset which batch effect was corrected by an algorithm
 
 Example file:
-`resources_test/task_cyto_batch_integration/cxg_mouse_pancreas_atlas/prediction.h5ad`
+`resources_test/task_cyto_batch_integration/starter_file/integrated.h5ad`
 
 Format:
 
@@ -350,14 +369,14 @@ Data structure:
 File indicating the score of a metric.
 
 Example file:
-`resources_test/task_cyto_batch_integration/cxg_mouse_pancreas_atlas/score.h5ad`
+`resources_test/task_cyto_batch_integration/starter_file/score.h5ad`
 
 Format:
 
 <div class="small">
 
     AnnData object
-     uns: 'dataset_id', 'normalization_id', 'method_id', 'metric_ids', 'metric_values'
+     uns: 'dataset_id', 'method_id', 'sample_ids', 'metric_ids', 'metric_values'
 
 </div>
 
@@ -368,10 +387,10 @@ Data structure:
 | Slot | Type | Description |
 |:---|:---|:---|
 | `uns["dataset_id"]` | `string` | A unique identifier for the dataset. |
-| `uns["normalization_id"]` | `string` | Which normalization was used. |
-| `uns["method_id"]` | `string` | A unique identifier for the method. |
+| `uns["method_id"]` | `string` | A unique identifier for the batch correction method. |
+| `uns["sample_ids"]` | `string` | The samples assessed by the metric. |
 | `uns["metric_ids"]` | `string` | One or more unique metric identifiers. |
-| `uns["metric_values"]` | `double` | The metric values obtained for the given prediction. Must be of same length as ‘metric_ids’. |
+| `uns["metric_values"]` | `double` | The metric values obtained. Must be of same length as ‘metric_ids’. |
 
 </div>
 
diff --git a/src/api/file_common_dataset.yaml b/src/api/file_common_dataset.yaml
@@ -31,6 +31,23 @@ info:
         name: group
         description: Biological group of the donor
         required: true
+      - type: integer
+        name: is_control
+        description: |
+          Whether the sample the cell came from can be used as a control for batch 
+          effect correction.
+          0: cannot be used as a control.
+          >= 1: can be used as a control.
+          For cells with >= 1: cells with the same value come from the same donor.
+          Different values indicate different donors.
+        required: true
+      - type: boolean
+        name: is_validation
+        description: |
+          Whether the cell will be used as validation data or not.
+          If FALSE, then the cell will only be included in unintegrated and unintegrated_censored.
+          If TRUE, then the cell will only be included in validation.
+        required: true
     var:
       - type: integer
         name: numeric_id
@@ -52,11 +69,6 @@ info:
         name: to_correct
         description: Whether the marker will be batch corrected
         required: true
-    # obsm:
-    #   - type: double
-    #     name: X_pca
-    #     description: The resulting PCA embedding.
-    #     required: true
     uns:
       - type: string
         name: dataset_id

diff --git a/src/api/file_integrated.yaml b/src/api/file_integrated.yaml
@@ -1,7 +1,7 @@
 type: file
 example: "resources_test/task_cyto_batch_integration/starter_file/integrated.h5ad"
 label: Integrated
-summary: "Integrated dataset"
+summary: "Integrated dataset which batch effect was corrected by an algorithm"
 info:
   format:
     type: h5ad

diff --git a/src/api/file_unintegrated.yaml b/src/api/file_unintegrated.yaml
@@ -1,9 +1,11 @@
 #TODO: Change to the required and/or optional fields of the anndata
 type: file
 example: "resources_test/task_cyto_batch_integration/starter_file/unintegrated.h5ad"
-label: "Unintegrated"
-summary: "Unintegrated dataset"
-
+label: Unintegrated
+summary: |
+  The complete unintegrated dataset, including all cells' metadata (columns) from the 
+  unintegrated_censored dataset. 
+  The cells in this dataset are the same to those in the unintegrated_censored dataset.
 info:
   format:
     type: h5ad
@@ -33,6 +35,16 @@ info:
         name: group
         description: Biological group of the donor
         required: true
+      - type: integer
+        name: is_control
+        description: |
+          Whether the sample the cell came from can be used as a control for batch 
+          effect correction.
+          0: cannot be used as a control.
+          >= 1: can be used as a control.
+          For cells with >= 1: cells with the same value come from the same donor.
+          Different values indicate different donors.
+        required: true
     var:
       - type: integer
         name: numeric_id
@@ -54,11 +66,6 @@ info:
         name: to_correct
         description: Whether the marker will be batch corrected
         required: true
-    # obsm:
-    #   - type: double
-    #     name: X_pca
-    #     description: The resulting PCA embedding.
-    #     required: true
     uns:
       - type: string
         name: dataset_id

diff --git a/src/api/file_unintegrated_censored.yaml b/src/api/file_unintegrated_censored.yaml
@@ -1,8 +1,14 @@
 #TODO: Change to the required and/or optional fields of the anndata
 type: file
 example: "resources_test/task_cyto_batch_integration/starter_file/unintegrated_censored.h5ad"
-label: "Unintegrated Censored"
-summary: "Unintegrated dataset"
+label: Unintegrated Censored
+summary: |
+  An unintegrated dataset with certain columns (cells metadata), such as the donor information, hidden.
+  These columns are intentionally hidden to prevent bias.
+  The batch correction algorithm should not have to rely on these information 
+  to properly integrate different batches.
+  This dataset is used as the input for the batch correction algorithm. 
+  The cells therein are identical to those in the unintegrated dataset. 
 info:
   format:
     type: h5ad
@@ -20,10 +26,16 @@ info:
         name: sample
         description: Sample ID
         required: true
-      - type: string
-        name: donor
-        description: Donor ID
-        required: false
+      - type: integer
+        name: is_control
+        description: |
+          Whether the sample the cell came from can be used as a control for batch 
+          effect correction.
+          0: cannot be used as a control.
+          >= 1: can be used as a control.
+          For cells with >= 1: cells with the same value come from the same donor.
+          Different values indicate different donors.
+        required: true
     var:
       - type: integer
         name: numeric_id
@@ -45,11 +57,6 @@ info:
         name: to_correct
         description: Whether the marker will be batch corrected
         required: true
-    # obsm:
-    #   - type: double
-    #     name: X_pca
-    #     description: The resulting PCA embedding.
-    #     required: true
     uns:
       - type: string
         name: dataset_id