spatialdata.join_spatialelement_table

spatialdata.join_spatialelement_table(sdata=None, spatial_element_names=None, spatial_elements=None, table_name=None, table=None, how='left', match_rows='no')

Join SpatialElement(s) and table together in SQL like manner.

The function allows the user to perform SQL like joins of SpatialElements and a table. The elements are not returned together in one dataframe-like structure, but instead filtered elements are returned. To determine matches, for the SpatialElement the index is used and for the table the region key column and instance key column. The elements are not overwritten in the SpatialData object.

The following joins are supported: 'left', 'left_exclusive', 'inner', 'right' and 'right_exclusive'. In case of a 'left' join the SpatialElements are returned in a dictionary as is while the table is filtered to only include matching rows. In case of 'left_exclusive' join None is returned for table while the SpatialElements returned are filtered to only include indices not present in the table. The cases for 'right' joins are symmetric to the 'left' joins. In case of an 'inner' join of SpatialElement(s) and a table, for each an element is returned only containing the rows that are present in both the SpatialElement and table.

For Points and Shapes elements every valid join for argument how is supported. For Labels elements only

the 'left' and 'right_exclusive' joins are supported.

Parameters:

• sdata (Optional[SpatialData] (default: None)) – SpatialData object containing all the elements and tables. This parameter can be None; in such case the both the names and values for the elements and the table must be provided.

• spatial_element_names (Union[str, list[str], None] (default: None)) –

  Required. The name(s) of the spatial elements to be joined with the table. If a list of names, and if sdata is

  None, the indices must match with the list of SpatialElements passed on by the argument elements.

• spatial_elements (Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame, list[Union[SpatialImage, MultiscaleSpatialImage, GeoDataFrame, DataFrame]], None] (default: None)) – This parameter should be speficied exactly when sdata is None. The SpatialElement(s) to be joined with the table. In case of a list of SpatialElements the indices must match exactly with the indices in the list of spatial_element_name.

• table_name (Optional[str] (default: None)) – The name of the table to join with the spatial elements. Optional, table can be provided instead.

• table (Optional[AnnData] (default: None)) – The table to join with the spatial elements. When sdata is not None, table_name can be used instead.

• how (Literal['left', 'left_exclusive', 'inner', 'right', 'right_exclusive'] (default: 'left')) – The type of SQL like join to perform, default is 'left'. Options are 'left', 'left_exclusive', 'inner', 'right' and 'right_exclusive'.

• match_rows (Literal['no', 'left', 'right'] (default: 'no')) – Whether to match the indices of the element and table and if so how. If 'left', element_indices take priority and if 'right' table instance ids take priority.

Return type:

tuple[dict[str, Any], AnnData]

Returns:

: A tuple containing the joined elements as a dictionary and the joined table as an AnnData object.

Raises:

• ValueError – If spatial_element_names is not provided.

• ValueError – If sdata is None but spatial_elements is not None; if sdata is not None, but spatial_elements is None.

• ValueError – If table_name is provided but not present in the SpatialData object, or if table_name is provided but sdata is None.

• ValueError – If not exactly one of table_name and table is provided.

• ValueError – If no valid elements are provided for the join operation.

• ValueError – If the provided join type is not supported.

• ValueError – If an incorrect value is given for match_rows.