fusion_tools.utils package

fusion_tools.utils.shapes module

Utility functions for data derived from FUSION

fusion_tools.utils.shapes.align_object_props(geo_ann: dict, prop_df: DataFrame | list, prop_cols: list | str, alignment_type: str, prop_key: None | str = None) → dict

Aligning GeoJSON formatted annotations with an external file containing properties for each feature

Parameters:

geo_ann (dict) – GeoJSON formatted annotations to align with external file
prop_df (Union[pd.DataFrame,list]) – Property DataFrame or list containing DataFrames to align with GeoJSON
prop_cols (Union[list,str]) – Column(s) containing property information in each DataFrame
alignment_type (str) – Process to use for aligning rows of property DataFrame to GeoJSON

Returns:

GeoJSON annotations with aligned properties applied

Return type:

dict

fusion_tools.utils.shapes.convert_histomics(json_anns: list | dict)

fusion_tools.utils.shapes.detect_geojson(query_annotations: list | dict)

Check whether a list/dict of annotations are in GeoJSON format

Parameters:: query_annotations (Union[list,dict]) – Input query annotation

fusion_tools.utils.shapes.detect_histomics(query_annotations: list | dict)

Check whether a list/dict of annotations are in histomics format

Parameters:: query_annotations (Union[list,dict]) – Input query annotation

fusion_tools.utils.shapes.export_annotations(ann_geojson: dict | list, format: str, save_path: str, ann_options: dict = {})

Exporting GeoJSON annotations to a desired format

Parameters:

ann_geojson (Union[dict,list]) – Individual or list of GeoJSON formatted annotations
format (str) – What format to export these annotations to
save_path (str) – Where to save the exported annotations
ann_options (dict, optional) – Additional options to pass to export (used to add an id or layer name for Aperio formatted annotations)

fusion_tools.utils.shapes.extract_geojson_properties(geo_list: list, reference_object: str | None = None, ignore_list: list | None = None, nested_depth: int = 4) → list

Extract property names and info for provided list of GeoJSON structures.

Parameters:

geo_list (list) – List of GeoJSON dictionaries containing properties
reference_object (Union[str,None], optional) – File path to reference object containing more information for each structure, defaults to None
ignore_list (Union[list,None], optional) – List of properties to hide from the main view, defaults to None
nested_depth (int, optional) – For properties stored as nested dictionaries, specify desired depth (depth of 2 = {‘property_name’: {‘sub-prop1’: val, etc.}}), defaults to 2

Returns:

List of accessible properties in visualization session.

Return type:

list

fusion_tools.utils.shapes.extract_listed_prop(main_list: list, path: tuple = (), values_list: list = [])

fusion_tools.utils.shapes.extract_nested_prop(main_prop_dict: dict, depth: int, path: tuple = (), values_list: list = [])

Extracted nested properties up to depth level.

Parameters:

main_prop_dict (dict) – Main dictionary containing nested properties. ex: {‘main_prop’: {‘sub_prop1’: value1, ‘sub_prop2’: value2}}
depth (int) – Number of levels to extend into nested dictionary

fusion_tools.utils.shapes.find_intersecting(geo_source: dict | str, geo_query: Polygon, return_props: bool = True, return_shapes: bool = True)

Return properties and/or shapes of features from geo_source that intersect with geo_query

Parameters:

geo_source (dict) – Source GeoJSON where you are searching for intersecting features
geo_query (shapely.geometry.Polygon) – Query polygon used to filter source GeoJSON features
return_props (bool, optional) – Whether or not to return properties of intersecting features
return_shapes (bool, optional) – Whether or not to return shape information of intersecting features

Returns:

Intersecting properties and/or shapes from geo_source

Return type:

tuple

fusion_tools.utils.shapes.find_nested_levels(nested_dict) → int

Find number of levels for nested dictionary

Parameters:: nested_dict (dict) – dictionary containing nested values
Returns:: number of levels for nested dictionary
Return type:: int

