Merge c46a5ed into 049fc20

bg_atlasapi/bg_atlas.py

@@ -10,6 +10,7 @@
 COMPRESSED_FILENAME = "atlas.tar.gz"
 
 __all__ = [
+    "ExampleAtlas",
     "FishAtlas",
     "RatAtlas",
     "AllenBrain25Um",

bg_atlasapi/core.py

@@ -14,10 +14,6 @@
 )
 
 
-def _idx_from_coords(coords):
-    return tuple([int(c) for c in coords])
-
-
 class Atlas:
     """ Base class to handle atlases in BrainGlobe.
 
@@ -49,6 +45,12 @@ def __init__(self, path):
         self._hierarchy = None
         self._lookup = None
 
+    @property
+    def resolution(self):
+        """Make resolution more accessible from class.
+        """
+        return self.metadata["resolution"]
+
     @property
     def hierarchy(self):
         """
@@ -59,7 +61,7 @@ def hierarchy(self):
         return self._hierarchy
 
     @property
-    def lookup(self):
+    def lookup_df(self):
         """
             Returns a dataframe with id, acronym and name for each structure
         """
@@ -99,35 +101,42 @@ def hemispheres(self):
                 )
         return self._hemispheres
 
-    def hemisphere_from_coords(self, coords, as_string=False):
+    def hemisphere_from_coords(self, coords, microns=False, as_string=False):
         """Get the hemisphere from a coordinate triplet.
 
         Parameters
         ----------
         coords : tuple or list or numpy array
-            Triplet of coordinates.
+            Triplet of coordinates. Default in voxels, can be microns if
+            microns=True
+        microns : bool
+            If true, coordinates are interpreted in microns.
         as_string : bool
             If true, returns "left" or "right".
 
+
         Returns
         -------
         int or string
             Hemisphere label.
 
         """
-        hem = self.hemispheres[_idx_from_coords(coords)]
+
+        hem = self.hemispheres[self._idx_from_coords(coords, microns)]
         if as_string:
             hem = ["left", "right"][hem]
         return hem
 
     def structure_from_coords(
-        self, coords, as_acronym=False, hierarchy_lev=None
+        self, coords, microns=False, as_acronym=False, hierarchy_lev=None
     ):
         """Get the structure from a coordinate triplet.
         Parameters
         ----------
         coords : tuple or list or numpy array
             Triplet of coordinates.
+        microns : bool
+            If true, coordinates are interpreted in microns.
         as_acronym : bool
             If true, the region acronym is returned.
         hierarchy_lev : int or None
@@ -138,8 +147,10 @@ def structure_from_coords(
         int or string
             Structure containing the coordinates.
         """
-        rid = self.annotation[_idx_from_coords(coords)]
 
+        rid = self.annotation[self._idx_from_coords(coords, microns)]
+
+        # If we want to cut the result at some high level of the hierarchy:
         if hierarchy_lev is not None:
             rid = self.structures[rid]["structure_id_path"][hierarchy_lev]
 
@@ -184,6 +195,13 @@ def root_mesh(self):
     def root_meshfile(self):
         return self.meshfile_from_structure("root")
 
+    def _idx_from_coords(self, coords, microns):
+        # If microns are passed, convert:
+        if microns:
+            coords = [c / res for c, res in zip(coords, self.resolution)]
+
+        return tuple([int(c) for c in coords])
+
     # ------- BrainRender methods, might be useful to implement here ------- #
 
     # def get_region_unilateral(self):

bg_atlasapi/utils.py

@@ -15,11 +15,13 @@
 def check_internet_connection(
     url="http://www.google.com/", timeout=5, raise_error=True
 ):
-    """
-        Check that there is an internet connection
-
-        :param url: url to use for testing (Default value = 'http://www.google.com/')
-        :param timeout:  timeout to wait for [in seconds] (Default value = 5)
+    """Check that there is an internet connection
+    url : str
+        url to use for testing (Default value = 'http://www.google.com/')
+    timeout : int
+        timeout to wait for [in seconds] (Default value = 5).
+    raise_error : bool
+        if false, warning but no error.
     """
 
     try:
@@ -36,6 +38,16 @@ def check_internet_connection(
 
 
 def retrieve_over_http(url, output_file_path):
+    """Download file from remote location, with progress bar.
+
+    Parameters
+    ----------
+    url : str
+        Remote URL.
+    output_file_path : str or Path
+        Full file destination for download.
+
+    """
     CHUNK_SIZE = 4096
     response = requests.get(url, stream=True)
 
@@ -58,20 +70,24 @@ def retrieve_over_http(url, output_file_path):
 
 
 def conf_from_url(url):
+    """Read conf file from an URL.
+    Parameters
+    ----------
+    url : str
+        conf file url (in a repo, make sure the "raw" url is passed)
+
+    Returns
+    -------
+    conf object
+
+    """
     text = requests.get(url).text
     config = configparser.ConfigParser()
     config.read_string(text)
 
     return config
 
 
-def get_latest_atlases_version():
-    # TODO download version from online
-
-    versions = read_json("docs/atlases/latest_version.json")
-    return versions
-
-
 # --------------------------------- File I/O --------------------------------- #
 def read_json(path):
     with open(path, "r") as f:

tests/test_core_atlas.py

@@ -55,10 +55,23 @@ def test_structures(atlas):
     "coords", [[39.0, 36.0, 57.0], (39, 36, 57), np.array([39.0, 36.0, 57.0])]
 )
 def test_data_from_coords(atlas, coords):
+    res = atlas.resolution
     assert atlas.structure_from_coords(coords) == 997
     assert atlas.structure_from_coords(coords, as_acronym=True) == "root"
+    assert (
+        atlas.structure_from_coords(
+            [c * r for c, r in zip(coords, res)], microns=True, as_acronym=True
+        )
+        == "root"
+    )
     assert atlas.hemisphere_from_coords(coords) == 0
     assert atlas.hemisphere_from_coords(coords, as_string=True) == "left"
+    assert (
+        atlas.hemisphere_from_coords(
+            [c * r for c, r in zip(coords, res)], microns=True, as_string=True
+        )
+        == "left"
+    )
 
 
 def test_meshfile_from_id(atlas):
@@ -80,8 +93,8 @@ def test_mesh_from_id(atlas):
     assert np.allclose(mesh.points[0], [7896.56, 3384.15, 503.781])
 
 
-def test_lookup(atlas):
-    df_lookup = atlas.lookup
+def test_lookup_df(atlas):
+    df_lookup = atlas.lookup_df
     df = pd.DataFrame(
         dict(
             acronym=["root", "grey", "CH"],

tests/test_utils.py

@@ -0,0 +1,14 @@
+import pytest
+
+from bg_atlasapi import utils
+
+
+def test_http_check():
+    assert utils.check_internet_connection()
+    with pytest.raises(ConnectionError) as error:
+        utils.check_internet_connection(url="http://asd")
+    assert "No internet connection, try again" in str(error)
+
+    assert not utils.check_internet_connection(
+        url="http://asd", raise_error=False
+    )