magmap.atlas.ontology module

Handle ontology lookup.

class magmap.atlas.ontology.LabelColumns(value)[source]

Bases: Enum

Label data frame columns enumeration.

FROM_LABEL = 'FromLabel'
TO_LABEL = 'ToLabel'
class magmap.atlas.ontology.LabelsRef(path_ref=None)[source]

Bases: object

Labels reference container and worker class.

Variables:

  • path_ref – Path to labels reference file.

  • loaded_ref – Loaded reference object.

  • ref_lookup – Reference in a dict format.

create_aba_reverse_lookup(labels_ref)[source]

Create a reverse lookup dictionary for Allen Brain Atlas style ontology files.

Parameters:

labels_ref – The ontology file as a parsed JSON dictionary.

Return type:

Dict[int, Any]

Returns:

Reverse lookup dictionary as output by ontology.create_reverse_lookup().

create_lookup_pd(df=None)[source]

Create a lookup dictionary from a Pandas data frame.

Parameters:

df (Optional[DataFrame], default: None) – Pandas data frame, assumed to have at least columns corresponding to :const:config.ABAKeys.ABA_ID or :const:config.AtlasMetrics.REGION and :const:config.ABAKeys.ABA_NAME or :const:config.AtlasMetrics.REGION_NAME. Defaults to None, in which case loaded_ref is used.

Return type:

Dict[int, Any]

Returns:

Dictionary similar to that generated from :meth:create_reverse_lookup, with IDs as keys and values corresponding of another dictionary with :const:NODE and :const:PARENT_IDS as keys. :const:NODE in turn contains a dictionary with entries for each Enum in :const:config.ABAKeys.

Raises:

KeyError – if the ID/region and name keys cannot be found.

create_ref_lookup(labels_ref=None)[source]

Wrapper to create a reference lookup from different sources.

Reference data frames and dictionaries are converted to a dictionary that can be looked up by ID.

Parameters:

labels_ref (Union[DataFrame, Dict, None], default: None) – Reference dictionary or data frame, typically loaded from load_labels(). Defaults to None, in which case loads_ref is used.

Return type:

Dict[int, Any]

Returns:

Ordered dictionary for looking up by ID.

create_reverse_lookup(nested_dict, key, key_children, id_dict=None, parent_list=None)[source]

Create a reveres lookup dictionary with the values of the original dictionary as the keys of the new dictionary.

Each value of the new dictionary is another dictionary that contains “node”, the dictionary with the given key-value pair, and “parent_ids”, a list of all the parents of the given node. This entry can be used to track all superceding dictionaries, and the node can be used to find all its children.

Parameters:

  • nested_dict (dict) – A dictionary that contains a list of dictionaries in the key_children entry.

  • key (Any) – Key that contains the values to use as keys in the new dictionary. The values of this key should be unique throughout the entire nested_dict and thus serve as IDs.

  • key_children (Any) – Name of the children key, which contains a list of further dictionaries but can be empty.

  • id_dict (OrderedDict) – The output dictionary as an OrderedDict to preserve key order (though not hierarchical structure) so that children will come after their parents. Defaults to None to create an empty OrderedDict.

  • parent_list (list[Any]) – List of values for the given key in all parent dictionaries.

Returns:

A dictionary with the original values as the keys, which each map to another dictionary containing an entry with the dictionary holding the given value and another entry with a list of all parent dictionary values for the given key.

Return type:

OrderedDict

get_node(nested_dict, key, value, key_children)[source]

Get a node from a nested dictionary by iterating through all dictionaries until the specified value is found.

Parameters:

  • nested_dict – A dictionary that contains a list of dictionaries in the key_children entry.

  • key – Key to check for the value.

  • value – Value to find, assumed to be unique for the given key.

  • key_children – Name of the children key, which contains a list of further dictionaries but can be empty.

Returns:

The node matching the key-value pair, or None if not found.

get_ref_lookup_as_df()[source]

Get the reference lookup dict as a data frame.

Return type:

Optional[DataFrame]

Returns:

ref_lookup converted to a data frame. Returns the object as-is if it is already a data frame.

load()[source]

Load the labels reference file to a lookup dictionary.

Loads the file from path_ref to loaded_ref and creates a lookup dictionary stored in lookup_ref.

Returns:

This instance for chained calls.

load_labels_ref(path=None)[source]

Load labels from a reference JSON or CSV file.

Parameters:

path (Optional[str], default: None) – Path to labels reference; defaults to None to use path_ref.

Return type:

Union[Dict, DataFrame]

Returns:

A JSON decoded object (eg dictionary) if the path has a JSON extension, or a data frame.

Raises:

FileNotFoundError – if path could not be loaded or parsed.

magmap.atlas.ontology.convert_itksnap_to_df(path)[source]

Convert an ITK-SNAP labels description file to a CSV file.

MagellanMapper can read this type of CSV file.

Parameters:

path (str) – Path to description file.

Returns:

Pandas data frame of the description file.

magmap.atlas.ontology.get_children_from_id(labels_ref_lookup, label_id, incl_parent=True, both_sides=False)[source]

