open-ephys · cjsha · May 26, 2025 · May 26, 2025 · May 26, 2025 · May 27, 2025
diff --git a/source/_static/downloads/uclaminiscopev4-miniscopedaq-gui.bonsai b/source/_static/downloads/uclaminiscopev4-miniscopedaq-gui.bonsai
diff --git a/source/_static/images/uclaminiscopev4-miniscopedaq-gui.svg b/source/_static/images/uclaminiscopev4-miniscopedaq-gui.svg
diff --git a/source/_static/images/uclaminiscopev4-miniscopedaq-gui_commutate-disable.svg b/source/_static/images/uclaminiscopev4-miniscopedaq-gui_commutate-disable.svg
diff --git a/source/overview/miniscopes.rst b/source/overview/miniscopes.rst
diff --git a/source/ucla-miniscope-v4/index.rst b/source/ucla-miniscope-v4/index.rst
@@ -23,10 +23,6 @@ To learn how the UCLA Miniscope v4 works, refer to the :doc:`/ucla-miniscope-v4/
 UCLA Miniscope v4 Features & Properties
 ***************************************
 
-..  todo::  format this better
-
-To compare the UCLA Miniscope v4 to other miniscopes sold by Open Ephys, refer to the :ref:`overview/miniscopes:Comparison Chart`.
-
 Mechanical Properties:
 
 *   **Mass:** <3g

diff --git a/source/ucla-miniscope-v4/quick/software.rst b/source/ucla-miniscope-v4/quick/software.rst
@@ -65,7 +65,8 @@ If you have not already done so,
             :align: center
             :height: 400px
 
-    #.  Download and install the required Bonsai packages:
+    #.  Download and install the required Bonsai packages or update to the latest versions using
+        the Bonsai Package Manager:
 
         *   Bonsai.StarterPack
 

diff --git a/source/ucla-miniscope-v4/user/miniscope-daq/gui/description.rst b/source/ucla-miniscope-v4/user/miniscope-daq/gui/description.rst
@@ -0,0 +1,55 @@
+####################
+Workflow Description
+####################
+
+..  note::  This description assumes the reader has a foundation in Bonsai that is built on the :doc:`Trigger Workflow Description <../save-data/description>`. Start there if you have not already.
+
+***************
+GUI Description
+***************
+
+..  image:: /_static/images/uclaminiscopev4-miniscopedaq-gui.svg
+    :alt:   exported svg of main workflow with bounding box over nodes responsible for automatic commutation
+    :align: center
+
+This example workflow is meant to be extensible. For that purpose, we have provided an overview of
+how it works broad overview of how it works.
+
+..  tip::
+
+    If you edit this workflow for your own experiment, one important feature of Bonsai to know about
+    is that all items passed from node to node are visible to the user using type visualizers. Either: 
+
+    #.  Double-click a node while the workflow is running to open the default visualizer.
+    #.  Right-click a node, click "Show Visualizer", and click a visualizer to show up when the 
+        workflow is running.
+
+    Not all types have descriptive visualizers, but they can still be helpful to know when data is
+    sent. Moreover, if a type doesn't have a descriptive visualizer, you might be able to select a
+    member from that type and visualize that member instead, i.e. what we do to visualize image or
+    quaternion data from a `UCLAMiniscopeV4Frame`. 
+
+There are several ``GroupWorkflow`` operators that have been named after the GUI elements that they
+contain or the function that they serve. Double-click one while the workflow is off to inspect it, or
+press ``F12`` while one is selected.
+
+-   The "SaveData" ``GroupWorkflow`` contains a pattern that allows the ``VideoWriter`` operator to
+    subscribe (a `Reactive <https://reactivex.io/documentation/observable.html>`__ way to say
+    "listening") to upstream operators which allows the user to change the filename while the
+    workflow is running. 
+
+-   The "DataSource" ``GroupWorkflow`` contains the ``UCLAMiniscopeV4`` source node.
+
+-   The rest of the ``GroupWorkflows`` are for controlling the state of GUI elements. Each one has a
+    ``VisualizerMapping`` to map each GUI element to a panel. 
+
+    -   If you want to add your own custom data-processing pipeline for visualization, inspect the
+        "Video" ``GroupWorkflow``. It contains three more ``GroupWorkflows`` that each represent a
+        way to look at the data. Create another radio button and branch (or override one that
+        already exists) to add your custom data-processing pipeline to the visualizer.
+
+This workflow also demonstrates the usage of ``PublishSubject``, ``MulticastSubject``, and
+``BehaviorSubject`` which can be combined with ``SubscribeSubject`` to connect nodes without drawing
+lines between them. Using `subjects <https://bonsai-rx.org/docs/articles/subjects.html>`_ is `good
+practice <https://bonsai-rx.org/docs/articles/workflow-guidelines.html>`_ when creating more
+extensive workflows. 
diff --git a/source/ucla-miniscope-v4/user/miniscope-daq/gui/hardware.rst b/source/ucla-miniscope-v4/user/miniscope-daq/gui/hardware.rst
@@ -0,0 +1,5 @@
+####################
+Hardware Connections
+####################
+
+Coming soon
diff --git a/source/ucla-miniscope-v4/user/miniscope-daq/gui/index.rst b/source/ucla-miniscope-v4/user/miniscope-daq/gui/index.rst
@@ -0,0 +1,31 @@
+###
+GUI
+###
+
+..  image:: /_static/images/uclaminiscopev4-miniscopedaq-commutate.svg
+    :alt:   image of workflow
+    :width: 50%
+    :align: center
+
+After following this tutorial, the user will be able to open an example GUI constructed in Bonsai for
+interfacing with the UCLA Miniscope v4, Miniscope DAQ and Open Ephys torque-free commutator with the following features:
+
+-   toggle between one of three online data-processing pipelines for viewing (raw, saturation, ΔF/F)
+-   control various properties related to the Miniscope hardware, saving data, and the ΔF/F signal-processing pipeline
+-   toggle recording manually or with a hardware input trigger
+-   view real-time pixel brightness histogram
+-   view real-time digital input data
+-   commutate the UCLA Miniscope V4 tether automatically with the Open Ephys torque-free commutator
+
+This example GUI is intended to provide easy-to-use access to the key features of the libraries that are available in Bonsai to work with this Miniscope system. We believe it will be useful as-is for most users. However, since the GUI is itself programmed in Bonsai, users can extend the layout or remove features to fit their experimental needs.
+
+..  note::
+    This is the first release of this Bonsai GUI for Miniscopes. If you have feedback, (i.e. feature requests, usability issues, bug fixes, etc.), please submit them as a `GitHub issue <https://github.com/open-ephys/miniscope-docs/issues/new>`__!
+
+..  toctree::
+    :hidden:
+
+    hardware
+    software
+    tutorial
+    description
diff --git a/source/ucla-miniscope-v4/user/miniscope-daq/gui/software.rst b/source/ucla-miniscope-v4/user/miniscope-daq/gui/software.rst
@@ -0,0 +1,75 @@
+#####################################
+Bonsai Installation and Configuration
+#####################################
+
+#.  If you have not already done so, 
+
+    #.  `Download and Install Bonsai <https://bonsai-rx.org/docs/articles/installation.html>`_
+
+    #.  `Install the necessary Bonsai packages: <https://bonsai-rx.org/docs/articles/packages.html>`_
+
+        #.  Open Bonsai
+
+        #.  Open the Bonsai package manager:
+
+            ..  grid::
+
+                ..  grid-item::
+                    :columns:   5
+
+                    From the Bonsai landing window, select *Manage Packages*
+
+                    ..  image:: /_static/images/bonsai-landing-page-package-manager-button.webp
+                        :alt:   screenshot of Bonsai landing window with *Manage Packages* text highlighted
+                        :align: center
+
+                ..  grid-item::
+                    :columns:       auto
+                    :child-align:   center
+
+                    or
+
+                ..  grid-item::
+                    :columns:   6
+
+                    From the Bonsai workflow editor, hover over the *Tools* tab in the top ribbon to reveal a drop-down menu, and left-click *Manage Packages...*.
+
+                    ..  image:: /_static/images/bonsai-workflow-editor-package-manager-button.webp
+                        :alt:   screenshot of Bonsai workflow editor with *Manage Packages...* text highlighted
+                        :align: center
+
+        #.  Select the *Browse* tab in the top ribbon:
+
+            ..  image:: /_static/images/bonsai-package-manager-browse-button.webp
+                :alt:   screenshot of Bonsai package manager with *Browse* tab highlighted
+                :align: center
+                :height: 400px
+
+        #.  Configure the *Package Source* field to *All* using the drop-down menu:
+
+            ..  image:: /_static/images/bonsai-package-manager-package-source-dropdown.webp
+                :alt:   screenshot of Bonsai package manager with the Package Source drop-down highlighted
+                :align: center
+                :height: 400px
+
+        #.  Download and install the required Bonsai packages or update to the latest versions using
+            the Bonsai Package Manager:
+
+            *   Bonsai.StarterPack
+
+            *   OpenEphys.Miniscope
+
+            *   OpenEphys.Commutator
+
+            *   Bonsai.GUI
+
+            For each one, search its name in the search bar, left-click its corresponding entry, and left-click the *Install* button. For example:
+
+            ..  image:: /_static/images/bonsai-starterpack.webp
+                :alt:   screenshot of Bonsai package manager with search bar highlighted
+                :align: center
+                :height: 400px
+
+            Click the *I Accept* button when prompted.
+
+
diff --git a/source/ucla-miniscope-v4/user/miniscope-daq/gui/tutorial.rst b/source/ucla-miniscope-v4/user/miniscope-daq/gui/tutorial.rst
@@ -0,0 +1,72 @@
+#################
+Workflow Tutorial
+#################
+
+#.  Download the following workflow (.bonsai file) and open it with Bonsai:
+
+    ..  raw:: html
+
+        {% with static_path = '../../../../_static', name = 'uclaminiscopev4-miniscopedaq-gui' %}
+            {% include 'workflow.html' %}
+        {% endwith %}
+
+#.  Double-click the ``DataSource`` node and set the ``UCLAMiniscopeV4`` operator's ``Index``
+    property to the value that corresponds to the index of your miniscope.
+
+    ..  grid::
+
+        ..  grid-item::
+
+            ..  include::  /includes/set-index.rst
+
+        ..  grid-item::
+            :columns:   3
+
+            ..  image:: /_static/images/uclaminiscopev4-properties.webp
+                :align: center
+                :alt:   screenshot of ucla miniscope v4 node properties for index
+
+#.  Set the COM port associated with your commutator in the workflow
+
+    *   Left-click the ``AutoCommutator`` node and set the ``PortName`` property under the
+        `Properties` pane to match the port that corresponds to your commutator. 
+
+    ..  note::  
+
+        If you are uncertain about which COM port corresponds to your commutator, follow these instructions:
+
+        #.  Open Window's *Device Manager*.
+
+        #.  Unplug the commutator, and plug it back in. Observe which COM port disappears and
+            appears in device manager when doing so - that is the COM port associated with your
+            commutator. If the commutator does not appear in device manager, follow `these
+            instructions <https://www.pjrc.com/teensy/troubleshoot.html>`_
+
+#.  If you do not have a commutator connected, select the following chain of nodes and disable them
+    by either pressing ``Ctrl+D`` or right-clicking the selected nodes and clicking the "Disable"
+    option in the context menu that pops up.
+
+    ..  figure:: /_static/images/uclaminiscopev4-miniscopedaq-gui_commutate-disable.svg
+        :align: center
+        :alt:   screenshot of nodes to be disabled if no commutator is connected
+
+        Disable this row that performs commutation if no commutator is connected.
+
+#.  If you want to change the FourCC, click the "SaveData" ``GroupWorkflow`` and edit it from the
+    properties panel.
+
+#.  Run the workflow. Double-click the ``Miniscope GUI`` node and expand the visualizer that pops
+    up.
+
+#.  Using the GUI, you can:
+
+    -   toggle between one of three online data-processing pipelines for viewing (raw, saturation, ΔF/F)
+    -   control various properties related to the Miniscope hardware, saving data,
+        and the ΔF/F signal-processing pipeline
+    -   toggle recording manually or with a hardware input trigger
+    -   view real-time pixel brightness histogram
+    -   view real-time digital input data
+    -   commutate the UCLA Miniscope V4 tether automatically with the Open Ephys torque-free commutator
+
+..  [1]
+    .. include::    /includes/start-workflow.rst
diff --git a/source/ucla-miniscope-v4/user/miniscope-daq/index.rst b/source/ucla-miniscope-v4/user/miniscope-daq/index.rst
@@ -15,11 +15,12 @@ The User Guide contains following tutorials:
 *   :doc:`Commutate the UCLA Miniscope's tether using the on-board IMU </ucla-miniscope-v4/user/miniscope-daq/commutate/index>`
 
 For an extensive overview of the Miniscope-DAQ, refer to :ref:`its section <overview/data-acq-hardware:Miniscope-DAQ>` of the :doc:`/overview/data-acq-hardware` page.
- 
+
 
 .. toctree::
     :hidden:
 
     save-data/index
     trigger/index
     commutate/index
+    gui/index