[MRG] ADD: Brain.remove_foci() (#251)

* ADD:  Brain.remove_foci()

* STY

* STY

* TEST

Author: christianbrodbeck

surfer/tests/test_viz.py

@@ -227,16 +227,21 @@ def test_foci():
     coords = [[-36, 18, -3],
               [-43, 25, 24],
               [-48, 26, -2]]
-    brain.add_foci(coords, map_surface="white", color="gold")
+    brain.add_foci(coords, map_surface="white", color="gold", name='test1')
 
     subj_dir = utils._get_subjects_dir()
     annot_path = pjoin(subj_dir, subject_id, 'label', 'lh.aparc.a2009s.annot')
     ids, ctab, names = nib.freesurfer.read_annot(annot_path)
     verts = np.arange(0, len(ids))
     coords = np.random.permutation(verts[ids == 74])[:10]
     scale_factor = 0.7
-    brain.add_foci(coords, coords_as_verts=True,
-                   scale_factor=scale_factor, color="#A52A2A")
+    brain.add_foci(coords, coords_as_verts=True, scale_factor=scale_factor,
+                   color="#A52A2A", name='test2')
+    with pytest.raises(ValueError):
+        brain.remove_foci(['test4'])
+    brain.remove_foci('test1')
+    brain.remove_foci()
+    assert len(brain.foci_dict) == 0
     brain.close()
 
 

surfer/viz.py

@@ -1454,6 +1454,34 @@ def remove_data(self, hemi=None):
         if all(len(brain.data) == 0 for brain in self.brains):
             self.n_times = self._times = None
 
+    def remove_foci(self, name=None):
+        """Remove foci added with ``Brain.add_foci()``.
+
+        Parameters
+        ----------
+        name : str | list of str | None
+            Names of the foci to remove (if None, remove all).
+
+        Notes
+        -----
+        Only foci added with a unique names can be removed.
+        """
+        if name is None:
+            keys = tuple(self.foci_dict)
+        else:
+            if isinstance(name, str):
+                keys = (name,)
+            else:
+                keys = name
+            if not all(key in self.foci_dict for key in keys):
+                missing = ', '.join(key for key in keys if key not in
+                                    self.foci_dict)
+                raise ValueError("foci=%r: no foci named %s" % (name, missing))
+
+        for key in keys:
+            for points in self.foci_dict.pop(key):
+                points.remove()
+
     def remove_labels(self, labels=None, hemi=None):
         """Remove one or more previously added labels from the image.