Update READMEs

README.md

@@ -20,8 +20,12 @@ All scripts and classes are available in the open-ephys directory. Make sure the
 
 See the [control module README file](open_ephys/control/README.md) for how to setup zmq with Matlab.
 
+Using the OpenEphysHTTPServer class is recommended for remote control of the GUI in v0.6+.
+
 ## Usage
 
+Example scripts are included in the `examples` directory. The following sections provide a brief overview of the functionality of each module.
+
 ### analysis
 
 ```matlab
@@ -35,28 +39,35 @@ If the directory contains data from one more Record Nodes (GUI version 0.5+), th
 If your directory just contains data (any GUI version), individual recordings can be accessed via `session.recordings`. The format of the recordings will be detected automatically as either 
 [Binary](https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/Binary-format.html), 
 [Open Ephys](https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/Binary-format.html), 
-[NWB 1.0](https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/NWB-format.html), or 
-[KWIK](https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/KWIK-format.html).
+[NWB 2.0](https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/NWB-format.html).
+
+([KWIK](https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/KWIK-format.html) is no longer supported)
 
 Each `recording` object has the following fields:
 
 * `continuous` : continuous data for each subprocessor in the recording
 * `spikes` : spikes for each electrode group
 * `events` : Pandas `DataFrame` Matlab analog of event times and metadata
+* `messages` : text messages sent to the GUI during recording
 
 More details about `continuous`, `spikes`, and `events` objects can be found in the [analysis module README file](open_ephys/analysis/README.md).
 
 ### control
 
 ```matlab
-url = '10.128.50.10' % IP address of the computer running Open Ephys 
-port = 2000 
+host = '127.0.0.1' % IP address of the computer running Open Ephys
+port = 37497 % EPHYS on a phone keypad 
 
-gui = NetworkControl(url, port)
+gui = OpenEphysHTTPServer(host, port)
 
-gui.startAcquisition %starts acquisition
+gui.acquire() % start acquisition
+gui.record() % start recording
+gui.idle() % stop recording and/or acquisition
+gui.quit() % quit the GUI
 ```
 
+See all API endpoints in the [control module README file](open_ephys/control/README.md).
+
 ### streaming
 
 (coming soon)

open_ephys/analysis/README.md

@@ -29,8 +29,7 @@ If data from multiple Record Nodes is stored in the same directory, you can use
 
 (1) Record Node 118 : Binary Format 
 (2) Record Node 119 : OpenEphys Format 
-(3) Record Node 120 : KWIK Format 
-(4) Record Node 121 : NWB Format
+(3) Record Node 120 : NWB2 Format
 ```
 
 Within each Record Node, recordings are grouped by "experiments" and "recordings." A new "experiment" begins whenever data acquisition is stopped and re-started, as this re-sets the incoming hardware timestamps to zero. Within a given experiment, all of the timestamps are relative to a common start time. Starting and stopped recording (but not acquisition) in the GUI will initiate a new "recording." Each recording will have contiguous timestamps that increment by 1 for each sample.
@@ -39,32 +38,46 @@ The `analysis` module does not have a separate hierarchical level for experiment
 
 ## Loading continuous data
 
-Continuous data for each recording is accessed via the `.continuous` property of each `Recording` object. This returns a list of continuous data, grouped by processor/sub-processor. For example, if you have two data streams merged into a single Record Node, each data stream will be associated with a different processor ID. If you're recording Neuropixels data, each probe's data stream will be stored in a separate sub-processor, which must be loaded individually.
+Continuous data for each recording is accessed via the `.continuous` property of each `Recording` object. `recording.continuous.keys()` returns a list of continuous data streams, grouped by processor/stream name. For example, if you have two data streams merged into a single Record Node, each data stream will be associated with a different processor ID. If you're recording Neuropixels data, each probe's data stream will be stored in a separate stream, which must be loaded individually.
 
 Each `continuous` object has three properties:
 
-- `samples` - an `array` that holds the actual continuous data with dimensions of samples x channels. For Binary, NWB, and Kwik format, this will be a memory-mapped array (i.e., the data will only be loaded into memory when specific samples are accessed)
-- `timestamps` - an `array` that holds the sample indices. This will have the same size as the first dimension of the `samples` array
+- `samples` - an `array` that holds the actual continuous data with dimensions of samples x channels. This will be a memory-mapped array (i.e., the data will only be loaded into memory when specific samples are accessed)
+- `sampleNumbers` - an `array` that holds the sample indices. This will have the same size as the first dimension of the `samples` array
+- `timestamps` - an `array` that holds synchronized timestamps (if available). This will have the same size as the first dimension of the `samples` array
 - `metadata` - a `struct` containing information about this data, such as the ID of the processor it originated from.
 
 
 ## Loading event data
 
-Event data for each recording is accessed via the `.events` property of each `Recording` object. This returns a pandas DataFrame with the following columns:
+### TTL Events
 