Get the children of a given atlas ID.

Parameters:

  • labels_ref_lookup – The labels reference lookup, assumed to be generated by create_reverse_lookup() to look up by ID.

  • label_id – ID of the label to find, which can be negative.

  • incl_parent (default: True) – True to include label_id itself in the list of children; defaults to True.

  • both_sides (default: False) – True to include both sides, ie positive and negative values of each ID. Defaults to False.

Returns:

A list of all children of the given ID, in order from highest (numerically lowest) level to lowest.

magmap.atlas.ontology.get_children_from_id_df(df, label_id, label_col, parent_col, incl_parent=True, ids=None)[source]

Get the children of a given atlas ID from a data frame.

Parameters:

  • df (DataFrame) – Data frame, which must include a column of label IDs and another column of the immediate parent ID for each label.

  • label_id (Union[int, Sequence[int]]) – ID or sequence of IDs whose children will be returned.

  • label_col (str) – Name of label ID column.

  • parent_col (str) – Name of immediate parent ID column.

  • incl_parent (bool, default: True) – True to include label_ids in the output.

  • ids (Optional[List[int]], default: None) – List of children, only for recursion.

Return type:

List[int]

Returns:

List of children, including parent(s) unless incl_parent is False.

magmap.atlas.ontology.get_label(coord, labels_img, labels_lookup, scaling=None, level=None, rounding=False)[source]

Get the atlas label for the given coordinates.

Parameters:

  • coord (Sequence[int]) – Coordinates of experiment image in (z, y, x) order.

  • labels_img (ndarray) – The registered image whose intensity values correspond to label IDs.

  • labels_lookup (Dict[int, Dict]) – The labels reference lookup, passed to get_label_at_level().

  • scaling (Optional[Sequence[int]], default: None) – Scaling factor for the labels image size compared with the experiment image; defaults to None.

  • level (Optional[int], default: None) – The ontology level as an integer to target; defaults to None.

  • rounding (bool, default: False) – True to round coordinates after scaling (see :func:get_label_ids_from_position); defaults to False.

Return type:

Optional[Dict[str, Any]]

Returns:

The label dictionary at those coordinates, or None if no label is found.

magmap.atlas.ontology.get_label_at_level(label_id, labels_lookup, level=None)[source]

Get atlas label at the given level.

Parameters:

  • label_id (Union[int, Sequence[int]]) – Label ID or sequence of IDs.

  • labels_lookup (Dict[int, Dict]) – The labels reference lookup, assumed to be generated by ontology.create_reverse_lookup() to look up by ID.

  • level (Optional[int], default: None) – The ontology level as an integer to target; defaults to None. If None, level will be ignored, and the exact matching label to the given coordinates will be returned. If a level is given, the label at the highest (numerically lowest) level encompassing this region will be returned.

Return type:

Optional[Dict[str, Any]]

Returns:

The label dictionary at those coordinates, or None if no label is found.

magmap.atlas.ontology.get_label_ids_from_position(coord_scaled, labels_img)[source]

Get the atlas label IDs for the given coordinates.

Parameters:

  • coord_scaled (numpy.ndarray) – 2D array of coordinates in [[z,y,x], ...] format, or a single row as a 1D array.

  • labels_img (numpy.ndarray) – Labeled image from which to extract labels at coordinates in coord_scaled.

Returns:

An array of label IDs corresponding to coord, or a scalar of one ID if only one coordinate is given.

Return type:

numpy.ndarray

magmap.atlas.ontology.get_label_item(label, item_key, key='node')[source]

Convenience function to get the item from the sub-label.

Parameters:

  • label (dict) – The label dictionary. Assumes that label is a nested dictionary.

  • item_key (str) – Key for item to retrieve from within label[key].

  • key (str) – First level key; defaults to NODE.

Returns:

The label item, or None if not found.

magmap.atlas.ontology.get_label_name(label, side=False, aba_key=None)[source]

Get the atlas region name from the label.

Parameters:

  • label (Dict[str, Any]) – The label dictionary.

  • side (bool, default: False) – True to add side suffix; defaults to False.

  • aba_key (Optional[ABAKeys], default: None) – ABA enum to get from label; defaults to None, in which case the name will be retrieved.

Returns:

The atlas region name, or None if not found.

magmap.atlas.ontology.get_label_side(label_id)[source]

Convert label IDs into side strings.

The convention used here is that positive values = right, negative values = left.

TODO: consider making pos/neg side correspondence configurable.

Parameters:

label_id (int, List[int]) – Label ID or sequence of IDs to convert, where all negative labels are considered right, all positive are left, and any mix of pos, neg, or zero are both.

Returns:

str: Value of corresponding config.HemSides enum.

magmap.atlas.ontology.get_region_middle(labels_ref_lookup, label_id, labels_img, scaling=None, both_sides=False, incl_children=True)[source]

Approximate the middle position of a region by taking the middle value of its sorted list of coordinates.

The region’s coordinate sorting prioritizes z, followed by y, etc, meaning that the middle value will be closest to the middle of z but may fall be slightly away from midline in the other axes if this z does not contain y/x’s around midline. Getting the coordinate at the middle of this list rather than another coordinate midway between other values in the region ensures that the returned coordinate will reside within the region itself, including non-contingous regions that may be intermixed with coordinates not part of the region.

Parameters:

  • labels_ref_lookup (Dict[int, Dict]) – The labels reference lookup, assumed to be generated by ontology.create_reverse_lookup() to look up by ID.

  • label_id (Union[int, Sequence[int]]) – ID of the label to find, or sequence of IDs.

  • labels_img (ndarray) – The registered image whose intensity values correspond to label IDs.

  • scaling (Optional[Sequence[int]], default: None) – Scaling factors as a Numpy array in z,y,x for the labels image size compared with the experiment image.

  • both_sides (Union[bool, Sequence[bool]], default: False) – True to include both sides, or sequence of booleans corresponding to label_id; defaults to False.

  • incl_children (bool, default: True) – True to include children of label_id, False to include only label_id; defaults to True.

Return type:

Tuple[Optional[Sequence[int]], Optional[ndarray], Optional[Sequence[int]]]

Returns:

Tuple of coord, the middle value of a list of all coordinates in the region at the given ID; img_region, a boolean mask of the region within labels_img; and region_ids, a list of the IDs included in the region. If labels_ref_lookup is None, all values are None.

magmap.atlas.ontology.labels_to_parent(labels_ref_lookup, level=None, allow_parent_same_level=False)[source]

Generate a dictionary mapping label IDs to parent IDs at a given level.

Parents are considered to be “below” (numerically lower level) their children, or at least at the same level if allow_parent_same_level is True.

Parameters:

  • labels_ref_lookup (dict) – The labels reference lookup, assumed to be an OrderedDict generated by ontology.create_reverse_lookup() to look up by ID while preserving key order to ensure that parents of any child will be reached prior to the child.

  • level (int) – Level at which to find parent for each label; defaults to None to get the parent immediately below the given label.

  • allow_parent_same_level (bool) – True to allow selecting a parent at the same level as the label; False to require the parent to be at least one level below. Defaults to False.

Returns:

Dictionary of label IDs to parent IDs at the given level. Labels at the given level will be assigned to their own ID, and labels below or without a parent at the level will be given a default level of 0.

Return type:

dict

magmap.atlas.ontology.make_labels_level(labels_np, ref, level, fn_prog=None)[source]

Convert a labels image to the given ontology level.

Parameters:

  • labels_np (ndarray) – Labels image.

  • ref (LabelsRef) – Atlas labels reference.

  • level (int) – Level at which labels_np will be remapped.

  • fn_prog (Optional[Callable[[int, str], None]], default: None) – Function to update progress. Takes an integer as a progress percentage and a string as a message. Defaults to None.

Return type:

ndarray

Returns:

The remapped labels_np, which will be altered in-place.

magmap.atlas.ontology.rel_to_abs_ages(rel_ages, gestation=19)[source]

Convert sample names to ages.

Parameters:

  • rel_ages (List[str]) – Sequence of strings in the format, [stage][relative_age_in_days], where stage is either “E” = “embryonic” or “P” = “postnatal”, such as “E3.5” for 3.5 days after conception, or “P10” for 10 days after birth.

  • gestation (int) – Number of days from conception until birth.

Returns:

Dictionary of {name: age_in_days}.

magmap.atlas.ontology.replace_labels(labels_img, df, clear=False, ref=None, combine_sides=False)[source]

Replace labels based on a data frame.

Parameters:

  • labels_img (numpy.ndarray) – Labels image array whose values will be converted in-place.

  • df (pandas.DataFrame) – Pandas data frame with from and to columns specified by LabelColumns values.

  • clear (bool) – True to clear all other label values.

  • ref (dict) – Dictionary to get all children from each label; defaults to None.

  • combine_sides (bool) – True to combine sides by converting both positive labels and their corresponding negative label; defaults to False.

Returns:

labels_img with values replaced in-place.

Return type:

numpy.ndarray

magmap.atlas.ontology.scale_coords(coord, scaling=None, clip_shape=None)[source]

Get the atlas label IDs for the given coordinates.

Parameters:

  • coord (Sequence[int]) – Coordinates of experiment image in z,y,x,... order. Can be an [n, >=3] array of coordinates.

  • scaling (Optional[Sequence[int]], default: None) – Scaling factor for the labels image size compared with the experiment image as z,y,x,...; defaults to None.

  • clip_shape (Optional[Sequence[int]], default: None) – Max image shape as z,y,x, used to round coordinates for extra precision. For simplicity, scaled values are simply floored. Repeated scaling such as upsampling after downsampling can lead to errors. If this parameter is given, values will instead by rounded to minimize errors while giving ints. Rounded values will be clipped to this shape minus 1 to stay within bounds.

Return type:

ndarray

Returns:

An scaled array of the same shape as coord. If the array contains a max of 3 coordinates columns, the array is casted to int. If not, the first 3 columns are rounded based on clip_shape, but the array type is float.