Merge pull request #89 from tne-lab/dev

Merging Changes from JOSS Review

Author: theonlydvr

docs/events.md

@@ -435,6 +435,33 @@ Event associated with the request to close the hardware/software connection with
 
 `comp_id` the ID of the component
 
+### Subject Configuration Events
+
+### ConstantsUpdateEvent
+
+    class ConstantsUpdateEvent(TaskEvent):
+        constants: Dict
+
+Event associated with sending information from the [SubjectConfigWidget](workstation.md#configuration-with-subjectconfigwidget) to the Task. This event may send multiple updates
+at once which will be split into constant-specific ConstantUpdateEvents for constants that actually had their values changed.
+
+### ConstantUpdateEvent
+
+    class ConstantUpdateEvent(Loggable):
+        name: str
+        value: Any
+
+Event associated with changes to constants from the SubjectConfigWidget that occur while the Task is running. One of these
+events will be logged for each constant that had a change in value after receiving a ConstantsUpdateEvent.
+
+### ConstantRemoveEvent
+
+    class ConstantRemoveEvent(TaskEvent):
+        constant: str
+
+Event associated with removing a constant from the SubjectConfigWidget. Will reset the value of the constant to what is listed
+in the task's `get_constants` method. If this occurs while a task is running, a ConstantUpdateEvent will be logged.
+
 ### EventLoggers
 
 The classes detailed below are contained in the `Events` package and associated with event logging.

docs/img/addressfile_gui.png

@@ -25,6 +25,17 @@ by the task's `get_constants` method with a new value to replace the pre-existin
 
 Protocols can be loaded from any directory, but we recommend saving them at *Desktop/py-behav-v2/TASK_NAME/Protocols*.
 
+### Protocol Creation GUI
+
+Instead of manually creating Protocols, Protocols can also be created using a GUI tool by going to File->Protocols->New/Edit.
+From here, you can select which Task you want to create a Protocol for. In the creation GUI, constants can be added or removed
+from the Protocol with the corresponding buttons in the bottom-left of the interface. When a constant is added, the GUI
+will default to selecting one of the available entries and autopopulate it with the default value from the `get_constants`
+method. The chosen constant can be changed in the corresponding Constant dropdown. If the constant's default value is an expression,
+the expression will be evaluated and set as the default value.
+
+![img/protocol_gui.png](img/protocol_gui.png)
+
 ## AddressFiles
 
 AddressFiles are executed at runtime to associate *Components* with particular *Sources*. Tasks can have any number of AddressFiles
@@ -50,4 +61,20 @@ is the identifier that was given to the [Source](sources.md) this component shou
 is the hardware address the source should associate this component with. The first of the two optional arguments, `list_index` 
 indicates the component's list position if the ID is associated with a list of components. The second optional argument, `metadata`
 is a dictionary that can be used to override Component attributes (analogous to a Protocol for components). AddressFiles can be 
-loaded from any directory, but we recommend saving them at *Desktop/py-behav-v2/TASK_NAME/AddressFiles*.
+loaded from any directory, but we recommend saving them at *Desktop/py-behav-v2/TASK_NAME/AddressFiles*.
+
+### AddressFile Creation GUI
+
+Instead of manually creating AddressFiles, AddressFiles can also be created using a GUI tool by going to File->AddressFiless->New/Edit.
+From here, you can select which Task you want to create an AddressFile for. In the creation GUI, components can be added or removed
+from the AddressFile with the corresponding buttons in the bottom-left of the interface. When a component is added, the GUI
+will default to selecting one of the available entries and autopopulate it according to the `get_components`
+method. The chosen component can be changed in the corresponding Component dropdown. The type of the component can be changed
+in the Type dropdown and will automatically be restricted to valid options. The Source linked to the component can be changed 
+in the Source dropdown and will include possible entries for all Sources configured in the system. The component address can
+be changed in the Address field; valid addresses must be strings, integers, floats, or list of the aforementioned options.
+If the component is part of a list, the component index in the list can be selected from the Index dropdown. Lastly, any metadata
+required for this component by the linked Source or the Component class itself will automatically be indicated in the Metdata
+field. Default values for metadata are indicated in the corresponding Source or Component class.
+
+![addressfile_gui.png](img/addressfile_gui.png)

docs/img/protocol_gui.png

@@ -126,6 +126,8 @@ Communicates with digital input and output lines represented via a connection to
 
 *Required Extras:* `whisker`
 
+Run `pip install pybehave[whisker]` if the extra is missing.
+
 *Attributes:*
 
 `address` IP address for the computer running the Whisker Server. Use "localhost" if pybehave and Whisker are on the same machine.
@@ -146,6 +148,8 @@ Communicates with touchscreen objects represented via a connection to Whisker.
 
 *Required Extras:* `whisker`
 
+Run `pip install pybehave[whisker]` if the extra is missing.
+
 *Attributes:*
 
 `address` IP address for the computer running the Whisker Server. Use "localhost" if pybehave and Whisker are on the same machine.
@@ -166,6 +170,8 @@ in JSON mode.
 
 *Required Extras:* `oe`
 
+Run `pip install pybehave[oe]` if the extra is missing.
+
 *Attributes:*
 
 `address` IP address for the computer running OpenEphys. Use "localhost" if pybehave and OpenEphys are on the same machine.
@@ -183,6 +189,8 @@ Source for coordinating connections to the Open Source Controller for Animal Res
 
 *Required Extras:* `serial`
 
+Run `pip install pybehave[serial]` if the extra is missing.
+
 *Attributes:*
 
 `coms` list of serial port IDs corresponding to OSCAR interfaces.
@@ -195,6 +203,8 @@ Source for coordinating connections to serial devices.
 
 *Required Extras:* `serial`
 
+Run `pip install pybehave[serial]` if the extra is missing.
+
 *Required Metadata:*
 
 `baudrate: int` the baudrate for the Serial connection corresponding to a registered Component
@@ -214,7 +224,9 @@ Source for coordinating connections to serial devices.
 Source for coordinating video recording with Webcams. Generally intended for sole use with Video components. Currently supports
 standard USB webcams. 
 
-*Required Extras:* `opencv-python`
+*Required Extras:* `video`
+
+Run `pip install pybehave[video]` if the extra is missing.
 
 *Attributes:*
 
@@ -251,6 +263,8 @@ By default, the source will draw a small black rectangle in the bottom left of t
 
 *Required Extras:* `hikvision`
 
+Run `pip install pybehave[hikvision]` if the extra is missing.
+
 *Attributes:*
 
 `ip` the IP of the DVR
@@ -269,6 +283,8 @@ Input functionality is currently not implemented.
 
 *Required Extras:* `ni`
 
+Run `pip install pybehave[ni]` if the extra is missing.
+
 *Attributes:*
 
 `dev` the device ID of the DAQ
@@ -284,4 +300,6 @@ Input functionality is currently not implemented.
 Source for coordinating selection of arbitrary parameters (like stimulation or task variables) according to an outcome of interest 
 using Bayesian optimization with gaussian process regression. Typically used with the general purpose `Both` component class.
 
-*Required Extras:* `bo`
+*Required Extras:* `bo`
+
+Run `pip install pybehave[bo]` if the extra is missing.

docs/img/subject_config.png

@@ -64,8 +64,12 @@ task's `get_constants` method).
 
 ![img.png](../img/constant_added.png)
 
+Values for a particular subject can be saved to load every time this subject runs the task by pressing the down-arrow button.
 Subject specific configuration can also be made to differ per Protocol or AddressFile but this feature is less useful for
-task testing and more for streamlining experiments.
+task testing and more for streamlining experiments. Constants can also be updated while a task is running and will log 
+ConstantUpdateEvents which can be analyzed offline or handled in Task code. Generally, this real-time feature is more intended
+for development than as an actual part of the task workflow since constants are meant to have fixed values. Instead, elements
+can be added to the GUI to update task variables if user input is required while the task is running.
 
 ## Simulating sources
 

docs/protocols_addressfiles.md

@@ -62,16 +62,19 @@ default but can be associated with any number of additional Widgets. Widgets are
 to the associated Task or its EventLoggers or controlling external hardware/software manually from the pybehave GUI. 
 While similar functionality can be implemented in Task GUIs, Widgets will have identical behavior regardless of the Task they are associated with.
 
-#### EventWidget
+#### Accessing events with EventWidget
 
 EventWidget is an abstract subclass of Widget that provides access to the Task event stream. This functionality should only be necessary if
 the Widget is intended for visualizing/displaying Task information or requires feedback from the Task
 
-#### SubjectConfigWidget
+#### Configuration with SubjectConfigWidget
 
 SubjectConfigWidget is a special purpose Widget that is integrated into the pybehave core. This Widget allows for overriding the
 value of any Task constant for a particular subject. This is useful if constants need to be set on a per-subject basis. 
-Values can also be made specific to the address file or protocol the subject is running on.
+Values can also be made specific to the address file or protocol the subject is running on. Constants can also be updated while a task is running and will log 
+ConstantUpdateEvents which can be analyzed offline or handled in Task code.
+
+![subject_config.png](img/subject_config.png)
 
 ## Workstation Settings
 

docs/sources.md

@@ -86,3 +86,8 @@ def close(self) -> None:
         if self.task is not None:
             self.task.close_component(self.id)
 
+    @staticmethod
+    def metadata_defaults() -> Dict:
+        """Call to get the metadata names and default values required by this component."""
+        return {}
+

docs/tutorials/task_no_hardware.md

@@ -1,5 +1,6 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Dict
+
 if TYPE_CHECKING:
     from pybehave.Tasks.Task import Task
 
@@ -29,3 +30,7 @@ def update(self, value: dict) -> bool:
                 self.state = False
                 return True
         return False
+
+    @staticmethod
+    def metadata_defaults() -> Dict:
+        return {"rising": True, "falling": False}