Add blk param to load_dataset, quick_launch for using existing Neo Block

docs/api.rst

@@ -12,9 +12,12 @@ its API in your own code.
     script is by invoking :func:`neurotic.quick_launch()
     <neurotic.scripts.quick_launch>`. For example:
 
-    >>> import neurotic
     >>> metadata = {'data_file': 'data.axgx'}
-    >>> neurotic.quick_launch(metadata)
+    >>> neurotic.quick_launch(metadata=metadata)
+
+    or
+
+    >>> neurotic.quick_launch(blk=my_neo_block)
 
 The core of the API consists of two classes and one function:
 

neurotic/datasets/data.py

@@ -21,7 +21,7 @@
 logger = logging.getLogger(__name__)
 
 
-def load_dataset(metadata, lazy=False, signal_group_mode='split-all', filter_events_from_epochs=False):
+def load_dataset(metadata, blk=None, lazy=False, signal_group_mode='split-all', filter_events_from_epochs=False):
     """
     Load a dataset.
 
@@ -32,7 +32,8 @@ def load_dataset(metadata, lazy=False, signal_group_mode='split-all', filter_eve
     The ``data_file`` in ``metadata`` is read into a Neo :class:`Block
     <neo.core.Block>` using an automatically detected :mod:`neo.io` class
     if ``lazy=False`` or a :mod:`neo.rawio` class if ``lazy=True``. If
-    ``data_file`` is unspecified, an empty Neo Block is created instead.
+    ``data_file`` is unspecified, an empty Neo Block is created instead. If a
+    Neo Block is passed as ``blk``, ``data_file`` is ignored.
 
     Epochs and events loaded from ``annotations_file`` and
     ``epoch_encoder_file`` and spike trains loaded from ``tridesclous_file``
@@ -45,14 +46,19 @@ def load_dataset(metadata, lazy=False, signal_group_mode='split-all', filter_eve
     signal.
     """
 
-    if metadata.get('data_file', None) is not None:
-        # read in the electrophysiology data
-        blk = _read_data_file(metadata, lazy, signal_group_mode)
+    if blk is None:
+        if metadata.get('data_file', None) is not None:
+            # read in the electrophysiology data
+            blk = _read_data_file(metadata, lazy, signal_group_mode)
+        else:
+            # create an empty Block
+            blk = neo.Block()
+            seg = neo.Segment()
+            blk.segments.append(seg)
     else:
-        # create an empty Block
-        blk = neo.Block()
-        seg = neo.Segment()
-        blk.segments.append(seg)
+        # a Block was provided
+        if not isinstance(blk, neo.Block):
+            raise TypeError('blk must be a neo.Block')
 
     # update the real-world start time of the data if provided
     if metadata.get('rec_datetime', None) is not None:
@@ -107,8 +113,8 @@ def load_dataset(metadata, lazy=False, signal_group_mode='split-all', filter_eve
         blk.segments[0].epochs += _run_burst_detectors(metadata, blk)
 
     # alphabetize epoch and event channels by name
-    blk.segments[0].epochs.sort(key=lambda ep: ep.name)
-    blk.segments[0].events.sort(key=lambda ev: ev.name)
+    blk.segments[0].epochs.sort(key=lambda ep: ep.name or '')
+    blk.segments[0].events.sort(key=lambda ev: ev.name or '')
 
     # compute rectified area under the curve (RAUC) for each signal if not
     # using lazy loading of signals

neurotic/scripts.py

@@ -138,28 +138,31 @@ def main():
         logger.info('Ready')
         app.exec_()
 
-def quick_launch(metadata, lazy=True):
+def quick_launch(metadata={}, blk=None, lazy=True):
     """
     Load data, configure the GUI, and launch the app with one convenient
     function.
 
     This function allows **neurotic** to be used easily in interactive sessions
-    and scripts. For example:
+    and scripts. For example, dictionaries can be passed as metadata:
 
-    >>> import neurotic
     >>> metadata = {'data_file': 'data.axgx'}
-    >>> neurotic.quick_launch(metadata)
+    >>> neurotic.quick_launch(metadata=metadata)
+
+    An existing Neo :class:`Block <neo.core.Block>` can be passed directly:
+
+    >>> neurotic.quick_launch(blk=my_neo_block)
 
     This function is equivalent to the following:
 
-    >>> blk = load_dataset(metadata, lazy=lazy)
+    >>> blk = load_dataset(metadata, blk, lazy=lazy)
     >>> ephyviewer_config = EphyviewerConfigurator(metadata, blk, lazy=lazy)
     >>> ephyviewer_config.show_all()
     >>> ephyviewer_config.launch_ephyviewer()
     """
 
     # make sure this matches the docstring after making changes
-    blk = load_dataset(metadata, lazy=lazy)
+    blk = load_dataset(metadata, blk, lazy=lazy)
     ephyviewer_config = EphyviewerConfigurator(metadata, blk, lazy=lazy)
     ephyviewer_config.show_all()
     ephyviewer_config.launch_ephyviewer()