diff --git a/src/tasks/spatial_decomposition/README.md b/src/tasks/spatial_decomposition/README.md new file mode 100644 index 0000000000..c068843b76 --- /dev/null +++ b/src/tasks/spatial_decomposition/README.md @@ -0,0 +1,17 @@ +# Spatial Decomposition/Deconvolution + +Spatial decomposition (also often referred to as Spatial deconvolution) is +applicable to spatial transcriptomics data where the transcription profile of +each capture location (spot, voxel, bead, etc.) do not share a bijective +relationship with the cells in the tissue, i.e., multiple cells may contribute +to the same capture location. The task of spatial decomposition then refers to +estimating the composition of cell types/states that are present at each capture +location. The cell type/states estimates are presented as proportion values, +representing the proportion of the cells at each capture location that belong to +a given cell type. + +We distinguish between _reference-based_ decomposition and _de novo_ +decomposition, where the former leverage external data (e.g., scRNA-seq or +scNuc-seq) to guide the inference process, while the latter only work with the +spatial data. We require that all datasets have an associated reference single +cell data set, but methods are free to ignore this information. \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/README.md b/src/tasks/spatial_decomposition/api/README.md new file mode 100644 index 0000000000..7c3b9c8d87 --- /dev/null +++ b/src/tasks/spatial_decomposition/api/README.md @@ -0,0 +1,8 @@ +# Component and file format specifications + +This folder contains specifications for file formats and component +interfaces. + +These are not only used for documentation (i.e. to document the file +format of inputs and outputs of a component), but also for unit testing +and validation of output files. diff --git a/src/tasks/spatial_decomposition/api/README.qmd b/src/tasks/spatial_decomposition/api/README.qmd new file mode 100644 index 0000000000..d31a99367e --- /dev/null +++ b/src/tasks/spatial_decomposition/api/README.qmd @@ -0,0 +1,8 @@ +--- +title: Component and file format specifications +format: gfm +--- + +This folder contains specifications for file formats and component interfaces. + +These are not only used for documentation (i.e. to document the file format of inputs and outputs of a component), but also for unit testing and validation of output files. \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/comp_control_method.yaml b/src/tasks/spatial_decomposition/api/comp_control_method.yaml new file mode 100644 index 0000000000..948257225d --- /dev/null +++ b/src/tasks/spatial_decomposition/api/comp_control_method.yaml @@ -0,0 +1,37 @@ +functionality: + namespace: "spatial_decomposition/control_methods" + info: + type: control_method + type_info: + label: Control method + summary: Quality control methods for verifying the pipeline. + description: | + Control methods have the same interface as the regular methods + but also receive the solution object as input. It serves as a + starting point to test the relative accuracy of new methods in + the task, and also as a quality control for the metrics defined + in the task. + arguments: + - name: "--input_single_cell" + __merge__: anndata_single_cell.yaml + direction: input + required: true + - name: "--input_spatial_masked" + __merge__: anndata_spatial_masked.yaml + direction: input + required: true + - name: "--input_solution" + __merge__: anndata_solution.yaml + direction: input + required: true + - name: "--output" + __merge__: anndata_output.yaml + direction: output + required: true + test_resources: + - type: python_script + path: /src/common/comp_tests/check_method_config.py + - type: python_script + path: /src/common/comp_tests/run_and_check_adata.py + - path: /resources_test/spatial_decomposition/pancreas + dest: resources_test/spatial_decomposition/pancreas \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/comp_method.yaml b/src/tasks/spatial_decomposition/api/comp_method.yaml new file mode 100644 index 0000000000..641f781cec --- /dev/null +++ b/src/tasks/spatial_decomposition/api/comp_method.yaml @@ -0,0 +1,28 @@ +functionality: + namespace: "spatial_decomposition/methods" + info: + type: method + type_info: + label: Method + summary: A spatial composition method. + description: "Method to estimate cell type proportions from spatial and single cell data" + arguments: + - name: "--input_single_cell" + __merge__: anndata_single_cell.yaml + direction: input + required: true + - name: "--input_spatial" + __merge__: anndata_spatial_masked.yaml + direction: input + required: true + - name: "--output" + __merge__: anndata_output.yaml + direction: output + required: true + test_resources: + - type: python_script + path: /src/common/comp_tests/check_method_config.py + - type: python_script + path: /src/common/comp_tests/run_and_check_adata.py + - path: /resources_test/spatial_decomposition/pancreas + dest: resources_test/spatial_decomposition/pancreas \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/comp_metric.yaml b/src/tasks/spatial_decomposition/api/comp_metric.yaml new file mode 100644 index 0000000000..d9188a64cb --- /dev/null +++ b/src/tasks/spatial_decomposition/api/comp_metric.yaml @@ -0,0 +1,30 @@ +functionality: + namespace: "spatial_decomposition/metrics" + info: + type: metric + type_info: + label: Metric + summary: A spatial decomposition metric. + description: | + A metric for evaluating accuracy of cell type proportion estimate + arguments: + - name: "--input_method" + __merge__: anndata_output.yaml + direction: input + required: true + - name: "--input_solution" + __merge__: anndata_solution.yaml + direction: input + required: true + - name: "--output" + __merge__: anndata_score.yaml + direction: output + required: true + test_resources: + - type: python_script + path: /src/common/comp_tests/check_metric_config.py + - type: python_script + path: /src/common/comp_tests/run_and_check_adata.py + - path: /resources_test/spatial_decomposition/pancreas + dest: resources_test/spatial_decomposition/pancreas + \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/comp_process_dataset.yaml b/src/tasks/spatial_decomposition/api/comp_process_dataset.yaml new file mode 100644 index 0000000000..4eaf9fecf8 --- /dev/null +++ b/src/tasks/spatial_decomposition/api/comp_process_dataset.yaml @@ -0,0 +1,31 @@ +functionality: + namespace: "spatial_decomposition" + info: + type: process_dataset + type_info: + label: Data processor + summary: A spatial decomposition dataset processor. + description: | + Prepare a common dataset for the spatial_decomposition task. + arguments: + - name: "--input" + __merge__: /src/datasets/api/anndata_common_dataset.yaml + direction: input + required: true + - name: "--output_single_cell" + __merge__: anndata_single_cell.yaml + direction: output + required: true + - name: "--output_spatial_masked" + __merge__: anndata_spatial_masked.yaml + direction: output + required: true + - name: "--output_solution" + __merge__: anndata_solution.yaml + direction: output + required: true + test_resources: + - type: python_script + path: /src/common/comp_tests/run_and_check_adata.py + - path: /resources_test/common/pancreas + dest: resources_test/common/pancreas diff --git a/src/tasks/spatial_decomposition/api/file_output.yaml b/src/tasks/spatial_decomposition/api/file_output.yaml new file mode 100644 index 0000000000..18f8cb736d --- /dev/null +++ b/src/tasks/spatial_decomposition/api/file_output.yaml @@ -0,0 +1,35 @@ +type: file +example: "resources_test/spatial_decomposition/pancreas/anndata_output.h5ad" +info: + label: Output + summary: "Spatial data with estimated proportions." + description: "Spatial data file with estimated cell type proportions." + slots: + layers: + - type: integer + name: counts + description: Raw counts + required: true + obsm: + - type: double + name: coordinates + description: XY coordinates for each spot + required: true + - type: double + name: proportions + description: Estimated cell type proportions for each spot + required: true + uns: + - type: string + name: cell_type_names + description: Cell type names corresponding to columns of `proportions` + required: true + - type: string + name: dataset_id + description: "A unique identifier for the dataset" + required: true + - type: string + name: method_id + description: "A unique identifier for the method" + required: true + \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/file_score.yaml b/src/tasks/spatial_decomposition/api/file_score.yaml new file mode 100644 index 0000000000..48326d2816 --- /dev/null +++ b/src/tasks/spatial_decomposition/api/file_score.yaml @@ -0,0 +1,25 @@ +type: file +example: "resources_test/spatial_decomposition/pancreas/anndata_score.h5ad" +info: + label: "Score" + summary: Metric score file. + slots: + uns: + - type: string + name: dataset_id + description: "A unique identifier for the dataset" + required: true + - type: string + name: method_id + description: "A unique identifier for the method" + required: true + - type: string + name: metric_ids + description: "One or more unique metric identifiers" + multiple: true + required: true + - type: double + name: metric_values + description: "The metric values obtained for the given prediction. Must be of same length as 'metric_ids'." + multiple: true + required: true diff --git a/src/tasks/spatial_decomposition/api/file_single_cell.yaml b/src/tasks/spatial_decomposition/api/file_single_cell.yaml new file mode 100644 index 0000000000..cf6d60f725 --- /dev/null +++ b/src/tasks/spatial_decomposition/api/file_single_cell.yaml @@ -0,0 +1,25 @@ +type: file +example: "resources_test/spatial_decomposition/pancreas/anndata_single_cell.h5ad" +info: + label: "Single cell data" + summary: "The single cell data file" + slots: + layers: + - type: integer + name: counts + description: Raw counts + required: true + obs: + - type: integer + name: label + description: Cell type label IDs + required: true + uns: + - type: string + name: cell_type_names + description: Cell type names corresponding to values in `label` + required: true + - type: string + name: dataset_id + description: "A unique identifier for the dataset" + required: true \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/file_solution.yaml b/src/tasks/spatial_decomposition/api/file_solution.yaml new file mode 100644 index 0000000000..b7e0479bc4 --- /dev/null +++ b/src/tasks/spatial_decomposition/api/file_solution.yaml @@ -0,0 +1,29 @@ +type: file +example: "resources_test/spatial_decomposition/pancreas/anndata_solution.h5ad" +info: + label: Solution + summary: "The solution spatial data file" + slots: + layers: + - type: integer + name: counts + description: Raw counts + required: true + obsm: + - type: double + name: coordinates + description: XY coordinates for each spot + required: true + - type: double + name: proportions + description: True cell type proportions for each spot + required: true + uns: + - type: string + name: cell_type_names + description: Cell type names corresponding to columns of `proportions` + required: true + - type: string + name: dataset_id + description: "A unique identifier for the dataset" + required: true \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/file_spatial_masked.yaml b/src/tasks/spatial_decomposition/api/file_spatial_masked.yaml new file mode 100644 index 0000000000..6319ffa48f --- /dev/null +++ b/src/tasks/spatial_decomposition/api/file_spatial_masked.yaml @@ -0,0 +1,25 @@ +type: file +example: "resources_test/spatial_decomposition/pancreas/anndata_spatial_masked.h5ad" +info: + label: "Masked" + summary: "The masked spatial data file" + slots: + layers: + - type: integer + name: counts + description: Raw counts + required: true + obsm: + - type: double + name: coordinates + description: XY coordinates for each spot + required: true + uns: + - type: string + name: cell_type_names + description: Cell type names corresponding to columns of `proportions` in output + required: true + - type: string + name: dataset_id + description: "A unique identifier for the dataset" + required: true \ No newline at end of file diff --git a/src/tasks/spatial_decomposition/api/task_info.yaml b/src/tasks/spatial_decomposition/api/task_info.yaml new file mode 100644 index 0000000000..411c2c4f8d --- /dev/null +++ b/src/tasks/spatial_decomposition/api/task_info.yaml @@ -0,0 +1,26 @@ +name: spatial_decomposition +label: "Spatial decomposition" +summary: "Estimation of cell type proportions per spot in 2D space from spatial transcriptomic data coupled with corresponding single-cell data" +motivation: | + Spatial decomposition (also often referred to as Spatial deconvolution) is + applicable to spatial transcriptomics data where the transcription profile of + each capture location (spot, voxel, bead, etc.) do not share a bijective + relationship with the cells in the tissue, i.e., multiple cells may contribute + to the same capture location. The task of spatial decomposition then refers to + estimating the composition of cell types/states that are present at each capture + location. The cell type/states estimates are presented as proportion values, + representing the proportion of the cells at each capture location that belong to + a given cell type. +description: | + We distinguish between _reference-based_ decomposition and _de novo_ + decomposition, where the former leverage external data (e.g., scRNA-seq or + scNuc-seq) to guide the inference process, while the latter only work with the + spatial data. We require that all datasets have an associated reference single + cell data set, but methods are free to ignore this information. +authors: + - name: "Giovanni Palla" + roles: [ author, maintainer ] + info: { github: giovp } + - name: "Scott Gigante" + roles: [ maintainer ] + info: { github: scottgigante, orcid: "0000-0002-4544-2764" } \ No newline at end of file