Updates to documentation and versions.

portugueslab · Jan 24, 2019 · 59d4902 · 59d4902
1 parent a2bdd9b
commit 59d4902
Show file tree

Hide file tree

Showing 17 changed files with 298 additions and 18 deletions.
diff --git a/docs/screenshots/screenshot.png b/docs/screenshots/screenshot.png
diff --git a/docs/source/calibration.rst b/docs/source/calibration.rst
@@ -33,11 +33,12 @@ is used (it is enabled automatically for freely-swimming experiments).
    :alt: freely-swimming tracking screenshot
    :align: center
 
-After Styra starts, turn off the IR illumination and remove the IR filter
+After Stytra starts, turn off the IR illumination and remove the IR filter
 in front of the camera. Then, click the display calibration pattern button (:red:`a`) and
 move the display window on the projector so that the 3 dots are clearly visible.
-Sometimes the camera exposure has to be adjusted as well (:red:`b`).
+Sometimes the camera exposure has to be adjusted as well (:red:`b`) so that all 3 dots are visible.
+Due to screen or projector framerates, usually setting the camera framerate to 30 and the exposure to 10ms works well.
 
-Then, click calibrate (:red:c`) and verify that the location of the camera image
+Then, click calibrate (:red:`c`) and verify that the location of the camera image
 in the projected image makes sense. If not, try adjusting camera settings and
 calibrating again.
diff --git a/docs/source/data_saving.rst b/docs/source/data_saving.rst
@@ -1,9 +1,13 @@
 Data and metadata saving
 ========================
 
-Data saving class in Stytra
----------------------------
+Data saving classes in Stytra
+-----------------------------
 
+All streaming data (tracking, stimulus state) is collected by subclasses of the :class:`Accumulator <stytra.collectors.accumulators.Accumulator>`
+Accumulators collect named tuples of data and timing of data points. If the data format changes, the accumulator resets.
+
+All other data (animal metadata, configuration information, GUI state etc. is collected inside the Experiment class via tha :class:`DataCollector <stytra.collectors.data_collector.DataCollector>`
 
 Configuring Stytra for updating external database:
 --------------------------------------------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -58,7 +58,7 @@ Modules
 
     :py:mod:`stytra.calibration`
         Classes to register the camera view to the projector display and
-        set physical dimentions
+        set physical dimensions
 
     :py:mod:`stytra.tracking`
         Fish, eye and tail tracking functions together with appropriate interfaces

diff --git a/docs/source/install_guide.rst b/docs/source/install_guide.rst
@@ -34,6 +34,7 @@ This should be everything you need to make ready before installing stytra.
     installed and updated before installing Stytra!
 
 The simplest way to install Stytra is with pip::
+
     pip install stytra
 
 You can the installation by running one of the examples in stytra

diff --git a/docs/source/interface.rst b/docs/source/interface.rst
@@ -1,4 +1,41 @@
 Stytra user interface
 =====================
 
-The toolbar on top controls running of the protocols
+.. image:: ../screenshots/screenshot.png
+   :scale: 50%
+   :alt: user interface screenshot
+   :align: center
+
+The toolbar on top controls running of the protocols: starting and stopping,
+progress display, opening a dialog for protocol settings, changing the metadata and
+save destination.
+
+The rest of the interface is reconfigured depending on the experiment type.
+Each panel can be moved separately and closed.
+To reopen a closed panel, you can right-click on the title bar of any panel and
+a list of all available panels will appear.
+
+The camera panel buttons are for:
+
+- pausing and starting the camera feed
+- activating the replay (for a region selected when the camera is paused). Refer to :ref:`replaying` section for details.
+- adjusting camera settings (framerate, exposure and gain)
+- capturing the current image of the camera (without the tracking results superimposed
+- turning on and off auto-scaling of the image brightness range.
+
+- selection box to display the image at a particular stage in the tracking pipeline
+- button for editing the tracking settings
+
+The framerate display widget shows current framerates of the stimulus display,
+camera and tracking. If minimum framerates for display or tracking are configuresd,
+the indicators turn red if the framerate drops. These are configured in the stytra_config dict
+for a protocol or setup_config.json file in the following sections::
+
+    stytra_config = dict(
+            display=dict(min_framerate=50),
+            camera=dict(min_framerate=100),
+        )
+
+The monitoring widget shows changing variables relating to the stimulus, tracking or estimation of the animal state for closed-loop stimulation use
+
+The status bar shows diagnostic messages from the camera or tracking.
diff --git a/docs/source/modules.rst b/docs/source/modules.rst
@@ -0,0 +1,7 @@
+stytra
+======
+
+.. toctree::
+   :maxdepth: 4
+
+   stytra
diff --git a/docs/source/pipelines.rst b/docs/source/pipelines.rst
@@ -1,11 +1,12 @@
 Image processing pipelines
 ==========================
 
-Image processing and tracking pipelines are defined by subclassing the `Pipeline` class.
+Image processing and tracking pipelines are defined by subclassing the :class:`Pipeline <stytra.tracking.pipelines.Pipeline>` class.
 The pipelines are defined as trees of nodes, starting from the camera image
 with each node parametrized using lightparam.
-The image processing nodes are subclasses of `ImageToImageNode` whereas the terminal
-nodes are `ImageToDataNode`
+The image processing nodes are subclasses of :class:`ImageToImageNode <stytra.tracking.pipelines.ImageToImageNode>` whereas the terminal
+nodes are :class:`ImageToDataNode <stytra.tracking.pipelines.ImageToDataNode>`
+
 
 Attributes of pipelines are:
 
@@ -15,25 +16,25 @@ Attributes of pipelines are:
 
 the nodes can be set as attributes of the class,
 with names that are arbitrary except for how they are used
-by the display and plotting classes (see the ... for exampls)
+by the display and plotting classes (see the :py:mod:`stytra.experiments.fish_pipelines` for examples)
 
 Processing nodes
 ----------------
 
-There are two types of nodes: `ImageToImageNode`  and `ImageToDataNode`
+There are two types of nodes: :class:`ImageToImageNode <stytra.tracking.pipelines.ImageToImageNode>`  and  `ImageToDataNode <stytra.tracking.pipelines.ImageToDataNode>`
 
 Nodes must have:
-A name
+- A name
 
-A _process function which contains optional parameters
+- A _process function which contains optional parameters
 as keyword arguments, annotated with Params for everything
 that can be changed from the user interface. The _process
-function **has to** output a NodeOutput named tuple
+function **has to** output a :class:`NodeOutput <stytra.tracking.pipelines.NodeOutput>` named tuple
 (from stytra.tracking.pipeline) which contains a list of
 diagnostic messages (can be empty), and either an
 image if the node is a ImageToImageNode
 or a NamedTuple if the node is a ImageToDataNode
 
-Optionally, if the processing function is stateful,
+Optionally, if the processing function is stateful (depends on previous inputs),
 you can define a reset function which resets the state.
 
diff --git a/docs/source/stytra.collectors.rst b/docs/source/stytra.collectors.rst
@@ -20,6 +20,14 @@ stytra.collectors.data\_collector module
     :undoc-members:
     :show-inheritance:
 
+stytra.collectors.namedtuplequeue module
+----------------------------------------
+
+.. automodule:: stytra.collectors.namedtuplequeue
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 
 Module contents
 ---------------

diff --git a/docs/source/stytra.examples.rst b/docs/source/stytra.examples.rst
@@ -12,6 +12,30 @@ stytra.examples.closed\_loop\_exp module
     :undoc-members:
     :show-inheritance:
 
+stytra.examples.combined\_conditional\_exp module
+-------------------------------------------------
+
+.. automodule:: stytra.examples.combined_conditional_exp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+stytra.examples.combined\_exp module
+------------------------------------
+
+.. automodule:: stytra.examples.combined_exp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+stytra.examples.custom\_exp module
+----------------------------------
+
+.. automodule:: stytra.examples.custom_exp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.examples.custom\_trigger\_exp module
 -------------------------------------------
 
@@ -36,6 +60,14 @@ stytra.examples.display\_camera\_exp module
     :undoc-members:
     :show-inheritance:
 
+stytra.examples.display\_opencv\_cam module
+-------------------------------------------
+
+.. automodule:: stytra.examples.display_opencv_cam
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.examples.eye\_tracking\_exp module
 -----------------------------------------
 
@@ -84,6 +116,14 @@ stytra.examples.most\_basic\_exp module
     :undoc-members:
     :show-inheritance:
 
+stytra.examples.no\_stytra\_exp module
+--------------------------------------
+
+.. automodule:: stytra.examples.no_stytra_exp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.examples.phototaxis module
 ---------------------------------
 
@@ -116,6 +156,14 @@ stytra.examples.self\_calib\_cl\_exp module
     :undoc-members:
     :show-inheritance:
 
+stytra.examples.stimulus\_trigger\_exp module
+---------------------------------------------
+
+.. automodule:: stytra.examples.stimulus_trigger_exp
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.examples.tail\_tracking\_exp module
 ------------------------------------------
 

diff --git a/docs/source/stytra.experiments.rst b/docs/source/stytra.experiments.rst
@@ -4,6 +4,14 @@ stytra.experiments package
 Submodules
 ----------
 
+stytra.experiments.fish\_pipelines module
+-----------------------------------------
+
+.. automodule:: stytra.experiments.fish_pipelines
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.experiments.tracking\_experiments module
 -----------------------------------------------
 

diff --git a/docs/source/stytra.gui.rst b/docs/source/stytra.gui.rst
@@ -28,6 +28,14 @@ stytra.gui.container\_windows module
     :undoc-members:
     :show-inheritance:
 
+stytra.gui.fishplots module
+---------------------------
+
+.. automodule:: stytra.gui.fishplots
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.gui.framerate\_viewer module
 -----------------------------------
 
@@ -44,6 +52,14 @@ stytra.gui.monitor\_control module
     :undoc-members:
     :show-inheritance:
 
+stytra.gui.multiscope module
+----------------------------
+
+.. automodule:: stytra.gui.multiscope
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.gui.protocol\_control module
 -----------------------------------
 

diff --git a/docs/source/stytra.hardware.video.cameras.rst b/docs/source/stytra.hardware.video.cameras.rst
@@ -28,6 +28,14 @@ stytra.hardware.video.cameras.mikrotron module
     :undoc-members:
     :show-inheritance:
 
+stytra.hardware.video.cameras.opencv module
+-------------------------------------------
+
+.. automodule:: stytra.hardware.video.cameras.opencv
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 stytra.hardware.video.cameras.spinnaker module
 ----------------------------------------------
 

diff --git a/docs/source/stytra.rst b/docs/source/stytra.rst
@@ -0,0 +1,39 @@
+stytra package
+==============
+
+Subpackages
+-----------
+
+.. toctree::
+
+    stytra.calibration
+    stytra.collectors
+    stytra.examples
+    stytra.experiments
+    stytra.gui
+    stytra.hardware
+    stytra.metadata
+    stytra.stimulation
+    stytra.tests
+    stytra.tracking
+    stytra.triggering
+
+Submodules
+----------
+
+stytra.utilities module
+-----------------------
+
+.. automodule:: stytra.utilities
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: stytra
+    :members:
+    :undoc-members:
+    :show-inheritance: