reorganize viewer api examples

kushalkolar · May 23, 2021 · fd48720 · fd48720
1 parent 70fa431
commit fd48720
Show file tree

Hide file tree

Showing 3 changed files with 109 additions and 93 deletions.
diff --git a/docs/source/api_reference/Viewer_data_types.rst b/docs/source/api_reference/Viewer_data_types.rst
@@ -51,3 +51,8 @@ Mesfile
     :special-members:
     :members:
     :private-members:
+
+Examples
+========
+
+.. include:: ./viewer_core_api_examples.rst
diff --git a/docs/source/api_reference/viewer_core_api_examples.rst b/docs/source/api_reference/viewer_core_api_examples.rst
@@ -0,0 +1,103 @@
+These examples can be run in the :ref:`Viewer Console <ViewerConsole>`.
+
+Working with meta data
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    # view meta data
+    >>> get_meta()
+
+    {'origin': 'AwesomeImager', 'version': '4107ff58a0c3d4d5d3c15c3d6a69f8798a20e3de', 'fps': 10.0, 'date': '20190426_152034', 'vmin': 323, 'vmax': 1529, 'orig_meta': {'source': 'AwesomeImager', 'version': '4107ff58a0c3d4d5d3c15c3d6a69f8798a20e3de', 'level_min': 323, 'stims': {}, 'time': '152034', 'date': '20190426', 'framerate': 10.0, 'level_max': 1529}}
+
+    # manually set meta data entries
+    >>> get_meta()['fps'] = 30.0
+
+
+Open image
+^^^^^^^^^^
+
+Use the :ref:`Viewer Core API <API_ViewerCore>` to open any arbitrary image
+
+This example loads an image stored using numpy.save(), but this is applicable to images stored in any format that can eventually be represented as a numpy array in python. For example, you could also load image files stored in HDF5 format and load the numpy array that represents your image sequence.
+
+.. code-block:: python
+    :linenos:
+
+    import numpy as np
+
+    # clear the viewer work environment
+    clear_workEnv()
+
+    a = np.load('/path_to_image.npy')
+
+    # check what the axes order is
+    a.shape
+
+    # (1000, 512, 512) # for example
+    # looks like this is in [t, x, y]
+    # this can be transposed so we get [x, y, t]
+    # ImgData takes either [x, y, t] or [x, y, t, z] axes order
+
+    # Define a meta data dict
+    meta = \
+        {
+            "origin":      "Tutorial example",
+            "fps":         10.0,
+            "date":        "20200629_171823",
+            "scanner_pos": [0, 1, 2, 3, 4, 5, 6]
+        }
+
+    # Create ImgData instance
+    imgdata = ImgData(a.T, meta)  # use a.T to get [x, y, t]
+
+    # Create a work environment instance
+    work_env = ViewerWorkEnv(imgdata)
+
+    # Set the current Viewer Work Environment from this new instance
+    vi.viewer.workEnv = work_env
+
+    # Update the viewer with the new work environment
+    # this MUST be run whenever you replace the viewer work environment (the previous line)
+    update_workEnv()
+
+
+Image data
+^^^^^^^^^^
+
+Image sequences are simply numpy arrays. For example extract the image sequence between frame 1000 and 2000.
+
+.. seealso:: `Numpy array indexing <https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html>`_
+
+.. code-block:: python
+    :linenos:
+
+    # Get the current image sequence
+    seq = get_image()
+
+    # Trim the image sequence
+    trim = seq[:, :, 1000:2000]
+
+    # Set the viewer work environment image sequence to the trim one
+    vi.viewer.workEnv.imgdata.seq = trim
+
+    # Update the GUI with the new work environment
+    update_workEnv()
+
+View analysis log
+^^^^^^^^^^^^^^^^^
+
+View the analysis log, such as batch manager processing history.
+
+.. code-block:: python
+
+    >>> get_workEnv().history_trace
+
+    [{'caiman_motion_correction': {'max_shifts_x': 32, 'max_shifts_y': 32, 'iters_rigid': 1, 'name_rigid': 'Does not matter', 'max_dev': 20, 'strides': 196, 'overlaps': 98, 'upsample': 4, 'name_elas': 'a1_t2', 'output_bit_depth': 'Do not convert', 'bord_px': 5}}, {'cnmfe': {'Input': 'Current Work Environment', 'frate': 10.0, 'gSig': 10, 'bord_px': 5, 'min_corr': 0.9600000000000001, 'min_pnr': 10, 'min_SNR': 1, 'r_values_min': 0.7, 'decay_time': 2, 'rf': 80, 'stride': 40, 'gnb': 8, 'nb_patch': 8, 'k': 8, 'name_corr_pnr': 'a8_t1', 'name_cnmfe': 'a1_t2', 'do_corr_pnr': False, 'do_cnmfe': True}}, {'cnmfe': {'Input': 'Current Work Environment', 'frate': 10.0, 'gSig': 10, 'bord_px': 5, 'min_corr': 0.9600000000000001, 'min_pnr': 14, 'min_SNR': 1, 'r_values_min': 0.7, 'decay_time': 4, 'rf': 80, 'stride': 40, 'gnb': 8, 'nb_patch': 8, 'k': 8, 'name_corr_pnr': '', 'name_cnmfe': 'a1_t2', 'do_corr_pnr': False, 'do_cnmfe': True}}]
+
+Running scripts
+----------------
+
+You can use the :ref:`Script Editor <module_ScriptEditor>` to run scripts in the Viewer console for automating tasks such as batch creation. It basically allows you to use the :ref:`viewer console <ViewerConsole>` more conveniently with a text editor. The execution environment of the viewer console and script editor are identical.
+
+Some example are provided for caiman modules and :ref:`stimulus mapping <module_StimulusMapping>`.
diff --git a/docs/source/user_guides/viewer/overview.rst b/docs/source/user_guides/viewer/overview.rst
@@ -236,96 +236,4 @@ Video Tutorial
 Examples
 --------
 
-View meta data
-^^^^^^^^^^^^^^
-
-.. code-block:: python
-
-    >>> get_meta()
-    
-    {'origin': 'AwesomeImager', 'version': '4107ff58a0c3d4d5d3c15c3d6a69f8798a20e3de', 'fps': 10.0, 'date': '20190426_152034', 'vmin': 323, 'vmax': 1529, 'orig_meta': {'source': 'AwesomeImager', 'version': '4107ff58a0c3d4d5d3c15c3d6a69f8798a20e3de', 'level_min': 323, 'stims': {}, 'time': '152034', 'date': '20190426', 'framerate': 10.0, 'level_max': 1529}}
-
-View history trace
-^^^^^^^^^^^^^^^^^^
-
-.. code-block:: python
-
-    >>> get_workEnv().history_trace
-    
-    [{'caiman_motion_correction': {'max_shifts_x': 32, 'max_shifts_y': 32, 'iters_rigid': 1, 'name_rigid': 'Does not matter', 'max_dev': 20, 'strides': 196, 'overlaps': 98, 'upsample': 4, 'name_elas': 'a1_t2', 'output_bit_depth': 'Do not convert', 'bord_px': 5}}, {'cnmfe': {'Input': 'Current Work Environment', 'frate': 10.0, 'gSig': 10, 'bord_px': 5, 'min_corr': 0.9600000000000001, 'min_pnr': 10, 'min_SNR': 1, 'r_values_min': 0.7, 'decay_time': 2, 'rf': 80, 'stride': 40, 'gnb': 8, 'nb_patch': 8, 'k': 8, 'name_corr_pnr': 'a8_t1', 'name_cnmfe': 'a1_t2', 'do_corr_pnr': False, 'do_cnmfe': True}}, {'cnmfe': {'Input': 'Current Work Environment', 'frate': 10.0, 'gSig': 10, 'bord_px': 5, 'min_corr': 0.9600000000000001, 'min_pnr': 14, 'min_SNR': 1, 'r_values_min': 0.7, 'decay_time': 4, 'rf': 80, 'stride': 40, 'gnb': 8, 'nb_patch': 8, 'k': 8, 'name_corr_pnr': '', 'name_cnmfe': 'a1_t2', 'do_corr_pnr': False, 'do_cnmfe': True}}]
-
-Open image
-^^^^^^^^^^
-
-Use the :ref:`Viewer Core API <API_ViewerCore>` to open any arbitrary image
-
-This example loads an image stored using numpy.save(), but this is applicable to images stored in any format that can eventually be represented as a numpy array in python. For example, you could also load image files stored in HDF5 format and load the numpy array that represents your image sequence.
-
-.. code-block:: python
-    :linenos:
-
-    import numpy as np
-    
-    # clear the viewer work environment
-    clear_workEnv()
-    
-    a = np.load('/path_to_image.npy')
-    
-    # check what the axes order is
-    a.shape
-    
-    # (1000, 512, 512) # for example
-    # looks like this is in [t, x, y]
-    # this can be transposed so we get [x, y, t]
-    # ImgData takes either [x, y, t] or [x, y, t, z] axes order
-    
-    # Define a meta data dict
-    meta = \
-        {
-            "origin":      "Tutorial example",
-            "fps":         10.0,
-            "date":        "20200629_171823",
-            "scanner_pos": [0, 1, 2, 3, 4, 5, 6]
-        }
-    
-    # Create ImgData instance
-    imgdata = ImgData(a.T, meta)  # use a.T to get [x, y, t]
-    
-    # Create a work environment instance
-    work_env = ViewerWorkEnv(imgdata)
-    
-    # Set the current Viewer Work Environment from this new instance
-    vi.viewer.workEnv = work_env
-    
-    # Update the viewer with the new work environment
-    # this MUST be run whenever you replace the viewer work environment (the previous line)
-    update_workEnv()
-    
-    
-Splice img seq
-^^^^^^^^^^^^^^
-
-Extract the image sequence between frame 1000 and 2000. Image sequences are simply numpy arrays.
-
-.. seealso:: `Numpy array indexing <https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html>`_
-
-.. code-block:: python
-    :linenos:
-    
-    # Get the current image sequence
-    seq = get_image()
-    
-    # Trim the image sequence
-    trim = seq[:, :, 1000:2000]
-    
-    # Set the viewer work environment image sequence to the trim one
-    vi.viewer.workEnv.imgdata.seq = trim
-    
-    # Update the GUI with the new work environment
-    update_workEnv()
-
-
-Running scripts
-----------------
-
-You can use the :ref:`Script Editor <module_ScriptEditor>` to run scripts in the Viewer console for automating tasks such as batch creation. It basically allows you to use the :ref:`viewer console <ViewerConsole>` more conveniently with a text editor.
+.. include:: ../../api_reference/viewer_core_api_examples.rst