From c4d4d105cfa31525db026b9c7d153a21dfd8d317 Mon Sep 17 00:00:00 2001 From: Robrecht Cannoodt Date: Wed, 29 Jul 2026 14:23:43 +0200 Subject: [PATCH] label file_test_mod2 as the solution It holds the ground truth, but "Test mod2" reads like just another input. Also regenerate the README, which had drifted from the api yamls for unrelated reasons. --- CHANGELOG.md | 8 ++ README.md | 152 ++++++++++++++++++------------------ src/api/file_test_mod2.yaml | 7 +- 3 files changed, 91 insertions(+), 76 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e9a8396c..13abcffb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +# task_predict_modality 0.2.0 + +## MINOR CHANGES + +* `file_test_mod2`: Label this file "Solution" and say in the description that only the metrics and control methods receive it. It holds the ground truth, but read like just another input (PR #49). + +* Regenerate `README.md`. It had drifted from the api yamls independently of this change -- author table layout, node ordering, and a contributor added in PR #10 (PR #49). + # task_predict_modality 0.1.1 ## NEW FUNCTIONALITY diff --git a/README.md b/README.md index 11451c08..b905fb15 100644 --- a/README.md +++ b/README.md @@ -30,19 +30,20 @@ data shows that this is not trivial. ## Authors & contributors -| name | roles | -|:-------------------|:-------------------| -| Alejandro Granados | author | -| Alex Tong | author | -| Bastian Rieck | author | -| Christopher Lance | author | -| Daniel Burkhardt | author | -| Kai Waldrant | contributor | -| Kaiwen Deng | contributor | -| Louise Deconinck | author | -| Robrecht Cannoodt | author, maintainer | -| Xueer Chen | contributor | -| Jiwei Liu | contributor | +| Name | Roles | Github | Orcid | Email | +|:---|:---|:---|:---|:---| +| Alejandro Granados | author | agranado | | | +| Alex Tong | author | atong01 | | | +| Bastian Rieck | author | Pseudomanifold | | | +| Christopher Lance | author | xlancelottx | 0000-0002-1275-9802 | | +| Daniel Burkhardt | author | dburkhardt | | | +| Kai Waldrant | contributor | KaiWaldrant | 0009-0003-8555-1361 | | +| Kaiwen Deng | contributor | nonztalk | | dengkw@umich.edu | +| Louise Deconinck | author | LouiseDck | | | +| Robrecht Cannoodt | author, maintainer | rcannood | 0000-0003-3641-729X | | +| Xueer Chen | contributor | xuerchen | | xc2579@columbia.edu | +| Jiwei Liu | contributor | daxiongshu | 0000-0002-8799-9763 | jiweil@nvidia.com | +| Marius Lange | contributor | marius1311 | 0000-0002-4846-1266 | | ## API @@ -50,42 +51,42 @@ data shows that this is not trivial. flowchart TB file_common_dataset_mod1("Raw dataset RNA") comp_process_datasets[/"Process Dataset"/] - file_test_mod1("Test mod1") - file_test_mod2("Test mod2") file_train_mod1("Train mod1") file_train_mod2("Train mod2") + file_test_mod1("Test mod1") + file_test_mod2("Solution") comp_control_method[/"Control method"/] + comp_method[/"Method"/] comp_method_predict[/"Predict"/] comp_method_train[/"Train"/] - comp_method[/"Method"/] comp_metric[/"Metric"/] file_prediction("Prediction") file_pretrained_model("Pretrained model") file_score("Score") file_common_dataset_mod2("Raw dataset mod2") file_common_dataset_mod1---comp_process_datasets - comp_process_datasets-->file_test_mod1 - comp_process_datasets-->file_test_mod2 comp_process_datasets-->file_train_mod1 comp_process_datasets-->file_train_mod2 - file_test_mod1---comp_control_method - file_test_mod1---comp_method_predict - file_test_mod1-.-comp_method_train - file_test_mod1---comp_method - file_test_mod2---comp_control_method - file_test_mod2---comp_metric + comp_process_datasets-->file_test_mod1 + comp_process_datasets-->file_test_mod2 file_train_mod1---comp_control_method + file_train_mod1---comp_method file_train_mod1-.-comp_method_predict file_train_mod1---comp_method_train - file_train_mod1---comp_method file_train_mod2---comp_control_method + file_train_mod2---comp_method file_train_mod2-.-comp_method_predict file_train_mod2---comp_method_train - file_train_mod2---comp_method + file_test_mod1---comp_control_method + file_test_mod1---comp_method + file_test_mod1---comp_method_predict + file_test_mod1-.-comp_method_train + file_test_mod2---comp_control_method + file_test_mod2---comp_metric comp_control_method-->file_prediction + comp_method-->file_prediction comp_method_predict-->file_prediction comp_method_train-->file_pretrained_model - comp_method-->file_prediction comp_metric-->file_score file_prediction---comp_metric file_pretrained_model---comp_method_predict @@ -154,17 +155,16 @@ Arguments: | `--output_train_mod1` | `file` | (*Output*) The mod1 expression values of the train cells. | | `--output_train_mod2` | `file` | (*Output*) The mod2 expression values of the train cells. | | `--output_test_mod1` | `file` | (*Output*) The mod1 expression values of the test cells. | -| `--output_test_mod2` | `file` | (*Output*) The mod2 expression values of the test cells. | -| `--seed` | `integer` | (*Optional*) NA. Default: `1`. | +| `--output_test_mod2` | `file` | (*Output*) The ground-truth mod2 expression values of the test cells. | -## File format: Test mod1 +## File format: Train mod1 -The mod1 expression values of the test cells. +The mod1 expression values of the train cells. Example file: -`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/test_mod1.h5ad` +`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/train_mod1.h5ad` Format: @@ -175,7 +175,7 @@ Format: var: 'gene_ids', 'hvg', 'hvg_score' obsm: 'gene_activity' layers: 'counts', 'normalized' - uns: 'dataset_id', 'common_dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism', 'normalization_id', 'gene_activity_var_names' + uns: 'dataset_id', 'common_dataset_id', 'dataset_organism', 'normalization_id', 'gene_activity_var_names' @@ -195,23 +195,18 @@ Data structure: | `layers["normalized"]` | `double` | Normalized expression values. | | `uns["dataset_id"]` | `string` | A unique identifier for the dataset. | | `uns["common_dataset_id"]` | `string` | (*Optional*) A common 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. | | `uns["normalization_id"]` | `string` | The unique identifier of the normalization method used. | | `uns["gene_activity_var_names"]` | `string` | (*Optional*) Names of the gene activity matrix. | -## File format: Test mod2 +## File format: Train mod2 -The mod2 expression values of the test cells. +The mod2 expression values of the train cells. Example file: -`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/test_mod2.h5ad` +`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/train_mod2.h5ad` Format: @@ -222,7 +217,7 @@ Format: var: 'gene_ids', 'hvg', 'hvg_score' obsm: 'gene_activity' layers: 'counts', 'normalized' - uns: 'dataset_id', 'common_dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism', 'gene_activity_var_names' + uns: 'dataset_id', 'common_dataset_id', 'dataset_organism', 'normalization_id', 'gene_activity_var_names' @@ -242,22 +237,18 @@ Data structure: | `layers["normalized"]` | `double` | Normalized expression values. | | `uns["dataset_id"]` | `string` | A unique identifier for the dataset. | | `uns["common_dataset_id"]` | `string` | (*Optional*) A common 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. | +| `uns["normalization_id"]` | `string` | The unique identifier of the normalization method used. | | `uns["gene_activity_var_names"]` | `string` | (*Optional*) Names of the gene activity matrix. | -## File format: Train mod1 +## File format: Test mod1 -The mod1 expression values of the train cells. +The mod1 expression values of the test cells. Example file: -`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/train_mod1.h5ad` +`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/test_mod1.h5ad` Format: @@ -268,7 +259,7 @@ Format: var: 'gene_ids', 'hvg', 'hvg_score' obsm: 'gene_activity' layers: 'counts', 'normalized' - uns: 'dataset_id', 'common_dataset_id', 'dataset_organism', 'normalization_id', 'gene_activity_var_names' + uns: 'dataset_id', 'common_dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism', 'normalization_id', 'gene_activity_var_names' @@ -288,18 +279,28 @@ Data structure: | `layers["normalized"]` | `double` | Normalized expression values. | | `uns["dataset_id"]` | `string` | A unique identifier for the dataset. | | `uns["common_dataset_id"]` | `string` | (*Optional*) A common 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. | | `uns["normalization_id"]` | `string` | The unique identifier of the normalization method used. | | `uns["gene_activity_var_names"]` | `string` | (*Optional*) Names of the gene activity matrix. | -## File format: Train mod2 +## File format: Solution -The mod2 expression values of the train cells. +The ground-truth mod2 expression values of the test cells. Example file: -`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/train_mod2.h5ad` +`resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/test_mod2.h5ad` + +Description: + +The ground truth against which predictions are scored. Only the metrics +and the control methods receive this file; regular methods never see it. Format: @@ -310,7 +311,7 @@ Format: var: 'gene_ids', 'hvg', 'hvg_score' obsm: 'gene_activity' layers: 'counts', 'normalized' - uns: 'dataset_id', 'common_dataset_id', 'dataset_organism', 'normalization_id', 'gene_activity_var_names' + uns: 'dataset_id', 'common_dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism', 'gene_activity_var_names' @@ -330,8 +331,12 @@ Data structure: | `layers["normalized"]` | `double` | Normalized expression values. | | `uns["dataset_id"]` | `string` | A unique identifier for the dataset. | | `uns["common_dataset_id"]` | `string` | (*Optional*) A common 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. | -| `uns["normalization_id"]` | `string` | The unique identifier of the normalization method used. | | `uns["gene_activity_var_names"]` | `string` | (*Optional*) Names of the gene activity matrix. | @@ -349,14 +354,14 @@ Arguments: | `--input_train_mod1` | `file` | The mod1 expression values of the train cells. | | `--input_train_mod2` | `file` | The mod2 expression values of the train cells. | | `--input_test_mod1` | `file` | The mod1 expression values of the test cells. | -| `--input_test_mod2` | `file` | The mod2 expression values of the test cells. | +| `--input_test_mod2` | `file` | The ground-truth mod2 expression values of the test cells. | | `--output` | `file` | (*Output*) A prediction of the mod2 expression values of the test cells. | -## Component type: Predict +## Component type: Method -Make predictions using a trained model. +A regression method. Arguments: @@ -364,17 +369,16 @@ Arguments: | Name | Type | Description | |:---|:---|:---| -| `--input_train_mod1` | `file` | (*Optional*) The mod1 expression values of the train cells. | -| `--input_train_mod2` | `file` | (*Optional*) The mod2 expression values of the train cells. | +| `--input_train_mod1` | `file` | The mod1 expression values of the train cells. | +| `--input_train_mod2` | `file` | The mod2 expression values of the train cells. | | `--input_test_mod1` | `file` | The mod1 expression values of the test cells. | -| `--input_model` | `file` | A pretrained model for predicting the expression of one modality from another. | | `--output` | `file` | (*Output*) A prediction of the mod2 expression values of the test cells. | -## Component type: Train +## Component type: Predict -Train a model to predict the expression of one modality from another. +Make predictions using a trained model. Arguments: @@ -382,16 +386,17 @@ Arguments: | Name | Type | Description | |:---|:---|:---| -| `--input_train_mod1` | `file` | The mod1 expression values of the train cells. | -| `--input_train_mod2` | `file` | The mod2 expression values of the train cells. | -| `--input_test_mod1` | `file` | (*Optional*) The mod1 expression values of the test cells. | -| `--output` | `file` | (*Output*) A pretrained model for predicting the expression of one modality from another. | +| `--input_train_mod1` | `file` | (*Optional*) The mod1 expression values of the train cells. | +| `--input_train_mod2` | `file` | (*Optional*) The mod2 expression values of the train cells. | +| `--input_test_mod1` | `file` | The mod1 expression values of the test cells. | +| `--input_model` | `file` | A pretrained model for predicting the expression of one modality from another. | +| `--output` | `file` | (*Output*) A prediction of the mod2 expression values of the test cells. | -## Component type: Method +## Component type: Train -A regression method. +Train a model to predict the expression of one modality from another. Arguments: @@ -401,8 +406,8 @@ Arguments: |:---|:---|:---| | `--input_train_mod1` | `file` | The mod1 expression values of the train cells. | | `--input_train_mod2` | `file` | The mod2 expression values of the train cells. | -| `--input_test_mod1` | `file` | The mod1 expression values of the test cells. | -| `--output` | `file` | (*Output*) A prediction of the mod2 expression values of the test cells. | +| `--input_test_mod1` | `file` | (*Optional*) The mod1 expression values of the test cells. | +| `--output` | `file` | (*Output*) A pretrained model for predicting the expression of one modality from another. | @@ -417,7 +422,7 @@ Arguments: | Name | Type | Description | |:---|:---|:---| | `--input_prediction` | `file` | A prediction of the mod2 expression values of the test cells. | -| `--input_test_mod2` | `file` | The mod2 expression values of the test cells. | +| `--input_test_mod2` | `file` | The ground-truth mod2 expression values of the test cells. | | `--output` | `file` | (*Output*) Metric score file. | @@ -532,4 +537,3 @@ Data structure: | `uns["gene_activity_var_names"]` | `string` | (*Optional*) Names of the gene activity matrix. | - diff --git a/src/api/file_test_mod2.yaml b/src/api/file_test_mod2.yaml index e56579b0..49af75cf 100644 --- a/src/api/file_test_mod2.yaml +++ b/src/api/file_test_mod2.yaml @@ -1,7 +1,10 @@ type: file example: "resources_test/task_predict_modality/openproblems_neurips2021/bmmc_cite/swap/test_mod2.h5ad" -label: "Test mod2" -summary: "The mod2 expression values of the test cells." +label: "Solution" +summary: "The ground-truth mod2 expression values of the test cells." +description: | + The ground truth against which predictions are scored. Only the metrics and the + control methods receive this file; regular methods never see it. info: format: type: h5ad