Update readme for 0.3.0

README.md

@@ -4,29 +4,56 @@ This is an NWB extension for storing timestamped event data and TTL pulses.
 
 The latest version is 0.3.0. This is a major change from previous versions.
 
-Events can be:
-1. **Simple events**. These are stored in the `Events` type. The `Events` type consists of only a name, a description,
-and a 1D array of timestamps. This should be used instead of a `TimeSeries` when the time series has no data.
-2. **Labeled events**. These are stored in the `LabeledEvents` type. The `LabeledEvents` type expands on the `Events`
-type by adding 1) a 1D array of integer values (data) with the same length as the timestamps and 2) a 1D array of
-labels (labels) associated with each unique integer value in the data array. The data values are indices into the
-array of labels. The `LabeledEvents` type can be used to encode additional information about individual events,
-such as the reward values for each reward event.
-3. **TTL pulses**. These are stored in the `TTLs` type. The `TTLs` type is a subtype of the `LabeledEvents` type
-specifically for TTL pulse data. A single instance should be used for all TTL pulse data. The pulse value (or channel)
-should be stored in the 1D data array, and the labels associated with each pulse value (or channel)
-should be stored in the 1D array of labels.
-4. **Annotated events**. These are stored in the `AnnotatedEventsTable` type. The `AnnotatedEventsTable` type is a
-subtype of `DynamicTable`, where each row corresponds to a different event type. The table has a ragged
-(variable-length) 1D column of event times, such that each event type (row) is associated with an array of event times.
-Unlike for the other event types, users can add their own custom columns to annotate each event type or event time.
-This can be useful for storing event metadata related to data preprocessing and analysis, such as marking bad events.
+**`EventTypesTable`**: Event types (e.g., lick, reward left, reward right, airpuff, reach) and metadata about them should be stored in an `EventTypesTable` object.
+- `EventTypesTable` inherits from `DynamicTable` and stores metadata related to each event type, one per row. 
+- An "event_name" text column is required.
+- A "event_type_description" text column is required.
+- The table allows for an arbitrary number of custom columns to be added for additional metadata for each event type. 
+- This table is intended to live in a `Task` object at the path "general/task" in the `NWBFile`.
+
+**`EventsTable`**: Event times and metadata about them should be stored in an `EventsTable` object.
+- `EventsTable` inherits from `DynamicTable` and stores metadata related to each event time / instance, one per row.
+- A "timestamp" column of type `TimestampVectorData` is required.
+- A “duration” column of type `DurationVectorData` is optional. 
+- An “event_type” column that is a foreign key reference to a row index of the `EventTypesTable` is required.
+- A "value" text column is optional. This enables storage of another layer of events within an event type. This could store different reward sizes or different tone frequencies or other parameterizations of an event. For example, if you have three levels of reward (e.g., 1 drop, 2 drops, 3 drops), instead of encoding each level of reward as its own event type (e.g., "reward_value_1", "reward_value_2", "reward_value_3", you could encode "reward" as the event type, and the value for each event time could be "1", "2", or "3". 
+- Because this inherits from `DynamicTable`, users can add additional custom columns to store other metadata.
+- This table is intended to live either under the "acquisition" group or in a "behavior" `ProcessingModule`, i.e., under the "processing/behavior" group.
+
+**`TtlTypesTable`**: TTL pulse types and metadata about them should be stored in a `TtlTypesTable` object. 
+- `TtlTypesTable` inherits from `EventTypesTable` and stores metadata related to each TTL pulse type, one per row. 
+- A "pulse_value" unsigned integer column is required. 
+- This table is intended to live in a `Task` object at the path "general/task" in the `NWBFile`.
+
+**`TtlsTable`**: TTL pulses and metadata about them should be stored in a `TtlsTable` object.
+- `TtlsTable` inherits from `EventsTable`.
+- The "event_type" column inherited from `EventsTable` should refer to the `TtlTypesTable`.
+- This table is intended to live either under the "acquisition" group or in a "behavior" `ProcessingModule`, i.e., under the "processing/behavior" group.
+
+This extension defines a few additional neurodata types related to storing events:
+
+**`Task`**: `Task` type is a subtype of the `LabMetaData` type and holds the `EventTypesTable` and `TtlTypesTable`. This allows the `Task` type to be added as a group in the root "general" group. 
+
+**`TimestampVectorData`**: The `TimestampVectorData` type stores a 1D array of timestamps in seconds.
+- Values are in seconds from session start time.
+- It has a "unit" attribute. The value of the attribute is fixed to "seconds".
+- It has a "resolution" attribute that represents the smallest possible difference between two timestamps. Usually 1 divided by the sampling rate for timestamps of the data acquisition system.
+
+**`DurationVectorData`**: The `DurationVectorData` type that stores a 1D array of durations in seconds.
+- It is otherwise identical to the `TimestampVectorData` type.
 
 This extension was developed by Ryan Ly, Oliver Rübel, and the NWB Technical Advisory Board.
 Information about the rationale, background, and alternative approaches to this extension can be found here:
 https://docs.google.com/document/d/1qcsjyFVX9oI_746RdMoDdmQPu940s0YtDjb1en1Xtdw
 
 ## Installation
+
+The latest **ndx-events 0.3.0** has not yet been released on PyPI. To install it on Python, use:
+```bash
+pip install git+https://github.com/rly/ndx-events.git
+```
+
+To install the 0.2.0 version, use:
 Python:
 ```bash
 pip install -U ndx-events
@@ -61,8 +88,5 @@ ruff .
 codespell .
 ```
 
-## Example usage
-Python:
-
 
 This extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).