Updated documentation

README.md

@@ -0,0 +1,111 @@
+<p align="center">
+## pybehave
+
+![](docs/img/full_gui.jpg)
+</p>
+
+Pybehave is an open source software interface and framework for controlling behavioral experiments in neuroscience and psychology
+built around a hardware-agnostic and highly object-oriented design philosophy.
+
+Pybehave separates code for task design from specific hardware implementations to streamline development, accessibility, and
+data sharing. This approach, combined with a task-specific Graphical User Interfaces (GUIs), expedites and simplifies the creation and visualization of complex behavioral tasks.
+User created [task](tasks.md) definition files can interact with hardware-specific [source](sources.md) files both written in Python. Any and all local
+configuration can be handled outside of Python using [Address Files](protocols_addressfiles.md#addressfiles) and [Protocols](protocols_addressfiles.md#protocols).
+
+All pybehave tasks are coordinated via a [Workstation](workstation.md) GUI.
+
+Pybehave software and documentation are available on [GitHub](https://github.com/tne-lab/py-behav-box-v2).
+
+## Getting started
+
+### Install with pip
+
+We recommend installing pybehave in a virtual environment. Pybehave has been tested on Python 3.9, 3.10, and 3.11.
+
+Install pybehave's default [PYPI distribution](https://pypi.org/project/pybehave/) with
+
+    pip install pybehave
+
+This distribution does not include any of the dependencies for hardware specific functionality. To install the dependencies
+for all supported hardware use the following
+
+    pip install pybehave[full]
+
+Alternatively, a subset of the dependencies can be downloaded, for example
+
+    pip install pybehave[oe,video]
+
+A full list of the optional hardware-specific extras is below
+
+    oe              # Dependencies for the OpenEphys framework
+    whisker         # Dependencies for communication with WhiskerServer
+    video           # Dependencies for control of connected video systems
+    serial          # Dependencies for communication over serial
+    ni              # Dependencies for communication with NationalInstruments DAQs
+    hikvision       # Dependencies for communication with HikVision DVRs
+    bo              # Dependencies for a Bayesian Optimization framework
+
+### Run from source
+
+Alternatively, you can clone the repository and run from source.
+
+    git clone https://github.com/tnelab/py-behav-box-v2.git
+    cd py-behav-box-v2
+    pip install .
+
+Hardware-specific extras can be installed by adding square brackets after the '.' similarly to the above.
+
+### Starting pybehave
+
+From the standard install, pybehave can be started by running the `pybehave` command from the virtual environment. Alternatively,
+if you have installed pybehave into a conda environment, we've provided an example batch script for starting pybehave in the root 
+directory (py-behav.bat). This batch script can be copied to the Desktop and the first line should be modified to use the name
+of the environment where pybehave was installed. This batch file will also redirect all console outputs to a log file in the
+`py-behav/logging` directory.
+
+### Local folder structure
+
+Pybehave uses a folder saved on the Desktop to handle all task files and local configuration:
+
+    -py-behav
+        pybehave.ini            # Contains all settings for the GUI
+        -Local
+            -Tasks              # Task python files
+            -GUIs               # Task GUI files
+            -Sources            # User-created sources
+        -Configurations         # Structured CSVs for quickly loading tasks
+        -TaskName1              # All files associated with a Task called TaskName1
+            -AddressFiles       # AddressFiles for this task
+            -Protocols          # Protocols for this task
+            -Data               # Any data associated with runs of the task
+        -TaskName2          
+
+We've included an example set of [task files](https://github.com/tne-lab/all-tasks) used by Translational Neuroengineering Lab. 
+If you plan to edit or add tasks, you should make a new repository with the same structure (Tasks and GUIs folders) and 
+include any existing tasks you might need. The contents of this repository should be saved in the Local directory.
+
+### Updating pybehave
+
+Pybehave is explicitly designed in a manner where files for local configuration are separate from the root directory. This
+ensures that users can easily update to the newest version of the platform without compromising their experimental files. 
+To update, simply pull the latest version from the upstream base pybehave code repository and the repository referenced by
+the *Local* folder.
+
+### Running a task
+
+After opening pybehave, you will see a GUI window like that shown above.
+
+Select *File->Add Task* from the menu bar. Choose your [task](tasks.md) and a chamber number from the dropdowns or load a [Configuration](workstation.md#configurations) file.
+
+Enter a subject ID in the *Subject* text box and choose an [Address File](protocols_addressfiles.md#addressfiles) or [Protocol](protocols_addressfiles.md#protocols) if necessary to set up the local configuration of the task.
+
+Any [event](events.md) information such as data saving or external communication or pre-task prompts can be configured by right-clicking the chamber widget
+and selecting *Edit Configuration*. All data will be saved to the Desktop in the *py-behav/TASK_NAME/Data/SUBJECT/DATE* folder.
+
+Press the green play button to start the task.
+
+The task can be paused or ended prematurely with the orange pause button or red stop button respectively.
+
+## Troubleshooting
+
+If you encounter problems, take a look at the [issues](https://github.com/tne-lab/py-behav-box-v2/issues) section of the GitHub and leave a new one if your problem hasn't been previously addressed.

docs/events.md

@@ -518,6 +518,8 @@ the task began.
 EventLogger that transmits pybehave events as strings to OpenEphys to aid in synchronization.
 This logger should be paired with a NetworkEvents plugin in OpenEphys.
 
+*Required Extras:* `oe`
+
 *Attributes:*
 
 `address` the IP address of the device running OpenEphys. Use localhost if both pybehave and OpenEphys are running on the

docs/index.md

@@ -22,7 +22,7 @@ Pybehave software and documentation are available on [GitHub](https://github.com
 
 We recommend installing pybehave in a virtual environment. Pybehave has been tested on Python 3.9, 3.10, and 3.11.
 
-Install pybehave's default [PYPI distribution]() with
+Install pybehave's default [PYPI distribution](https://pypi.org/project/pybehave/) with
 
     pip install pybehave
 
@@ -35,7 +35,7 @@ Alternatively, a subset of the dependencies can be downloaded, for example
 
     pip install pybehave[oe,video]
 
-A full list of the optional hardware-specific options is below
+A full list of the optional hardware-specific extras is below
 
     oe              # Dependencies for the OpenEphys framework
     whisker         # Dependencies for communication with WhiskerServer
@@ -51,7 +51,17 @@ Alternatively, you can clone the repository and run from source.
 
     git clone https://github.com/tnelab/py-behav-box-v2.git
     cd py-behav-box-v2
-    pip install -r requirements.txt
+    pip install .
+
+Hardware-specific extras can be installed by adding square brackets after the '.' similarly to the above.
+
+### Starting pybehave
+
+From the standard install, pybehave can be started by running the `pybehave` command from the virtual environment. Alternatively,
+if you have installed pybehave into a conda environment, we've provided an example batch script for starting pybehave in the root 
+directory (py-behav.bat). This batch script can be copied to the Desktop and the first line should be modified to use the name
+of the environment where pybehave was installed. This batch file will also redirect all console outputs to a log file in the
+`py-behav/logging` directory.
 
 ### Local folder structure
 

docs/sources.md

@@ -124,9 +124,7 @@ Call to signal to other processes that the Source has lost connection to the har
 
 Communicates with digital input and output lines represented via a connection to Whisker. This Source is only compatible with Windows.
 
-*Unique Dependencies:*
-
-`win32gui` used to check if there is an actively running Whisker Server 
+*Required Extras:* `whisker`
 
 *Attributes:*
 
@@ -146,9 +144,7 @@ Communicates with digital input and output lines represented via a connection to
 
 Communicates with touchscreen objects represented via a connection to Whisker.
 
-*Unique Dependencies:*
-
-`pywin32` used to check if there is an actively running Whisker Server 
+*Required Extras:* `whisker`
 
 *Attributes:*
 
@@ -168,6 +164,8 @@ Communicates with touchscreen objects represented via a connection to Whisker.
 Source for coordinating connections to the networking system in OpenEphys. Make sure all events to/from OpenEphys are received/sent
 in JSON mode.
 
+*Required Extras:* `oe`
+
 *Attributes:*
 
 `address` IP address for the computer running OpenEphys. Use "localhost" if pybehave and OpenEphys are on the same machine.
@@ -183,9 +181,7 @@ in JSON mode.
 
 Source for coordinating connections to the Open Source Controller for Animal Research (OSCAR). Has functionality for digital and analog inputs and outputs.
 
-*Unique Dependencies:*
-
-`pyserial` used to communicate with the serial ports
+*Required Extras:* `serial`
 
 *Attributes:*
 
@@ -197,9 +193,7 @@ Source for coordinating connections to the Open Source Controller for Animal Res
 
 Source for coordinating connections to serial devices.
 
-*Unique Dependencies:*
-
-`pyserial` used to communicate with the serial ports
+*Required Extras:* `serial`
 
 *Required Metadata:*
 
@@ -220,13 +214,7 @@ 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. 
 
-*Unique Dependencies:*
-
-`opencv-python` used to coordinate video acquisition, display, and serialization
-
-`imutils` used to process the video stream
-
-`qasync` used to visualize the video stream
+*Required Extras:* `opencv-python`
 
 *Attributes:*
 
@@ -261,9 +249,7 @@ Source for coordinating video recording with HikVision CCTV systems. Generally i
 Recordings will start when the Video component is started and downloaded in a separate thread when the video is stopped.
 By default, the source will draw a small black rectangle in the bottom left of the video to assist with synchronization.
 
-*Unique Dependencies:*
-
-`hikload` used to interface with the Hikvision ISAPI
+*Required Extras:* `hikvision`
 
 *Attributes:*
 
@@ -281,9 +267,7 @@ By default, the source will draw a small black rectangle in the bottom left of t
 Source for coordinating connections to National Instruments hardware. Has functionality for digital and analog outputs.
 Input functionality is currently not implemented.
 
-*Unique Dependencies:*
-
-`nidaqmx` used to interface with the NIDAQ API
+*Required Extras:* `ni`
 
 *Attributes:*
 
@@ -298,4 +282,6 @@ Input functionality is currently not implemented.
     class BayesOptSource()
 
 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.
+using Bayesian optimization with gaussian process regression. Typically used with the general purpose `Both` component class.
+
+*Required Extras:* `bo`

docs/workstation.md

@@ -154,4 +154,16 @@ which can be provided with a name/value pair by the GUI.
     class OEWidget(Widget):
         name: str
         address: str
-        port: str
+        port: str
+
+*Attributes:*
+
+`name: str` the identifier given to this Widget
+
+`address: str` the IP address for the computer running OpenEphys (localhost if on the same device)
+
+`port: str` the port for the connection to OpenEphys
+
+*Required Extras:* `oe`
+
+Widget providing control over the OpenEphys acquisition system

py-behav.bat

@@ -1,5 +1,4 @@
-call C:\ProgramData\Anaconda3\Scripts\activate.bat py-behav-box-v2
-cd C:\Users\SetShift\Documents\GitHub\py-behav-box-v2\source
+call conda activate py-behav-box-v2
 if not exist %USERPROFILE%\Desktop\py-behav\logging mkdir %USERPROFILE%\Desktop\py-behav\logging
-call python run.py > %USERPROFILE%\Desktop\py-behav\logging\%date:~10%%date:~4,2%%date:~7,2%-%time:~0,2%%time:~3,2%%time:~6,2%.log 2>&1
+call pybehave > %USERPROFILE%\Desktop\py-behav\logging\%date:~10%%date:~4,2%%date:~7,2%-%time:~0,2%%time:~3,2%%time:~6,2%.log 2>&1
 pause