update api files

Author: rcannood

README.md

@@ -46,19 +46,20 @@ signals were preserved.
 flowchart TB
   file_common_dataset("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-common-dataset'>Common Dataset</a>")
   comp_data_processor[/"<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#component-type-data-processor'>Data processor</a>"/]
-  file_censored("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-censored'>Censored</a>")
+  file_censored_split1("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-censored--split-1-'>Censored (split 1)</a>")
+  file_censored_split2("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-censored--split-2-'>Censored (split 2)</a>")
   file_unintegrated("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-unintegrated'>Unintegrated</a>")
   comp_method[/"<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#component-type-method'>Method</a>"/]
   comp_control_method[/"<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#component-type-control-method'>Control Method</a>"/]
   comp_metric[/"<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#component-type-metric'>Metric</a>"/]
-  file_integrated_split1("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-integrated'>Integrated</a>")
-  file_integrated_split2("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-integrated'>Integrated</a>")
+  file_integrated_split1("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-integrated--split-1-'>Integrated (split 1)</a>")
+  file_integrated_split2("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-integrated--split-2-'>Integrated (split 2)</a>")
   file_score("<a href='https://github.com/openproblems-bio/task_cyto_batch_integration#file-format-score'>Score</a>")
   file_common_dataset---comp_data_processor
-  comp_data_processor-->file_censored
-  comp_data_processor-->file_censored
+  comp_data_processor-->file_censored_split1
+  comp_data_processor-->file_censored_split2
   comp_data_processor-->file_unintegrated
-  file_censored---comp_method
+  file_censored_split1---comp_method
   file_unintegrated---comp_control_method
   file_unintegrated---comp_metric
   comp_method-->file_integrated_split1
@@ -138,7 +139,7 @@ Arguments:
 
 </div>
 
-## File format: Censored
+## File format: Censored (split 1)
 
 An unintegrated dataset with certain columns (cells metadata), such as
 the donor information, hidden. These columns are intentionally hidden to
@@ -193,6 +194,61 @@ Data structure:
 
 </div>
 
+## File format: Censored (split 2)
+
+An unintegrated dataset with certain columns (cells metadata), such as
+the donor information, hidden. These columns are intentionally hidden to
+prevent bias.
+
+Example file:
+`resources_test/task_cyto_batch_integration/mouse_spleen_flow_cytometry_subset/censored_split2.h5ad`
+
+Description:
+
+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.
+
+Format:
+
+<div class="small">
+
+    AnnData object
+     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'
+
+</div>
+
+Data structure:
+
+<div class="small">
+
+| Slot | Type | Description |
+|:---|:---|:---|
+| `obs["batch"]` | `string` | Batch information. |
+| `obs["sample"]` | `string` | Sample 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. |
+| `var["marker_type"]` | `string` | Whether the marker is a functional or lineage marker. |
+| `var["to_correct"]` | `boolean` | Whether the marker will be batch corrected. |
+| `layers["preprocessed"]` | `double` | preprocessed data, e.g. already compensated, transformed and debris/doublets removed. |
+| `uns["dataset_id"]` | `string` | A unique identifier for the dataset. |
+| `uns["dataset_name"]` | `string` | Nicely formatted name. |
+| `uns["dataset_url"]` | `string` | (*Optional*) Link to the original source of the dataset. |
+| `uns["dataset_reference"]` | `string` | (*Optional*) Bibtex reference of the paper in which the dataset was published. |
+| `uns["dataset_summary"]` | `string` | Short description of the dataset. |
+| `uns["dataset_description"]` | `string` | Long description of the dataset. |
+| `uns["dataset_organism"]` | `string` | (*Optional*) The organism of the sample in the dataset. |
+
+</div>
+
 ## File format: Unintegrated
 
 The complete unintegrated dataset.
@@ -297,7 +353,7 @@ Arguments:
 
 </div>
 
-## File format: Integrated
+## File format: Integrated (split 1)
 
 Integrated dataset which batch effect was corrected by an algorithm
 
@@ -327,7 +383,7 @@ Data structure:
 
 </div>
 
-## File format: Integrated
+## File format: Integrated (split 2)
 
 Integrated dataset which batch effect was corrected by an algorithm
 