-- `timestamp` - the sample index at which this event occurred
-- `channel` - the channel on which this event occurred
-- `nodeId` - the ID of the processor from which this event originated
+`recording.ttlEvents('Neuropixels-PXI.Probe-A')`
+
+This returns a pandas-like DataFrame with the following columns
+
+- `line` - the event line number 
+- `sample_number` - the sample index at which this event occurred
+- `timestamp` - the synchronized timestamp at which this event occurred (if available)
+- `processor_id` - the ID of the processor from which this event originated
+- `stream_name` - the full identifier for the stream (Neuropixels_PXI-100.Probe-A) 
 - `state` - 1 or 0, to indicate whether this is a rising edge or falling edge event
 
+### Message Events
+
+`recording.messages('MessageCenter')`
+
+This returns a pandas-like DataFrame with the following columns
+
+- `timestamps` - the synchronized timestamp (if available) at which this event occurred
+- `sample_number` - the sample index at which this event occurred
+- `text` - the text of the message
 
 ## Loading spike data
 
 If spike data has been saved by your Record Node (i.e., there is a Spike Detector or Spike Sorter upstream in the signal chain), this can be accessed via the `.spikes` property of each `Recording` object. This returns a list of spike sources, each of which has the following properties:
 
 - `waveforms` - `array` containing spike waveforms, with dimensions of spikes x channels x samples
-- `timestamps` - `array` of sample indices (one per spikes)
-- `electrodes` - `array` containing the index of the electrode from which each spike originated
-- `metadata` - `struct` with metadata about each electrode
-
-
+- `timestamps` - `array` of synchronized timestamps (if available) for each spike
+- `sample_numbers` - `array` of sample indices for each spike
+- `electrodes` - `array` containing the index of the electrode from which each spike originated

open_ephys/analysis/Session.m

@@ -78,7 +78,7 @@ function show(self)
             for i = 1:length(self.recordNodes)
 
                 node = self.recordNodes{i};
-                fprintf("Found record node: (%d) %s : %s Format \n", i, node.name, node.format);
+                fprintf("(%d) %s : %s Format \n", i, node.name, node.format);
 
             end
 

open_ephys/control/README.md

@@ -2,6 +2,160 @@
 
 This module makes it possible to control the [Open Ephys GUI](https://open-ephys.org/gui) via Matlab, either running locally or over a network.
 
+## OpenEphysHTTPServer
+
+Starting in GUI v0.6.0 we recommend using the OpenEphysHTTPServer to control the GUI remotely. 
+
+### Usage
+
+Create an instance of the OpenEphysHTTPServer class:
+
+```matlab
+gui = OpenEphysHTTPServer('127.0.0.1', 34947)
+```
+
+Get the processor list (all available processors to use in a signal chain)
+
+```matlab
+gui.getProcessorList()
+```
+
+Get the processors in the current signal chain
+
+```matlab
+gui.getProcessors()
+```
+
+Clear the current signal chain
+
+```matlab
+gui.clearSignalChain()
+```
+
+Add a processor to the signal chain (source and destination are optional, if not included will add to end of signal chain)
+
+```matlab
+gui.addProcessor(processorName, source, destination)
+```
+
+Delete a processor from the signal chain
+
+```matlab
+gui.deleteProcessor(processorId)
+```
+
+Get the parameters for a processor
+
+```matlab
+gui.getParameters(processorId, streamIdx)
+```
+
+Set the parameters for a processor
+
+```matlab
+gui.setParameter(processorId, streamIdx, paramName, value)
+```
+
+Get recording information
+
+```matlab
+gui.getRecordingInfo(key)
+```
+
+Set parent recording directory
+
+```matlab
+gui.setParentDirectory(path)
+```
+
+Set prepend text
+
+```matlab
+gui.setPrependText(text)
+```
+
+Set base text
+
+```matlab
+gui.setBaseText(text)
+```
+
+Set append text
+
+```matlab
+gui.setAppendText(text)
+```
+
+Set start new directory flag (starts a new directory for the next recording)
+
+```matlab
+gui.setStartNewDirectory()
+```
+
+Set file path to load for a FileReader
+
+```matlab
+gui.setFileReaderPath(nodeId, path)
+```
+
+Set file index to load for a FileReader
+
+```matlab
+gui.setFileReaderIndex(nodeId, index)
+```
+
+Set record engine
+
+```matlab
+gui.setRecordEngine(nodeId, engine)
+```
+
+Set record path
+
+```matlab
+gui.setRecordPath(nodeId, directory)
+```
+
+Get GUI status (acquiring, recording or idle)
+
+```matlab
+gui.getStatus()
+```
+
+Start acquisition (duration is optional)
+
+```matlab
+gui.acquire(duration)
+```
+
+Stop recording (duration is optional)
+
+```matlab
+gui.record(duration)
+```
+
+Stop acquisition/recording (duration is optional)
+
+```matlab
+gui.idle(duration)
+```
+
+Send a text message to all processors in the signal chain
+
+```matlab
+gui.message(text)
+```
+
+Quit the GUI
+
+```matlab
+gui.quit()
+```
+
+## NetworkControl
+
+### Usage
+
 Your GUI's signal chain must include a [NetworkEvents](https://open-ephys.github.io/gui-docs/User-Manual/Plugins/Network-Events.html) plugin in order for this module to work.
 
 To use the control module in Matlab: