Spatial Segmentation

A one sentence summary of purpose and methodology. Used for creating an overview tables.

Repository: openproblems-bio/task_spatial_segmentation

Description

Provide a clear and concise description of your task, detailing the specific problem it aims to solve. Outline the input data types, the expected output, and any assumptions or constraints. Be sure to explain any terminology or concepts that are essential for understanding the task.

Explain the motivation behind your proposed task. Describe the biological or computational problem you aim to address and why it’s important. Discuss the current state of research in this area and any gaps or challenges that your task could help address. This section should convince readers of the significance and relevance of your task.

Authors & contributors

Name	Roles	Orcid	Github
Daria Romanovskaia	maintainer, author	0000-0003-2831-0919	dariarom94
Florian Heyl	maintainer, author	0000-0002-3651-5685	heylf
Robrecht Cannoodt	author	0000-0003-3641-729X	rcannood

API

flowchart TB
file_common_ist("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-common-ist-dataset'>Common iST Dataset</a>")
comp_data_processor[/"<a href='https://github.com/openproblems-bio/task_spatial_segmentation#component-type-data-processor'>Data processor</a>"/]
file_spatial_unlabelled("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-unlabelled'>Unlabelled</a>")
file_spatial_solution("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-solution'>Solution</a>")
file_scrnaseq_reference("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-scrna-seq-reference'>scRNA-seq Reference</a>")
comp_control_method[/"<a href='https://github.com/openproblems-bio/task_spatial_segmentation#component-type-control-method'>Control Method</a>"/]
comp_method[/"<a href='https://github.com/openproblems-bio/task_spatial_segmentation#component-type-method'>Method</a>"/]
comp_output_processor[/"<a href='https://github.com/openproblems-bio/task_spatial_segmentation#component-type-output-processor'>Output processor</a>"/]
comp_metric[/"<a href='https://github.com/openproblems-bio/task_spatial_segmentation#component-type-metric'>Metric</a>"/]
file_prediction("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-predicted-data'>Predicted data</a>")
file_processed_prediction("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-processed-prediction'>Processed prediction</a>")
file_score("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-score'>Score</a>")
file_common_scrnaseq("<a href='https://github.com/openproblems-bio/task_spatial_segmentation#file-format-common-sc-dataset'>Common SC Dataset</a>")
file_common_ist---comp_data_processor
comp_data_processor-->file_spatial_unlabelled
comp_data_processor-->file_spatial_solution
comp_data_processor-->file_scrnaseq_reference
file_spatial_unlabelled---comp_control_method
file_spatial_unlabelled---comp_method
file_spatial_unlabelled---comp_output_processor
file_spatial_solution---comp_control_method
file_spatial_solution---comp_metric
comp_control_method-->file_prediction
comp_method-->file_prediction
comp_output_processor-->file_processed_prediction
comp_metric-->file_score
file_prediction---comp_output_processor
file_processed_prediction---comp_metric
file_common_scrnaseq---comp_data_processor

Loading

File format: Common iST Dataset

An unprocessed spatial imaging dataset stored as a zarr file.

Example file: resources_test/common/2023_10x_mouse_brain_xenium_rep1/dataset.zarr

Description:

This dataset contains raw images, labels, points, shapes, and tables as output by a dataset loader.

Format:

SpatialData object
images: 'image', 'image_3D', 'he_image'
labels: 'cell_labels', 'nucleus_labels', 'groundtruth_cell_labels'
points: 'transcripts'
shapes: 'cell_boundaries', 'nucleus_boundaries'
tables: 'table'
coordinate_systems: 'global'

Data structure:

images

Name	Description
image	The raw image data.
image_3D	(Optional) The raw 3D image data.
he_image	(Optional) H&E image data.

labels

Name	Description
cell_labels	Vendor-provided cell segmentation labels.
nucleus_labels	Vendor-provided nucleus segmentation labels.
groundtruth_cell_labels	(Optional) Manually annotated cell segmentation labels used as ground truth for evaluation.

points

transcripts: Point cloud data of transcripts.

Column	Type	Description
x	float	x-coordinate of the point.
y	float	y-coordinate of the point.
z	float	(Optional) z-coordinate of the point.
feature_name	categorical	Name of the feature.
cell_id	integer	(Optional) Unique identifier of the cell.
nucleus_id	integer	(Optional) Unique identifier of the nucleus.
cell_type	string	(Optional) Cell type of the cell.
qv	float	(Optional) Quality value of the point.
transcript_id	long	Unique identifier of the transcript.
overlaps_nucleus	boolean	(Optional) Whether the point overlaps with a nucleus.

shapes

cell_boundaries: Cell boundaries.

Column	Type	Description
geometry	object	Geometry of the cell boundary.

nucleus_boundaries: Nucleus boundaries.

Column	Type	Description
geometry	object	Geometry of the nucleus boundary.

tables

table: Metadata of spatial dataset.

Slot	Type	Description
obs["cell_id"]	string	A unique identifier for the cell.
obs["groundtruth_cell_type"]	string	(Optional) Manually curated cell type annotations which serves as ground truth for evaluations.
var["gene_ids"]	string	Unique identifier for the gene.
var["feature_types"]	string	Type of the feature.
obsm["spatial"]	double	Spatial coordinates of the cell.
uns["dataset_id"]	string	A unique identifier for the dataset.
uns["dataset_name"]	string	A human-readable name for the dataset.
uns["dataset_url"]	string	Link to the original source of the dataset.
uns["dataset_reference"]	string	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	The organism of the sample in the dataset.
uns["segmentation_id"]	string	A unique identifier for the segmentation.

coordinate_systems

Name	Description
global	Coordinate system of the replicate.

Component type: Data processor

A data processor.

Arguments:

Name	Type	Description
--input_sp	file	An unprocessed spatial imaging dataset stored as a zarr file.
--input_sc	file	An unprocessed dataset as output by a dataset loader.
--output_spatial_unlabelled	file	(Output) Preprocessed spatial transcriptomics data without segmentation labels for method input.
--output_spatial_solution	file	(Output) Ground truth segmentation labels and cell assignments for method evaluation.
--output_scrnaseq_reference	file	(Output) A single-cell reference dataset, preprocessed for this benchmark.

File format: Unlabelled

Preprocessed spatial transcriptomics data without segmentation labels for method input.

Example file: resources_test/task_spatial_segmentation/mouse_brain_combined/spatial_unlabelled.zarr

Description:

This dataset contains preprocessed images and transcript point clouds for spatial transcriptomics data. Ground truth segmentation labels are intentionally excluded to prevent methods from cheating.

Format:

SpatialData object
images: 'image'
labels: 'cell_labels', 'nucleus_labels'
points: 'transcripts'
tables: 'table'
coordinate_systems: 'global'

Data structure:

images

Name	Description
image	The raw image data.

labels

Name	Description
cell_labels	(Optional) Vendor-provided cell segmentation labels, exposed as a segmentation prior.
nucleus_labels	(Optional) Vendor-provided nucleus segmentation labels, exposed as a segmentation prior.

points

transcripts: Point cloud data of transcripts.

Column	Type	Description
x	float	x-coordinate of the point.
y	float	y-coordinate of the point.
z	float	(Optional) z-coordinate of the point.
feature_name	categorical	Name of the feature.
qv	float	(Optional) Quality value of the point.
transcript_id	long	Unique identifier of the transcript.
overlaps_nucleus	boolean	(Optional) Whether the point overlaps with the nucleus (derived from morphology).
cell_id	integer	(Optional) Vendor-provided cell assignment from the raw data, exposed as a segmentation prior. This is NOT the ground truth used for evaluation (which is held out in spatial_solution); methods may freely condition on it.

tables

table: Metadata of spatial dataset.

Slot	Type	Description
var["feature_id"]	string	(Optional) Unique identifier for the feature, usually a ENSEMBL gene id.
var["feature_name"]	string	A human-readable name for the feature, usually a gene symbol.
uns["dataset_id"]	string	A unique identifier for the dataset.
uns["dataset_name"]	string	A human-readable name for the dataset.
uns["dataset_url"]	string	Link to the original source of the dataset.
uns["dataset_reference"]	string	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	The organism of the sample in the dataset.
uns["orig_dataset_id"]	string	The identifier of the original dataset from which this dataset was derived (if applicable).

coordinate_systems

Name	Description
global	Coordinate system of the replicate.

File format: Solution

Ground truth segmentation labels and cell assignments for method evaluation.

Example file: resources_test/task_spatial_segmentation/mouse_brain_combined/spatial_solution.zarr

Description:

This dataset contains the ground truth cell and nucleus segmentation labels, cell boundaries, and a reference table matching each cell to its label region.

Format:

SpatialData object
labels: 'cell_labels', 'nucleus_labels', 'groundtruth_cell_labels'
points: 'transcripts'
shapes: 'cell_boundaries', 'nucleus_boundaries'
tables: 'table'

Data structure:

labels

Name	Description
cell_labels	Vendor-provided cell segmentation labels.
nucleus_labels	Vendor-provided nucleus segmentation labels.
groundtruth_cell_labels	(Optional) Manually annotated cell segmentation labels used as ground truth for evaluation.

points

transcripts: Point cloud data of transcripts with ground truth cell assignments.

Column	Type	Description
x	float	x-coordinate of the point.
y	float	y-coordinate of the point.
z	float	(Optional) z-coordinate of the point.
feature_name	categorical	Name of the feature.
cell_id	integer	Ground truth cell assignment (0 = background).
transcript_id	long	Unique identifier of the transcript.

shapes

cell_boundaries: Ground truth cell boundary shapes.

Column	Type	Description
geometry	object	Geometry of the cell boundary.

nucleus_boundaries: Ground truth nucleus boundary shapes.

Column	Type	Description
geometry	object	Geometry of the nucleus boundary.

tables

table: Reference cell metadata table.

Slot	Type	Description
obs["cell_id"]	integer	Unique cell identifier, matching instance IDs in the label images.
obs["region"]	string	Name of the label image this cell belongs to (e.g. ‘cell_labels’).
obs["cell_area"]	double	(Optional) Area of the cell in pixels.
obs["transcript_counts"]	integer	(Optional) Total number of transcripts assigned to this cell.
obs["groundtruth_cell_type"]	string	(Optional) Manually curated cell type annotations which serves as ground truth for evaluations.
var["feature_id"]	string	(Optional) Unique identifier for the feature, usually a ENSEMBL gene id.
var["feature_name"]	string	A human-readable name for the feature, usually a gene symbol.
uns["dataset_id"]	string	A unique identifier for the dataset.
uns["orig_dataset_id"]	string	The identifier of the original dataset from which this dataset was derived (if applicable).

File format: scRNA-seq Reference

A single-cell reference dataset, preprocessed for this benchmark.

Example file: resources_test/task_spatial_segmentation/mouse_brain_combined/scrnaseq_reference.h5ad

Description:

This dataset contains preprocessed counts and metadata for single-cell RNA-seq data.

Format:

AnnData object
obs: 'cell_type'
var: 'feature_id', 'feature_name', 'hvg'
obsm: 'X_pca'
obsp: 'knn_distances', 'knn_connectivities'
varm: 'pca_loadings'
layers: 'counts', 'normalized', 'normalized_log', 'normalized_log_scaled'
uns: 'dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism'

Data structure:

Slot	Type	Description
obs["cell_type"]	string	Classification of the cell type based on its characteristics and function within the tissue or organism.
var["feature_id"]	string	(Optional) Unique identifier for the feature, usually a ENSEMBL gene id.
var["feature_name"]	string	A human-readable name for the feature, usually a gene symbol.
var["hvg"]	boolean	Whether or not the feature is considered to be a ‘highly variable gene’.
obsm["X_pca"]	double	The resulting PCA embedding.
obsp["knn_distances"]	double	K nearest neighbors distance matrix.
obsp["knn_connectivities"]	double	K nearest neighbors connectivities matrix.
varm["pca_loadings"]	double	The PCA loadings matrix.
layers["counts"]	integer	Raw counts.
layers["normalized"]	double	Normalized expression values.
layers["normalized_log"]	double	Log1p normalized expression values.
layers["normalized_log_scaled"]	double	Log1p normalized expression values scaled to unit variance and zero mean.
uns["dataset_id"]	string	A unique identifier for the dataset. This is different from the obs.dataset_id field, which is the identifier for the dataset from which the cell data is derived.
uns["dataset_name"]	string	A human-readable name for the dataset.
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.

Component type: Control Method

Quality control methods for verifying the pipeline.

Arguments:

Name	Type	Description
--input	file	Preprocessed spatial transcriptomics data without segmentation labels for method input.
--input_solution	file	Ground truth segmentation labels and cell assignments for method evaluation.
--output	file	(Output) A predicted dataset as output by a method.

Component type: Method

A method.

Arguments:

Name	Type	Description
--input	file	Preprocessed spatial transcriptomics data without segmentation labels for method input.
--output	file	(Output) A predicted dataset as output by a method.

Component type: Output processor

An output processor for the prediction.

Arguments:

Name	Type	Description
--input_prediction	file	A predicted dataset as output by a method.
--input_spatial_unlabelled	file	Preprocessed spatial transcriptomics data without segmentation labels for method input.
--output	file	(Output) A processed predicted dataset, ready to be used as input for the evaluation.

Component type: Metric

A task template metric.

Arguments:

Name	Type	Description
--input_prediction	file	A processed predicted dataset, ready to be used as input for the evaluation.
--input_solution	file	Ground truth segmentation labels and cell assignments for method evaluation.
--output	file	(Output) File indicating the score of a metric.

File format: Predicted data

A predicted dataset as output by a method.

Example file: resources_test/task_spatial_segmentation/mouse_brain_combined/prediction.zarr

Format:

SpatialData object
labels: 'segmentation'
tables: 'table'

Data structure:

labels

Name	Description
segmentation	Segmentation of the data.

tables

table: AnnData table.

Slot	Type	Description
uns["dataset_id"]	string	A unique identifier for the dataset.
uns["method_id"]	string	A unique identifier for the method.

File format: Processed prediction

A processed predicted dataset, ready to be used as input for the evaluation.

Example file: resources_test/task_spatial_segmentation/mouse_brain_combined/processed_prediction.zarr

Format:

SpatialData object
labels: 'segmentation'
tables: 'table'

Data structure:

labels

Name	Description
segmentation	Segmentation of the data.

tables

table: AnnData table.

Slot	Type	Description
obs["cell_id"]	string	Cell ID.
obs["region"]	string	Region.
var["feature_id"]	string	(Optional) Unique identifier for the feature, usually a ENSEMBL gene id.
var["feature_name"]	string	A human-readable name for the feature, usually a gene symbol.
var["hvg"]	boolean	Whether or not the feature is considered to be a ‘highly variable gene’.
layers["counts"]	integer	Raw counts.
layers["normalized"]	double	Normalized expression values.
layers["normalized_log"]	double	Log1p normalized expression values.
layers["normalized_log_scaled"]	double	Log1p normalized expression values scaled to unit variance and zero mean.
uns["dataset_id"]	string	A unique identifier for the dataset.
uns["method_id"]	string	A unique identifier for the method.

File format: Score

File indicating the score of a metric.

Example file: resources_test/task_spatial_segmentation/mouse_brain_combined/score.h5ad

Format:

AnnData object
uns: 'dataset_id', 'normalization_id', 'method_id', 'metric_ids', 'metric_values'

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["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’.

File format: Common SC Dataset

An unprocessed dataset as output by a dataset loader.

Example file: resources_test/common/2023_yao_mouse_brain_scrnaseq_10xv2/dataset.h5ad

Description:

This dataset contains raw counts and metadata as output by a dataset loader.

The format of this file is mainly derived from the CELLxGENE schema v4.0.0.

Format:

AnnData object
obs: 'cell_type', 'cell_type_level2', 'cell_type_level3', 'cell_type_level4', 'dataset_id', 'assay', 'assay_ontology_term_id', 'cell_type_ontology_term_id', 'development_stage', 'development_stage_ontology_term_id', 'disease', 'disease_ontology_term_id', 'donor_id', 'is_primary_data', 'organism', 'organism_ontology_term_id', 'self_reported_ethnicity', 'self_reported_ethnicity_ontology_term_id', 'sex', 'sex_ontology_term_id', 'suspension_type', 'tissue', 'tissue_ontology_term_id', 'tissue_general', 'tissue_general_ontology_term_id', 'batch', 'soma_joinid'
var: 'feature_id', 'feature_name', 'soma_joinid', 'hvg', 'hvg_score'
obsm: 'X_pca'
obsp: 'knn_distances', 'knn_connectivities'
varm: 'pca_loadings'
layers: 'counts', 'normalized'
uns: 'dataset_id', 'dataset_name', 'dataset_url', 'dataset_reference', 'dataset_summary', 'dataset_description', 'dataset_organism'

Data structure:

Slot	Type	Description
obs["cell_type"]	string	Classification of the cell type based on its characteristics and function within the tissue or organism.
obs["cell_type_level2"]	string	(Optional) Classification of the cell type based on its characteristics and function within the tissue or organism.
obs["cell_type_level3"]	string	(Optional) Classification of the cell type based on its characteristics and function within the tissue or organism.
obs["cell_type_level4"]	string	(Optional) Classification of the cell type based on its characteristics and function within the tissue or organism.
obs["dataset_id"]	string	(Optional) Identifier for the dataset from which the cell data is derived, useful for tracking and referencing purposes.
obs["assay"]	string	(Optional) Type of assay used to generate the cell data, indicating the methodology or technique employed.
obs["assay_ontology_term_id"]	string	(Optional) Experimental Factor Ontology (EFO:) term identifier for the assay, providing a standardized reference to the assay type.
obs["cell_type_ontology_term_id"]	string	(Optional) Cell Ontology (CL:) term identifier for the cell type, offering a standardized reference to the specific cell classification.
obs["development_stage"]	string	(Optional) Stage of development of the organism or tissue from which the cell is derived, indicating its maturity or developmental phase.
obs["development_stage_ontology_term_id"]	string	(Optional) Ontology term identifier for the developmental stage, providing a standardized reference to the organism’s developmental phase. If the organism is human (organism_ontology_term_id == 'NCBITaxon:9606'), then the Human Developmental Stages (HsapDv:) ontology is used. If the organism is mouse (organism_ontology_term_id == 'NCBITaxon:10090'), then the Mouse Developmental Stages (MmusDv:) ontology is used. Otherwise, the Uberon (UBERON:) ontology is used.
obs["disease"]	string	(Optional) Information on any disease or pathological condition associated with the cell or donor.
obs["disease_ontology_term_id"]	string	(Optional) Ontology term identifier for the disease, enabling standardized disease classification and referencing. Must be a term from the Mondo Disease Ontology (MONDO:) ontology term, or PATO:0000461 from the Phenotype And Trait Ontology (PATO:).
obs["donor_id"]	string	(Optional) Identifier for the donor from whom the cell sample is obtained.
obs["is_primary_data"]	boolean	(Optional) Indicates whether the data is primary (directly obtained from experiments) or has been computationally derived from other primary data.
obs["organism"]	string	(Optional) Organism from which the cell sample is obtained.
obs["organism_ontology_term_id"]	string	(Optional) Ontology term identifier for the organism, providing a standardized reference for the organism. Must be a term from the NCBI Taxonomy Ontology (NCBITaxon:) which is a child of NCBITaxon:33208.
obs["self_reported_ethnicity"]	string	(Optional) Ethnicity of the donor as self-reported, relevant for studies considering genetic diversity and population-specific traits.
obs["self_reported_ethnicity_ontology_term_id"]	string	(Optional) Ontology term identifier for the self-reported ethnicity, providing a standardized reference for ethnic classifications. If the organism is human (organism_ontology_term_id == 'NCBITaxon:9606'), then the Human Ancestry Ontology (HANCESTRO:) is used.
obs["sex"]	string	(Optional) Biological sex of the donor or source organism, crucial for studies involving sex-specific traits or conditions.
obs["sex_ontology_term_id"]	string	(Optional) Ontology term identifier for the biological sex, ensuring standardized classification of sex. Only PATO:0000383, PATO:0000384 and PATO:0001340 are allowed.
obs["suspension_type"]	string	(Optional) Type of suspension or medium in which the cells were stored or processed, important for understanding cell handling and conditions.
obs["tissue"]	string	(Optional) Specific tissue from which the cells were derived, key for context and specificity in cell studies.
obs["tissue_ontology_term_id"]	string	(Optional) Ontology term identifier for the tissue, providing a standardized reference for the tissue type. For organoid or tissue samples, the Uber-anatomy ontology (UBERON:) is used. The term ids must be a child term of UBERON:0001062 (anatomical entity). For cell cultures, the Cell Ontology (CL:) is used. The term ids cannot be CL:0000255, CL:0000257 or CL:0000548.
obs["tissue_general"]	string	(Optional) General category or classification of the tissue, useful for broader grouping and comparison of cell data.
obs["tissue_general_ontology_term_id"]	string	(Optional) Ontology term identifier for the general tissue category, aiding in standardizing and grouping tissue types. For organoid or tissue samples, the Uber-anatomy ontology (UBERON:) is used. The term ids must be a child term of UBERON:0001062 (anatomical entity). For cell cultures, the Cell Ontology (CL:) is used. The term ids cannot be CL:0000255, CL:0000257 or CL:0000548.
obs["batch"]	string	(Optional) A batch identifier. This label is very context-dependent and may be a combination of the tissue, assay, donor, etc.
obs["soma_joinid"]	integer	(Optional) If the dataset was retrieved from CELLxGENE census, this is a unique identifier for the cell.
var["feature_id"]	string	(Optional) Unique identifier for the feature, usually a ENSEMBL gene id.
var["feature_name"]	string	A human-readable name for the feature, usually a gene symbol.
var["soma_joinid"]	integer	(Optional) If the dataset was retrieved from CELLxGENE census, this is a unique identifier for the feature.
var["hvg"]	boolean	Whether or not the feature is considered to be a ‘highly variable gene’.
var["hvg_score"]	double	A score for the feature indicating how highly variable it is.
obsm["X_pca"]	double	The resulting PCA embedding.
obsp["knn_distances"]	double	K nearest neighbors distance matrix.
obsp["knn_connectivities"]	double	K nearest neighbors connectivities matrix.
varm["pca_loadings"]	double	The PCA loadings matrix.
layers["counts"]	integer	Raw counts.
layers["normalized"]	integer	Normalized expression values.
uns["dataset_id"]	string	A unique identifier for the dataset. This is different from the obs.dataset_id field, which is the identifier for the dataset from which the cell data is derived.
uns["dataset_name"]	string	A human-readable name for the dataset.
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.