src/api/comp_data_processor.yaml

@@ -12,11 +12,11 @@ arguments:
     direction: input
     required: true
   - name: "--output_censored_split1"
-    __merge__: file_censored.yaml
+    __merge__: file_censored_split1.yaml
     direction: output
     required: true
   - name: "--output_censored_split2"
-    __merge__: file_censored.yaml
+    __merge__: file_censored_split2.yaml
     direction: output
     required: true
   - name: "--output_unintegrated"

src/api/comp_method.yaml

@@ -8,7 +8,7 @@ info:
       A method for integrating batch effects in cytometry data.
 arguments:
   - name: --input
-    __merge__: file_censored.yaml
+    __merge__: file_censored_split1.yaml
     required: true
     direction: input
   - name: --output

src/api/file_censored.yaml src/api/file_censored_split1.yamlsrc/api/file_censored.yaml renamed to src/api/file_censored_split1.yaml

@@ -1,7 +1,7 @@
 #TODO: Change to the required and/or optional fields of the anndata
 type: file
 example: "resources_test/task_cyto_batch_integration/mouse_spleen_flow_cytometry_subset/censored_split1.h5ad"
-label: Censored
+label: Censored (split 1)
 summary: |
   An unintegrated dataset with certain columns (cells metadata), such as the donor information, hidden.
   These columns are intentionally hidden to prevent bias.

src/api/file_censored_split2.yaml

@@ -0,0 +1,93 @@
+#TODO: Change to the required and/or optional fields of the anndata
+type: file
+example: "resources_test/task_cyto_batch_integration/mouse_spleen_flow_cytometry_subset/censored_split2.h5ad"
+label: Censored (split 2)
+summary: |
+  An unintegrated dataset with certain columns (cells metadata), such as the donor information, hidden.
+  These columns are intentionally hidden to prevent bias.
+description: |
+  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
+    layers:
+      - type: double
+        name: preprocessed
+        description: preprocessed data, e.g. already compensated, transformed and debris/doublets removed
+        required: true
+    obs:
+      - type: string
+        name: batch
+        description: Batch information
+        required: true
+      - type: string
+        name: sample
+        description: Sample ID
+        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
+        description: Numeric ID associated with each marker
+        required: true
+      - type: string
+        name: channel
+        description: The channel / detector of the instrument
+        required: true
+      - type: string
+        name: marker
+        description: The marker name associated with the channel
+        required: false
+      - type: string
+        name: marker_type
+        description: Whether the marker is a functional or lineage marker
+        required: true
+      - type: boolean
+        name: to_correct
+        description: Whether the marker will be batch corrected
+        required: true
+    uns:
+      - type: string
+        name: dataset_id
+        description: "A unique identifier for the dataset"
+        required: true
+      - name: dataset_name
+        type: string
+        description: Nicely formatted name.
+        required: true
+      - type: string
+        name: dataset_url
+        description: Link to the original source of the dataset.
+        required: false
+      - name: dataset_reference
+        type: string
+        description: Bibtex reference of the paper in which the dataset was published.
+        required: false
+      - name: dataset_summary
+        type: string
+        description: Short description of the dataset.
+        required: true
+      - name: dataset_description
+        type: string
+        description: Long description of the dataset.
+        required: true
+      - name: dataset_organism
+        type: string
+        description: The organism of the sample in the dataset.
+        required: false

src/api/file_integrated_split1.yaml

@@ -1,6 +1,6 @@
 type: file
 example: "resources_test/task_cyto_batch_integration/mouse_spleen_flow_cytometry_subset/integrated_split1.h5ad"
-label: Integrated
+label: Integrated (split 1)
 summary: "Integrated dataset which batch effect was corrected by an algorithm"
 info:
   format:

src/api/file_integrated_split2.yaml

@@ -1,6 +1,6 @@
 type: file
 example: "resources_test/task_cyto_batch_integration/mouse_spleen_flow_cytometry_subset/integrated_split2.h5ad"
-label: Integrated
+label: Integrated (split 2)
 summary: "Integrated dataset which batch effect was corrected by an algorithm"
 info:
   format: