ENH: add name to find method

fsl/data/atlases.py

@@ -595,12 +595,25 @@ class AtlasDescription(object):
                   labels, and a 3D ``LabelAtlas`` may have more values
                   than labels.
         """
-        if (index is     None and value is     None) or \
-           (index is not None and value is not None):
-            raise ValueError('Only one of index or value may be specified')
+        if ((index is not None) + (value is not None) + (name is not None)) != 1:
+            raise ValueError('Only one of index, value, or name may be specified')
+        if index is not None:   return self.labels[         index]
+        elif value is not None: return self.__labelsByValue[int(value)]
+        else:
+            matches = [l for l in self.labels if l.name == name]
+            if len(matches) == 0:
+                # look for partial matches only if there are no full matches
+                matches = [l for l in self.labels if l.name[:len(name)] == name]
+            if len(matches) == 0:
+                raise IndexError('No match for {} found in labels {}'.format(
+                    name, tuple(l.name for l in self.labels)
+                ))
+            elif len(matches) > 1:
+                raise IndexError('Multiple matches for {} found in labels {}'.format(
+                    name, tuple(l.name for l in self.labels)
+                ))
+            return matches[0]
 
-        if index is not None: return self.labels[         index]
-        else:                 return self.__labelsByValue[int(value)]
 
 
     def __eq__(self, other):

fsl/utils/filetree/trees/ProbtrackX.tree

-basename=fdt
+basename=fdt_paths
 
 probtrackx.log (log_cmd)
 {basename}.log (log_settings)

tests/test_atlases.py

@@ -254,16 +254,31 @@ def test_find():
 
             assert atlas     .find(value=label.value) == label
             assert atlas     .find(index=label.index) == label
+            assert atlas     .find(name=label.name) == label
             assert atlas.desc.find(value=label.value) == label
             assert atlas.desc.find(index=label.index) == label
+            assert atlas.desc.find(name=label.name) == label
+
+            if atlas is not lblatlas:
+                # lblatlas has a lot of very similar label names
+                assert atlas     .find(name=label.name[:-2]) == label
+                assert atlas.desc.find(name=label.name[:-2]) == label
 
         with pytest.raises(ValueError):
             atlas.find()
         with pytest.raises(ValueError):
             atlas.find(index=1, value=1)
+        with pytest.raises(ValueError):
+            atlas.find(index=1, name=1)
+        with pytest.raises(ValueError):
+            atlas.find(value=1, name=1)
 
         with pytest.raises(IndexError):
             atlas.find(index=len(labels))
+        with pytest.raises(IndexError):
+            atlas.find(name='InvalidROI')
+        with pytest.raises(IndexError):
+            atlas.find(name='')
 
         maxval = max([l.value for l in labels])
         with pytest.raises(KeyError):