fusion_tools.utils.shapes.load_annotations(file_path: str, name: str | None = None, **kwargs) → dict

fusion_tools.utils.shapes.load_aperio(xml_path: str) → list

Loading Aperio formatted annotations

Parameters:: xml_path (str) – Path to Aperio formatted annotations (XML)
Returns:: GeoJSON FeatureCollection formatted annotations for each layer in XML
Return type:: list

fusion_tools.utils.shapes.load_geojson(geojson_path: str, name: str | None = None) → dict

Load GeoJSON annotations from file path. Optionally add names for GeoJSON FeatureCollections

Parameters:

geojson_path (str) – Path to GeoJSON file
name (Union[str,None], optional) – Name for structure present in FeatureCollection, defaults to None

Returns:

GeoJSON FeatureCollection dictionary

Return type:

dict

fusion_tools.utils.shapes.load_histomics(json_path: str) → list

Load large-image annotation from filepath

Parameters:: json_path (str) – Path to large-image formatted annotations
Returns:: GeoJSON FeatureCollection formatted annotation
Return type:: list

fusion_tools.utils.shapes.load_label_mask(label_mask: ndarray, name: str) → dict

fusion_tools.utils.shapes.load_polygon_csv(csv_path: str, name: str, shape_cols: list | str, group_by_col: str | None, property_cols: str | list | None, shape_options: dict) → dict: Load csv formatted annotations from filepath shape_cols: should be x,y (names of columns for x and then y coordinates) group_by_col: name of column to group features by (used to determine which coordinates belong to the same structure for non-point annotations) property_cols: list of columns containing properties shape_options: dict with “radius” for point annotations (can be number or column that has number)

fusion_tools.utils.shapes.load_visium(visium_path: str, include_var_names: list = [], include_obs: list = [], mpp: float | None = None)

Loading 10x Visium Spot annotations from an h5ad file. Adds any of the variables listed in var_names and also the barcodes associated with each spot.

Parameters:

visium_path (str) – Path to the h5ad (anndata) formatted Visium data
include_var_names (list, optional) – List of additional variables to add to the generated annotations (barcode is added by default), defaults to []
mpp (Union[float,None], optional) – If the Microns Per Pixel (MPP) is known for this image then pass it here to save time calculating spot diameter., defaults to None

fusion_tools.utils.shapes.merge_dict(a: dict, b: dict, path=[])

fusion_tools.utils.shapes.path_to_indices(path): From SVG path to numpy array of coordinates, each row being a (row, col) point

fusion_tools.utils.shapes.path_to_mask(path, shape): From SVG path to a boolean array where all pixels enclosed by the path are True, and the other pixels are False.

fusion_tools.utils.shapes.process_filters_queries(filter_list: list, spatial_list: list, structures: list, all_geo_list: list)

Filter GeoJSON list based on lists of both spatial and property filters.

Parameters:

filter_list (list) – List of property filters (keys = name: “name of property”, range: “either a list of categorical values or min-max for quantitative”)
spatial_list (list) – List of spatial filters (keys= type: “predicate”, structure: “name of structure that is basis of predicate”)
structures (list) – List of included structures in final GeoJSON
all_geo_list (list) – List of GeoJSON objects to search

Returns:

Filtered GeoJSON where all included structures are included as one FeatureCollection and a reference list containing original structure name and index

Return type:

tuple

fusion_tools.utils.shapes.spatially_aggregate(child_geo: dict, parent_geos: list, separate: bool = True, summarize: bool = True, ignore_list: list = ['_id', '_index'])

Aggregate intersecting feature properties to a provided GeoJSON

Parameters:

child_geo (dict) – GeoJSON object that is receiving aggregated properties
parent_geos (list) – List of GeoJSON objects which are intersecting with child_geo

Returns:

Updated child_geo object with new properties from intersecting parent_geos

Return type:

dict