Formatting

Author: k1o0

ibllib/atlas/__init__.py

@@ -3,8 +3,8 @@
 For examples and tutorials on using the IBL atlas package, see
 https://docs.internationalbrainlab.org/atlas_examples.html
 
-TODO Explain differences between this package and the Allen SDK.
-Much of this was adapted from the [cortexlab allenCCF repository](https://github.com/cortex-lab/allenCCF).
+.. TODO Explain differences between this package and the Allen SDK.
+Much of this was adapted from the `cortexlab allenCCF repository <https://github.com/cortex-lab/allenCCF>`_.
 
 Terminology
 -----------
@@ -37,12 +37,12 @@
 There are two principal mouse brain atlases in this module:
 
 1. The Allen Common Coordinate Framework (CCF) [1]_.
-2. The Mouse Brain in Stereotaxic Coordinates (MBSC) 4th Edition, by Paxinos G, and Franklin KBJ [2]_ and matched to
-   to the Allen Common Coordiante Framework by Chon et al. [10]
+2. The Mouse Brain in Stereotaxic Coordinates (MBSC) 4th Edition, by Paxinos G, and Franklin KBJ [2]_, matched to
+   to the Allen Common Coordiante Framework by Chon et al. [3]_.
 
 The latter is referred to here as the 'Franklin-Paxinos atlas'.  These atlases comprise a 3D array of voxels and their associated
 brain region identifiers (labels) at a given resolution. The Allen Atlas can be instantiated in 10um, 25um or 50um resolution.
-The Franklin-Paxinos atlas has a resolution of 10um in the ML and DV axis, and 100um in the AP axis. TODO Mention flat maps.
+The Franklin-Paxinos atlas has a resolution of 10um in the ML and DV axis, and 100um in the AP axis. **TODO Mention flat maps.**
 
 
 Scalings
@@ -51,14 +51,14 @@
 to account for distortion that occurs during the imaging and tissue fixation process:
 
 1. The Needles atlas - 40 C57BL/6J (p84) mice underwnt MRI imaging post-mortem while the brain was still in the skull, followed by
-   conventional Nissl histology [3]_. These mouse brain atlas images combined with segmentation (known as DSURQE) were manually
+   conventional Nissl histology [4]_. These mouse brain atlas images combined with segmentation (known as DSURQE) were manually
    transformed onto the Allen CCF atlas to determine the scaling.
 2. The MRI Toronto - 12 p65 mice MRI images were taken *in vivo* then averaged and transformed on the Allen CCF atlas to determine
-   the scaling [4]_.
+   the scaling [5]_.
 
 All scaling is currently linear. Scaling of this kind can be applied arbitrarily to better represent a specific mouse age and
-sex [4]_. NB: In addition to distortions, the Allen CFF atlas is pitched down by about 5 degrees relative to a flat skull (where
-bregma and lambda are at the same DV height) [5]_, however this is not currently accounted for.
+sex [5]_. NB: In addition to distortions, the Allen CFF atlas is pitched down by about 5 degrees relative to a flat skull (where
+bregma and lambda are at the same DV height) [6]_, however this is not currently accounted for.
 
 
 Mappings
@@ -69,7 +69,7 @@
 
 1. Beryl - brain atlas annotations without layer sub-divisions or certain ganglial/nucleus sub-devisisions (e.g. the core/shell
    sub-division of the lateral geniculate nucleus). Fibre tracts, pia, etc. are also absent.  The choice of which areas to combine
-   was guided partially by the computed volume of each area.  This mapping is used in the brainwide map and prior papers [6]_ [7]_
+   was guided partially by the computed volume of each area.  This mapping is used in the brainwide map and prior papers [7]_, [8]_
    .
 2. Cosmos - coarse brain atlas annotations, dividing the atlas into 10 broad areas: isocortex, olfactory areas, cortical subplate,
    cerebral nuclei, thalamus, hypothalamus, midbrain, hindbrain, cerebellum and hippocampal formation.
@@ -78,7 +78,7 @@
 
 Non-Allen mappings:
 
-3. Swanson - the brain atlas annotations from the Swansan rat brain flat map [8]_, mapped to the Allen atlas manually by Olivier
+3. Swanson - the brain atlas annotations from the Swansan rat brain flat map [9]_, mapped to the Allen atlas manually by Olivier
    Winter. See `Fixtures`_ for details.
 
 Each mapping includes both a lateralized (suffix '-lr') and non-laterized version. The lateralized mappings assign a different ID
@@ -89,12 +89,13 @@
 
 Notes
 -----
-The Allen atlas and the CCF annotations have different release dates and versions [8]_. The annotations used by IBL are the 2017
+The Allen atlas and the CCF annotations have different release dates and versions [10]_. The annotations used by IBL are the 2017
 version.
 
 The IBL uses the following conventions:
 
-- All atlas images have dimensions (AP, ML, DV). With C-ordering this makes coronal slicing most efficient.
+- All atlas images have dimensions (AP, ML, DV). With C-ordering this makes coronal slicing most efficient. The origin is the top
+  left corner of the image.
 - Coordinates are provided in the order (ML AP DV) and are in meters relative to bregma.
 - Left hemisphere ML coordinates are -ve; right, +ve.
 - AP coordinates anterior to bregma are +ve; posterior, -ve.
@@ -104,29 +105,6 @@
 - All left hemisphere regions have negative region IDs in all lateralized mappings.
 
 
-References
-----------
-.. [1] © 2015 Allen Institute for Brain Science. Allen Mouse Brain Atlas (2015) with region annotations (2017).
-   Available from: http://download.alleninstitute.org/informatics-archive/current-release/mouse_ccf/annotation/
-.. [2] Paxinos G, and Franklin KBJ (2012) The Mouse Brain in Stereotaxic Coordinates, 4th edition (Elsevier Academic Press)
-.. [3] Dorr AE, Lerch JP, Spring S, Kabani N, Henkelman RM (2008). High resolution three-dimensional brain atlas using an average
-   magnetic resonance image of 40 adult C57Bl/6J mice. Neuroimage 42(1):60-9. [doi 10.1016/j.neuroimage.2008.03.037]
-.. [4] Qiu, LR, Fernandes, DJ, Szulc-Lerch, KU et al. (2018) Mouse MRI shows brain areas relatively larger
-   in males emerge before those larger in females. Nat Commun 9, 2615. [doi 10.1038/s41467-018-04921-2]
-.. [5] International Brain Laboratory et al. (2022) Reproducibility of in-vivo electrophysiological measurements in mice.
-   bioRxiv. [doi 10.1101/2022.05.09.491042]
-.. [6] International Brain Laboratory et al. (2023) A Brain-Wide Map of Neural Activity during Complex Behaviour.
-   bioRxiv. [doi 10.1101/2023.07.04.547681]
-.. [7] Findling C et al. (2023) Brain-wide representations of prior information in mouse decision-making.
-   bioRxiv. [doi 10.1101/2023.07.04.547684]
-.. [8] Swanson LW (2018) Brain maps 4.0—Structure of the rat brain: An open access atlas with global nervous system nomenclature
-   ontology and flatmaps. J Comp Neurol. [doi 10.1002/cne.24381]
-.. [9] Allen Mouse Common Coordinate Framework Technical White Paper (October 2017 v3)
-   http://help.brain-map.org/download/attachments/8323525/Mouse_Common_Coordinate_Framework.pdf
-.. [10] Chon et al (2019) Enhanced and unified anatomical labeling for a common mouse brain atlas
-   [doi 10.1038/s41467-019-13057-w]
-
-
 Examples
 --------
 Below are some breif API examples. For in depth tutorials on using the IBL atlas package, see
@@ -145,10 +123,11 @@
 Fixtures
 --------
 
-* TODO List the data files in this package, their purpose, data types, shape, etc.
-* TODO List the remote files used by this package, e.g. annotations files, swansonpaths.json, etc.
+.. TODO List the data files in this package, their purpose, data types, shape, etc.
+.. TODO List the remote files used by this package, e.g. annotations files, swansonpaths.json, etc.
 
-### Local files
+Local files
+^^^^^^^^^^^
 
 * **allen_structure_tree.csv** - TODO Document. Where does this come from? Is it modified from either structure_tree_safe.csv or
   structure_tree_safe_2017.csv?
@@ -162,33 +141,58 @@
   The rows contain the correspondence of each mapping to the int64 index of the lateralized Allen structure tree.  The table is
   generated by ibllib.atlas.regions.BrainRegions._compute_mappings.
 
-### Remote files
+Remote files
+^^^^^^^^^^^^
 
 * **annotation_<res_um>.nrrd** - A 3D volume containing indicies of the regions in the associated
   structure tree.  `res_um` indicates the isometric spacing in microns.  These uint16 indicies are
   known as the region 'index' in the structure tree, i.e. the position of the region in the
   flattened tree.
 * **average_template_<res_um>.nrrd** - TODO Document
 * **annotation_<res_um>_lut_<LUT_VERSION>.npz** - TODO Document
-* FranklinPaxinons/annotation_<res_um>.npz - A 3D volume containing indices of the regions associated with
-  the Franklin Paxinos structure tree. The volume was created from the images provided in Supplemtary Data 4 of
-  reference [10] and stitched together as a single volume using SimpleITK.
-* FranklinPaxinons/average_template_<res_um>.npz - A 3D volume containing the Allen dwi image slices corresponding to
-  the slices in the annotation volume. The volume was created from the images provided in Supplemtary Data 5 of
-  reference [10] and stitched together as a single volume using SimpleITK.
+* **FranklinPaxinons/annotation_<res_um>.npz** - A 3D volume containing indices of the regions associated with the Franklin-
+  Paxinos structure tree.
+* **FranklinPaxinons/average_template_<res_um>.npz** - A 3D volume containing the Allen dwi image slices corresponding to
+  the slices in the annotation volume [*] .
 * **swansonpaths.json** - The paths of a vectorized Swanson flatmap image [*]. The vectorized version was generated
   from the Swanson bitmap image using the matlab contour function to find the paths for each region. The paths for each
-  region were then simplified using the Ramer Douglas Peucker algorithm https://rdp.readthedocs.io/en/latest/
+  region were then simplified using the `Ramer Douglas Peucker algorithm <https://rdp.readthedocs.io/en/latest/>`_
 * **swanson2allen.npz** - TODO Document who made this, its contents, purpose and data type
 * **<flatmap_name>_<res_um>.nrrd** - TODO Document who made this, its contents, purpose and data type
 * **gene-expression.pqt** - TODO Document who made this, its contents, purpose and data type
 * **gene-expression.bin** - TODO Document who made this, its contents, purpose and data type.
 
+.. [*] The annotation and average template volumes were created from the images provided in Supplemtary Data 4 of Chon et al. [3]_
+   and stitched together as a single volume using SimpleITK.
 .. [*] output of aggType 2 in https://github.com/cortex-lab/allenCCF/blob/master/Browsing%20Functions/aggregateAcr.m
 .. [*] output of aggType 1 in https://github.com/cortex-lab/allenCCF/blob/master/Browsing%20Functions/aggregateAcr.m
 .. [*] the paths were generated from a bitmap of the
-   [BM3 rat flatmap 3.0 foldout poster](https://larrywswanson.com/wp-content/uploads/2015/03/BM3-flatmap-foldout.pdf) in
-   [Swanson LW (2004) Brain Maps, 3rd ed.](https://larrywswanson.com/?page_id=164) TODO where is code for this?
+   `BM3 rat flatmap 3.0 foldout poster <https://larrywswanson.com/wp-content/uploads/2015/03/BM3-flatmap-foldout.pdf>`_
+   in `Swanson LW (2004) Brain Maps, 3rd ed. <https://larrywswanson.com/?page_id=164>`_ TODO where is code for this?
+
+
+References
+----------
+.. [1] © 2015 Allen Institute for Brain Science. Allen Mouse Brain Atlas (2015) with region annotations (2017).
+   Available from: http://download.alleninstitute.org/informatics-archive/current-release/mouse_ccf/annotation/
+.. [2] Paxinos G, and Franklin KBJ (2012) The Mouse Brain in Stereotaxic Coordinates, 4th edition (Elsevier Academic Press)
+.. [3] Chon U et al (2019) Enhanced and unified anatomical labeling for a common mouse brain atlas
+   [doi 10.1038/s41467-019-13057-w]
+.. [4] Dorr AE, Lerch JP, Spring S, Kabani N, Henkelman RM (2008). High resolution three-dimensional brain atlas using an average
+   magnetic resonance image of 40 adult C57Bl/6J mice. Neuroimage 42(1):60-9. [doi 10.1016/j.neuroimage.2008.03.037]
+.. [5] Qiu, LR, Fernandes, DJ, Szulc-Lerch, KU et al. (2018) Mouse MRI shows brain areas relatively larger
+   in males emerge before those larger in females. Nat Commun 9, 2615. [doi 10.1038/s41467-018-04921-2]
+.. [6] International Brain Laboratory et al. (2022) Reproducibility of in-vivo electrophysiological measurements in mice.
+   bioRxiv. [doi 10.1101/2022.05.09.491042]
+.. [7] International Brain Laboratory et al. (2023) A Brain-Wide Map of Neural Activity during Complex Behaviour.
+   bioRxiv. [doi 10.1101/2023.07.04.547681]
+.. [8] Findling C et al. (2023) Brain-wide representations of prior information in mouse decision-making.
+   bioRxiv. [doi 10.1101/2023.07.04.547684]
+.. [9] Swanson LW (2018) Brain maps 4.0—Structure of the rat brain: An open access atlas with global nervous system nomenclature
+   ontology and flatmaps. J Comp Neurol. [doi 10.1002/cne.24381]
+.. [10] Allen Mouse Common Coordinate Framework Technical White Paper (October 2017 v3)
+   http://help.brain-map.org/download/attachments/8323525/Mouse_Common_Coordinate_Framework.pdf
+
 """
 from .atlas import *  # noqa
 from .regions import regions_from_allen_csv