diff --git a/docs/screenshots/screenshot.png b/docs/screenshots/screenshot.png new file mode 100644 index 00000000..7fc905d4 Binary files /dev/null and b/docs/screenshots/screenshot.png differ diff --git a/docs/source/calibration.rst b/docs/source/calibration.rst index bdcd6595..524b98a5 100644 --- 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. \ No newline at end of file diff --git a/docs/source/data_saving.rst b/docs/source/data_saving.rst index 07d064ad..c1dc4b3d 100644 --- 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 ` +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 ` Configuring Stytra for updating external database: -------------------------------------------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 8892cef7..48103b2c 100644 --- 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 index d9a54b9a..4d24ee34 100644 --- 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 index a3223549..800378b2 100644 --- 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 \ No newline at end of file +.. 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. \ No newline at end of file diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 00000000..75a769f9 --- /dev/null +++ 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 index 7f36a4d4..c20f8769 100644 --- 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 ` 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 ` whereas the terminal +nodes are :class:`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 ` and `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 ` 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 index 9392d34a..05ec5753 100644 --- 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 index 66b1d39c..b326175a 100644 --- 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 index a1cf8ef9..070253cc 100644 --- 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 index 26627e7d..cc657147 100644 --- 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 index b9e9d486..407f976b 100644 --- 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 new file mode 100644 index 00000000..dec72217 --- /dev/null +++ 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: diff --git a/docs/source/stytra.tests.rst b/docs/source/stytra.tests.rst new file mode 100644 index 00000000..ce06f989 --- /dev/null +++ b/docs/source/stytra.tests.rst @@ -0,0 +1,78 @@ +stytra.tests package +==================== + +Submodules +---------- + +stytra.tests.record\_stimuli module +----------------------------------- + +.. automodule:: stytra.tests.record_stimuli + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_base\_exp\_class module +------------------------------------------ + +.. automodule:: stytra.tests.test_base_exp_class + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_fish\_tracking module +---------------------------------------- + +.. automodule:: stytra.tests.test_fish_tracking + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_kalman module +-------------------------------- + +.. automodule:: stytra.tests.test_kalman + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_namedtuplequeue module +----------------------------------------- + +.. automodule:: stytra.tests.test_namedtuplequeue + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_online\_bout\_detection module +------------------------------------------------- + +.. automodule:: stytra.tests.test_online_bout_detection + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_pipeline module +---------------------------------- + +.. automodule:: stytra.tests.test_pipeline + :members: + :undoc-members: + :show-inheritance: + +stytra.tests.test\_triggering module +------------------------------------ + +.. automodule:: stytra.tests.test_triggering + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: stytra.tests + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/stytra.tracking.rst b/docs/source/stytra.tracking.rst index 92c96aeb..47b31fbc 100644 --- a/docs/source/stytra.tracking.rst +++ b/docs/source/stytra.tracking.rst @@ -20,6 +20,22 @@ stytra.tracking.fish module :undoc-members: :show-inheritance: +stytra.tracking.online\_bouts module +------------------------------------ + +.. automodule:: stytra.tracking.online_bouts + :members: + :undoc-members: + :show-inheritance: + +stytra.tracking.pipelines module +-------------------------------- + +.. automodule:: stytra.tracking.pipelines + :members: + :undoc-members: + :show-inheritance: + stytra.tracking.preprocessing module ------------------------------------ @@ -44,6 +60,14 @@ stytra.tracking.tail module :undoc-members: :show-inheritance: +stytra.tracking.tracking\_process module +---------------------------------------- + +.. automodule:: stytra.tracking.tracking_process + :members: + :undoc-members: + :show-inheritance: + Module contents --------------- diff --git a/setup.py b/setup.py index 7a2fc9d3..e6a112c8 100644 --- a/setup.py +++ b/setup.py @@ -4,7 +4,7 @@ setup( name="stytra", - version="0.8.2", + version="0.8.3", author="Vilim Stih, Luigi Petrucco @portugueslab", author_email="vilim@neuro.mpg.de", license="GPLv3+", @@ -32,8 +32,8 @@ "Intended Audience :: Science/Research", # Pick your license as you wish (should match "license" above) "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)", - "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", + "Programming Language :: Python :: 3.7", ], keywords="tracking behavior experiments", description="A modular package to control stimulation and track behavior in zebrafish experiments.",