Merge pull request #12 from TeamNCMC/config-brainglobe

More explicit support for Brainglobe atlases

Author: guillaumelegoc

README.md

@@ -58,5 +58,8 @@ mkdocs serve
 Head to [http://localhost:8000/](http://localhost:8000/) from a web browser.
 The documentation is built with [MkDocs](https://www.mkdocs.org/) using the [Material theme](https://squidfunk.github.io/mkdocs-material/). [KaTeX](https://katex.org/) CSS and fonts are embedded instead of using a CDN, and are under a [MIT license](https://opensource.org/license/MIT).
 
+## Contributing
+
+
 ## Credits
 `cuisto` has been primarly developed by [Guillaume Le Goc](https://legoc.fr) in [Julien Bouvier's lab](https://www.bouvier-lab.com/) at [NeuroPSI](https://neuropsi.cnrs.fr/). The clever name was found by Aurélie Bodeau.

configs/config_template.toml

@@ -12,16 +12,16 @@
 #   - matplotlib colors : https://matplotlib.org/stable/gallery/color/color_demo.html
 #
 # Configuration file part of the python cuisto package.
-# version : 2.1
+# version : 2.2
 ########################################################################################
 
 object_type = "Cells"  # name of QuPath base classification (eg. without the ": subclass" part)
 segmentation_tag = "cells"  # type of segmentation, matches directory name, used only in the full pipeline
 
 [atlas]  # information related to the atlas used
 name = "allen_mouse_10um"  # brainglobe-atlasapi atlas name
-type = "brain"  # brain or cord (eg. registration done in ABBA or abba_python)
-midline = 5700  # midline Z coordinates (left/right limit) in microns
+type = "abba"  # abba or brainglobe : registration done with regular ABBA (except allen_mouse_10um_java) or abba_python)
+midline = 5700  # midline coordinates in microns (left/right limit, Z for abba, X for brainglobe) 
 outline_structures = ["root", "CB", "MY", "P"]  # structures to show an outline of in heatmaps
 
 [channels]  # information related to imaging channels

cuisto/config.py

@@ -42,6 +42,20 @@ def __init__(self, config_file):
         else:
             self.bg_atlas = None
 
+        # name axes to handle ABBA/Brainglobe atlases differences
+        if self.atlas["type"] in ("abba", "brain"):
+            self.Xname = "Atlas_X"  # antero-posterior (rostro-caudal)
+            self.Yname = "Atlas_Y"  # infero-superior (dorso-ventral)
+            self.Zname = "Atlas_Z"  # left-right (medio-lateral)
+        elif self.atlas["type"] in ("brainglobe", "cord"):
+            self.Xname = "Atlas_Z"  # antero-posterior (rostro-caudal)
+            self.Yname = "Atlas_Y"  # infero-superior (dorso-ventral)
+            self.Zname = "Atlas_X"  # left-right (medio-lateral)
+        else:
+            raise ValueError(
+                f"{self.atlas['type']} not supported, choose either 'abba' or 'brainglobe'."
+            )
+
         self.get_blacklist()
         self.get_leaves_list()
 
@@ -125,6 +139,6 @@ def get_hue_palette(self, mode: str) -> dict:
             }
         else:
             palette = None
-            warnings.warn(f"hue={self.regions["display"]["hue"]} not supported.")
+            warnings.warn(f"hue={self.regions['display']['hue']} not supported.")
 
         return palette

cuisto/display.py

@@ -796,12 +796,12 @@ def plot_2D_distributions(df: pd.DataFrame, cfg):
     cbar_kws = dict(label="count")
 
     # determine which axes are going to be inverted
-    if cfg.atlas["type"] == "brain":
+    if cfg.atlas["type"] in ("abba", "brain"):
         cor_invertx = True
         cor_inverty = False
         top_invertx = True
         top_inverty = False
-    elif cfg.atlas["type"] == "cord":
+    elif cfg.atlas["type"] in ("brainglobe", "cord"):
         cor_invertx = False
         cor_inverty = False
         top_invertx = True
@@ -812,8 +812,8 @@ def plot_2D_distributions(df: pd.DataFrame, cfg):
     outline_kws["view"] = "sagittal"
     nice_joint_plot(
         df,
-        x="Atlas_X",
-        y="Atlas_Y",
+        x=cfg.Xname,
+        y=cfg.Yname,
         xlabel="Rostro-caudal (mm)",
         ylabel="Dorso-ventral (mm)",
         outline_kws=outline_kws,
@@ -825,8 +825,8 @@ def plot_2D_distributions(df: pd.DataFrame, cfg):
     outline_kws["view"] = "coronal"
     nice_joint_plot(
         df,
-        x="Atlas_Z",
-        y="Atlas_Y",
+        x=cfg.Zname,
+        y=cfg.Yname,
         xlabel="Medio-lateral (mm)",
         ylabel="Dorso-ventral (mm)",
         invertx=cor_invertx,
@@ -841,8 +841,8 @@ def plot_2D_distributions(df: pd.DataFrame, cfg):
     outline_kws["view"] = "top"
     nice_joint_plot(
         df,
-        x="Atlas_X",
-        y="Atlas_Z",
+        x=cfg.Xname,
+        y=cfg.Zname,
         xlabel="Rostro-caudal (mm)",
         ylabel="Medio-lateral (mm)",
         invertx=top_invertx,
@@ -864,8 +864,8 @@ def plot_2D_distributions(df: pd.DataFrame, cfg):
         _ = nice_heatmap(
             df,
             animals,
-            x="Atlas_X",
-            y="Atlas_Y",
+            x=cfg.Xname,
+            y=cfg.Yname,
             xlabel="Rostro-caudal (mm)",
             ylabel="Dorso-ventral (mm)",
             invertx=True,
@@ -879,8 +879,8 @@ def plot_2D_distributions(df: pd.DataFrame, cfg):
         _ = nice_heatmap(
             df,
             animals,
-            x="Atlas_Z",
-            y="Atlas_Y",
+            x=cfg.Zname,
+            y=cfg.Yname,
             xlabel="Medio-lateral (mm)",
             ylabel="Dorso-ventral (mm)",
             inverty=True,

cuisto/io.py

@@ -112,12 +112,17 @@ def cat_csv_dir(directory, **kwargs) -> pd.DataFrame:
 
 
 def cat_json_dir(
-    directory: str, hemisphere_names: dict, atlas: BrainGlobeAtlas
+    directory: str,
+    hemisphere_names: dict,
+    atlas: BrainGlobeAtlas,
+    xname: str = "Atlas_X",
+    yname: str = "Atlas_Y",
+    zname: str = "Atlas_Z",
 ) -> pd.DataFrame:
     """
     Scans a directory for json files and concatenate them in a single DataFrame.
 
-    The json files must be generated with 'pipelineImportExport.groovy" or 
+    The json files must be generated with 'pipelineImportExport.groovy" or
     'exportFibersAtlasCoordinates.groovy' from a QuPath project.
 
     Parameters
@@ -129,6 +134,9 @@ def cat_json_dir(
         something else (eg. "Ipsi." and "Contra.").
     atlas : BrainGlobeAtlas
         Atlas to read regions from.
+    xname, yname, zname : str, optional
+        How to name x, y and z coordinates. Default is ABBA convention, eg. Atlas_X,
+        Atlas_Y and Atlas_Z, resp. corresponding to AP, DV, ML.
 
     Returns
     -------
@@ -160,9 +168,9 @@ def cat_json_dir(
         .reset_index()
         .rename(
             columns=dict(
-                x="Atlas_X",
-                y="Atlas_Y",
-                z="Atlas_Z",
+                x=xname,
+                y=yname,
+                z=zname,
                 index="Object ID",
                 classification="Classification",
             )
@@ -177,7 +185,9 @@ def cat_json_dir(
     df["Object type"] = "Detection"
 
     # add brain regions
-    df = utils.add_brain_region(df, atlas, col="Parent")
+    df = utils.add_brain_region(
+        df, atlas, col="Parent", xname=xname, yname=yname, zname=zname
+    )
 
     return df
 

cuisto/process.py

@@ -86,7 +86,7 @@ def process_animal(
             df_detections,
             cfg.hemispheres["names"],
             cfg.atlas["midline"],
-            col="Atlas_Z",
+            col=cfg.Zname,
             atlas_type=cfg.atlas["type"],
         )
         # add detection channel
@@ -104,19 +104,19 @@ def process_animal(
                 df_detections["Atlas_DV"],
                 df_detections["Atlas_ML"],
             ) = utils.ccf_to_stereo(
-                df_detections["Atlas_X"],
-                df_detections["Atlas_Y"],
-                df_detections["Atlas_Z"],
+                df_detections[cfg.Xname],
+                df_detections[cfg.Yname],
+                df_detections[cfg.Zname],
             )
         else:
             (
                 df_detections["Atlas_AP"],
                 df_detections["Atlas_DV"],
                 df_detections["Atlas_ML"],
             ) = (
-                df_detections["Atlas_X"],
-                df_detections["Atlas_Y"],
-                df_detections["Atlas_Z"],
+                df_detections[cfg.Xname],
+                df_detections[cfg.Yname],
+                df_detections[cfg.Zname],
             )
 
     # - Computations
@@ -270,7 +270,7 @@ def process_animals(
     # -- Saving
     if out_fmt:
         outdir = os.path.join(wdir, "quantification")
-        outfile = f"{cfg.object_type.lower()}_{cfg.atlas["type"]}_{'-'.join(animals)}.{out_fmt}"
+        outfile = f"{cfg.object_type.lower()}_{cfg.atlas['type']}_{'-'.join(animals)}.{out_fmt}"
         dfs = dict(
             df_regions=df_regions,
             df_coordinates=df_coordinates,

cuisto/utils.py

@@ -299,7 +299,7 @@ def add_hemisphere(
     hemisphere_names: dict,
     midline: float = 5700,
     col: str = "Atlas_Z",
-    atlas_type: str = "brain",
+    atlas_type: str = "abba",
 ) -> pd.DataFrame:
     """
     Add hemisphere (left/right) as a measurement for detections or annotations.
@@ -321,9 +321,10 @@ def add_hemisphere(
     col : str, optional
         Name of the column containing the Z coordinate (medio-lateral) in microns.
         Default is "Atlas_Z".
-    atlas_type : {"brain", "cord"}, optional
-        Type of atlas used for registration. Required because the brain atlas is swapped
-        between left and right while the spinal cord atlas is not. Default is "brain".
+    atlas_type : {"abba", "brainglobe"}, optional
+        Type of atlas used for registration. Required because the brain atlas provided
+        by ABBA is swapped between left and right while the brainglobe atlases are not.
+        Default is "abba".
 
     Returns
     -------
@@ -340,12 +341,12 @@ def add_hemisphere(
 
     if kind == "detection":
         # use midline
-        if atlas_type == "brain":
-            # brain atlas : beyond midline, it's left
+        if atlas_type in ("abba", "brain"):
+            # regular ABBA atlas : beyond midline, it's left
             df.loc[df[col] >= midline, "hemisphere"] = hemisphere_names["Left"]
             df.loc[df[col] < midline, "hemisphere"] = hemisphere_names["Right"]
-        elif atlas_type == "cord":
-            # cord atlas : below midline, it's left
+        elif atlas_type in ("brainglibe", "cord"):
+            # brainglobe atlas : below midline, it's left
             df.loc[df[col] <= midline, "hemisphere"] = hemisphere_names["Left"]
             df.loc[df[col] > midline, "hemisphere"] = hemisphere_names["Right"]
 
@@ -399,7 +400,12 @@ def add_channel(
 
 
 def add_brain_region(
-    df: pd.DataFrame, atlas: BrainGlobeAtlas | None, col="Parent"
+    df: pd.DataFrame,
+    atlas: BrainGlobeAtlas | None,
+    col: str = "Parent",
+    xname: str = "Atlas_X",
+    yname: str = "Atlas_Z",
+    zname: str = "Altas_Z",
 ) -> pd.DataFrame:
     """
     Add brain region to a DataFrame with `Atlas_X`, `Atlas_Y` and `Atlas_Z` columns.
@@ -417,6 +423,9 @@ def add_brain_region(
     atlas : BrainGlobeAtlas or None
     col : str, optional
         Column in which to put the regions acronyms. Default is "Parent".
+    xname, yname, zname : str, optional
+        Name of the x, y, z coordinates columns in `df`. They should correspond to what
+        is expected by brainglobe-atlasapi : x is AP, y is DV and Z is ML.
 
     Returns
     -------
@@ -435,15 +444,15 @@ def add_brain_region(
     lims = atlas.shape_um  # out of brain
 
     # set out-of-brain objects at 0 so we get "root" as their parent
-    df_in.loc[(df_in["Atlas_X"] >= lims[0]) | (df_in["Atlas_X"] < 0), "Atlas_X"] = 0
-    df_in.loc[(df_in["Atlas_Y"] >= lims[1]) | (df_in["Atlas_Y"] < 0), "Atlas_Y"] = 0
-    df_in.loc[(df_in["Atlas_Z"] >= lims[2]) | (df_in["Atlas_Z"] < 0), "Atlas_Z"] = 0
+    df_in.loc[(df_in[xname] >= lims[0]) | (df_in[xname] < 0), xname] = 0
+    df_in.loc[(df_in[yname] >= lims[1]) | (df_in[yname] < 0), yname] = 0
+    df_in.loc[(df_in[zname] >= lims[2]) | (df_in[zname] < 0), zname] = 0
 
     # build the multi index, in pixels and integers
     ixyz = (
-        df_in["Atlas_X"].divide(res[0]).astype(int),
-        df_in["Atlas_Y"].divide(res[1]).astype(int),
-        df_in["Atlas_Z"].divide(res[2]).astype(int),
+        df_in[xname].divide(res[0]).astype(int),
+        df_in[yname].divide(res[1]).astype(int),
+        df_in[zname].divide(res[2]).astype(int),
     )
     # convert i, j, k indices in raveled indices
     linear_indices = np.ravel_multi_index(ixyz, dims=atlas.annotation.shape)
@@ -556,7 +565,7 @@ def get_data_coverage(df: pd.DataFrame, col="Atlas_AP", by="animal") -> pd.DataF
     df : pd.DataFrame
         _description_
     col : str, optional
-        Key in `df`, default is "Atlas_X".
+        Key in `df`, default is "Atlas_AP".
     by : str, optional
         Key in `df` , default is "animal".
 

docs/demo_notebooks/cells_distributions.ipynb

@@ -3,6 +3,9 @@ You can head to [the ABBA documentation](https://abba-documentation.readthedocs.
 
 You will find below installation instructions for the regular [ABBA Fiji plugin](#abba-fiji), which proposes only the mouse and rat brain atlases. To be able to use the [Brainglobe atlases](https://brainglobe.info/documentation/brainglobe-atlasapi/usage/atlas-details.html#available-atlases), you will need the [Python version](#abba-python). The two can be installed alongside each other.
 
+!!! danger "Important"
+    Please have a look at this [few considerations](tips-abba.md#abba-and-brainglobe-atlases) related to coordinates systems in ABBA and Brainglobe atlases and their consequences on downstream analysis.
+
 ## ABBA Fiji
 ### Install Fiji
 Install the "batteries-included" distribution of ImageJ, Fiji, from the [official website](https://fiji.sc/).