From fee5b28ee4eccff1ebd4b6ebcc819cb00d34acef Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Thu, 14 Jul 2022 19:29:59 -0500
Subject: [PATCH 001/143] Started the remodelling tools documentation pages
---
docs/source/DesignMatricesWithHed.md | 171 ++++++++++
docs/source/EventRestructuring.md | 125 +++++++
docs/source/HedRemodelingTools.md | 305 ++++++++++++++++++
docs/source/HedSearchingAndSummary.md | 171 ++++++++++
.../bids_validate_dataset.ipynb | 4 +-
...bids_validate_dataset_with_libraries.ipynb | 2 +-
.../matlab_scripts/web_services/runAllTests.m | 1 +
7 files changed, 776 insertions(+), 3 deletions(-)
create mode 100644 docs/source/DesignMatricesWithHed.md
create mode 100644 docs/source/EventRestructuring.md
create mode 100644 docs/source/HedRemodelingTools.md
create mode 100644 docs/source/HedSearchingAndSummary.md
diff --git a/docs/source/DesignMatricesWithHed.md b/docs/source/DesignMatricesWithHed.md
new file mode 100644
index 0000000..99471e0
--- /dev/null
+++ b/docs/source/DesignMatricesWithHed.md
@@ -0,0 +1,171 @@
+# Event restructuring
+
+
+
+This tutorial takes you through the steps of annotating the events
+using HED (Hierarchical Event Descriptors).
+The tutorial focuses on how to make good choices of HED annotations
+to make your data usable for downstream analysis.
+The mechanics of putting your selected HED annotations into
+[BIDS (Brain Imaging Data Structure)](https://bids.neuroimaging.io/) format
+is covered in the [**BIDS annotation quickstart**](./BidsAnnotationQuickstart.md) guide.
+
+* [**What is HED annotation?**](what-is-hed-annotation-anchor)
+* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
+
+(what-is-hed-annotation-anchor)=
+## What is HED annotation?
+
+A HED annotation consists of a comma separated list of tags selected from
+a HED vocabulary or schema.
+An important reason for using an agreed-upon vocabulary rather than
+free-form tagging for annotation is to avoid confusion and ambiguity
+and to promote data-sharing.
+
+The basic terms are organized into trees for easier access and search.
+The [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html) allows
+you to explore these terms.
+
+(a-recipe-for-simple-annotation-anchor)=
+## A recipe for simple annotation
+In thinking about how to annotate an event, you should always start
+by selecting a tag from the *Event* subtree to indicate the general event category.
+Possible choices are: *Sensory-event*, *Agent-action*, *Data-feature*, *Experiment-control*,
+*Experiment-procedure*, *Experiment-structure*, and *Measurement-event*.
+See the [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html)
+to view the available tags.
+
+Most experiments will only have a few types of distinct events.
+The simplest way to create a minimal HED annotation for your events is:
+
+1. Select one of the 7 tags from the *Event* subtree to designate the general category of the event.
+2. Use the following table to select the appropriate supporting tags given that event type.
+
+(standard-hed-tag-selections-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Event tag | Support tag type | Example tags | Reason |
+| ------------- | -------------------- | ------------ | ------ |
+| **Sensory-event** | *Sensory-presentation* | *Visual-presentation*
*Auditory-presentation*| Which sense? |
+| | *Task-event-role* | *Experimental-stimulus*
*Instructional* | What task role? |
+| | *Task-stimulus-role* | *Cue*
*Target* | Stimulus purpose? |
+| | *Item* | *(Face, Image)*
*Siren* | What is presented? |
+| | *Sensory-attribute* | *Red* | What modifiers are needed? |
+| **Agent-action** | *Agent-task-role* | *Experiment-participant* | Who is agent? |
+| | *Action* | *Move*
*Press* | What action is performed? |
+| | *Task-action-type* | *Appropriate-action*
*Near-miss* | What task relationship? |
+| | *Item* | *Arm*
*Mouse-button* | What is action target? |
+| **Data-feature** | *Data-source-type* | *Expert-annotation*
*Computed-feature* | Where did the feature come from? |
+| | *Label* | *Label/Blinker_BlinkMax* | Tool name?
Feature type? |
+| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | Feature value or type? |
+| **Experiment-control** | *Agent* | *Controller-Agent* | What is the controller? |
+| | *Informational* | *Label/Stop-recording* | What did the controller do? |
+| **Experiment-procedure** | *Task-event-role* | *Task-activity* | What procedure? |
+| **Experiment-structure** | *Organizational-property* | *Time-block*
*Condition-variable* | What structural property? |
+| **Measurement-event** | *Data-source-type* | *Instrument-measurement*
*Observation* | Source of the data. |
+| | *Label* | *Label/Oximeter_O2Level* | Instrument name?
Measurement type? |
+| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | What value or type?
+```
+
+
+As in BIDS, we assume that the event metadata is given in tabular form.
+Each table row represents the metadata associated with a single data event marker,
+as shown in the following excerpt of the `events.tsv` file for a simple Go/No-go experiment.
+The `onset` column gives the time in seconds of the marker relative
+to the beginning of the associated data file.
+
+(example-go-no-go-event-table-anchor)=
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+In the Go/No-go experiment, the experimental participant is presented
+with a series of target and distractor animal images.
+The participant is instructed to lift a finger off a button
+when a target animal image appears.
+Since in this experiment, the `value` column has distinct values
+for all possible unique event types, the `event_type` column is redundant.
+In this case, we can choose to assign all the annotations to
+the `value` column as demonstrated in the following example.
+
+````{admonition} Version 1: Assigning all annotations to the value column.
+
+| value | Event category | Supporting tags |
+| ------- | -------------- | --------------- |
+| animal_target | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
+| animal_distractor | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Non-target*, *Distractor*, (*Animal*, *Image*) |
+| correct_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Correct-action* |
+| incorrect_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Incorrect-action* |
+
+````
+
+The table above shows the event category and the supporting tags as suggested in the
+[**Standard hed tags for minimal annotation**](standard-hed-tag-selections-anchor) table.
+
+A better format for your annotations is the
+[**4-column spreadsheet format**](four-column-spreadsheet-format-anchor) described in
+[**BIDS annotation quickstart**](BidsAnnotationQuickstart.md), since there are online
+tools to convert this format into a JSON sidecar that can be deployed directly in
+a BIDS dataset.
+
+````{admonition} 4-column spreadsheet format for the previous example.
+
+| column_name| column_value | description | HED |
+| ------- | -------------- | ----------- | ------- |
+| value | animal_target | An target animal image was
presented on a screen. |*Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
+| value | animal_distractor | A non-target animal distractor
image was presented
on a screen. | *Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*, *Non-target*,
*Distractor*, (*Animal*, *Image*)|
+| value | correct_response | Participant correctly
lifted finger off button. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Correct-action* |
+| value | incorrect_response | Participant lifted finger off
the button but should not have. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Incorrect-action* |
+
+````
+
+HED tools assemble the annotations for each event into a single HED tag string.
+An exactly equivalent version of the previous example splits the HED tag annotation between
+the `event_type` and `value` columns as shown in the next example.
+
+````{admonition} Version 2: Assigning annotations to multiple event file columns.
+
+| column_name | column_value | description | HED |
+| ------- | -------------- | --------------- | ------ |
+| event_type | stimulus | An image of an animal
was presented on a
computer screen.| *Sensory-event*,
*Visual-presentation*,
*experimental-stimulus* |
+| event_type | response | Participant lifted finger
off button.| *Agent-action*,
*Experiment-participant*,
(*Lift*, *Finger*) |
+| value | animal_target | A target animal image. | *Target*, (*Animal*, *Image*) |
+| value | animal_distractor | A non-target animal image
meant as a distractor. | *Non-target*, *Distractor*,
(*Animal*, *Image*) |
+| value | correct_response | The previous stimulus
was a target animal. | *Correct-action* |
+| value | incorrect_response | The previous stimulus
was not a target animal. | *Incorrect-action* |
+| stim_file | n/a | Filename of stimulus image. | (*Image*, *Pathname/#*) |
+````
+In version 2, the annotations that are common
+to all stimuli and responses are assigned to `event_type`.
+We have also included the annotation for the `stim_file` column in the last row
+of this table.
+
+The assembled annotation for the first event (with onset 5.035) in the
+[**event file excerpt from go/no-go**](example-go-no-go-event-table-anchor) above is:
+
+> *Sensory-event*, *Visual-presentation*, *Experimental-stimulus*, *Target*, (*Animal*, *Image*), (*Image*, *Pathname/105064.jpg*)
+
+Mapping annotations and column information across multiple column values often makes
+the annotation process simpler, especially when annotations become more complex.
+Multiple column representation also can make analysis easier,
+particularly if the columns represent information such as design variables.
+
+See [**BIDS annotation quick start**](BidsAnnotationQuickstart.md#bids-annotation-quickstart) for how to
+create templates to fill in with your annotations using online tools.
+Once you have completed the annotation and converted it to a sidecar,
+you simply need to place this sidecar in the root directory of your BIDS dataset.
+
+This quick start demonstrates the most basic HED annotations.
+HED is capable of much more extensive and expressive annotations as
+explained in a series of tutorials on this site.
\ No newline at end of file
diff --git a/docs/source/EventRestructuring.md b/docs/source/EventRestructuring.md
new file mode 100644
index 0000000..42c7553
--- /dev/null
+++ b/docs/source/EventRestructuring.md
@@ -0,0 +1,125 @@
+# Event restructuring
+
+This tutorial works through the process of restructuring event files using the HED event remodeling tools. The tools are designed to be run on an entire BIDS dataset.
+
+* [**What is HED annotation?**](what-is-hed-annotation-anchor)
+* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
+
+(what-is-event-restructuring-anchor)=
+## What is event restructuring?
+
+
+(a-recipe-for-simple-annotation-anchor)=
+## Installation and running of the restructuring
+
+
+(standard-hed-tag-selections-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Event tag | Support tag type | Example tags | Reason |
+| ------------- | -------------------- | ------------ | ------ |
+| **Sensory-event** | *Sensory-presentation* | *Visual-presentation*
*Auditory-presentation*| Which sense? |
+```
+
+
+As in BIDS, we assume that the event metadata is given in tabular form.
+Each table row represents the metadata associated with a single data event marker,
+as shown in the following excerpt of the `events.tsv` file for a simple Go/No-go experiment.
+The `onset` column gives the time in seconds of the marker relative
+to the beginning of the associated data file.
+
+(example-go-no-go-event-table-anchor)=
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+In the Go/No-go experiment, the experimental participant is presented
+with a series of target and distractor animal images.
+The participant is instructed to lift a finger off a button
+when a target animal image appears.
+Since in this experiment, the `value` column has distinct values
+for all possible unique event types, the `event_type` column is redundant.
+In this case, we can choose to assign all the annotations to
+the `value` column as demonstrated in the following example.
+
+````{admonition} Version 1: Assigning all annotations to the value column.
+
+| value | Event category | Supporting tags |
+| ------- | -------------- | --------------- |
+| animal_target | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
+| animal_distractor | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Non-target*, *Distractor*, (*Animal*, *Image*) |
+| correct_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Correct-action* |
+| incorrect_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Incorrect-action* |
+
+````
+
+The table above shows the event category and the supporting tags as suggested in the
+[**Standard hed tags for minimal annotation**](standard-hed-tag-selections-anchor) table.
+
+A better format for your annotations is the
+[**4-column spreadsheet format**](four-column-spreadsheet-format-anchor) described in
+[**BIDS annotation quickstart**](BidsAnnotationQuickstart.md), since there are online
+tools to convert this format into a JSON sidecar that can be deployed directly in
+a BIDS dataset.
+
+````{admonition} 4-column spreadsheet format for the previous example.
+
+| column_name| column_value | description | HED |
+| ------- | -------------- | ----------- | ------- |
+| value | animal_target | An target animal image was
presented on a screen. |*Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
+| value | animal_distractor | A non-target animal distractor
image was presented
on a screen. | *Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*, *Non-target*,
*Distractor*, (*Animal*, *Image*)|
+| value | correct_response | Participant correctly
lifted finger off button. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Correct-action* |
+| value | incorrect_response | Participant lifted finger off
the button but should not have. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Incorrect-action* |
+
+````
+
+HED tools assemble the annotations for each event into a single HED tag string.
+An exactly equivalent version of the previous example splits the HED tag annotation between
+the `event_type` and `value` columns as shown in the next example.
+
+````{admonition} Version 2: Assigning annotations to multiple event file columns.
+
+| column_name | column_value | description | HED |
+| ------- | -------------- | --------------- | ------ |
+| event_type | stimulus | An image of an animal
was presented on a
computer screen.| *Sensory-event*,
*Visual-presentation*,
*experimental-stimulus* |
+| event_type | response | Participant lifted finger
off button.| *Agent-action*,
*Experiment-participant*,
(*Lift*, *Finger*) |
+| value | animal_target | A target animal image. | *Target*, (*Animal*, *Image*) |
+| value | animal_distractor | A non-target animal image
meant as a distractor. | *Non-target*, *Distractor*,
(*Animal*, *Image*) |
+| value | correct_response | The previous stimulus
was a target animal. | *Correct-action* |
+| value | incorrect_response | The previous stimulus
was not a target animal. | *Incorrect-action* |
+| stim_file | n/a | Filename of stimulus image. | (*Image*, *Pathname/#*) |
+````
+In version 2, the annotations that are common
+to all stimuli and responses are assigned to `event_type`.
+We have also included the annotation for the `stim_file` column in the last row
+of this table.
+
+The assembled annotation for the first event (with onset 5.035) in the
+[**event file excerpt from go/no-go**](example-go-no-go-event-table-anchor) above is:
+
+> *Sensory-event*, *Visual-presentation*, *Experimental-stimulus*, *Target*, (*Animal*, *Image*), (*Image*, *Pathname/105064.jpg*)
+
+Mapping annotations and column information across multiple column values often makes
+the annotation process simpler, especially when annotations become more complex.
+Multiple column representation also can make analysis easier,
+particularly if the columns represent information such as design variables.
+
+See [**BIDS annotation quick start**](BidsAnnotationQuickstart.md#bids-annotation-quickstart) for how to
+create templates to fill in with your annotations using online tools.
+Once you have completed the annotation and converted it to a sidecar,
+you simply need to place this sidecar in the root directory of your BIDS dataset.
+
+This quick start demonstrates the most basic HED annotations.
+HED is capable of much more extensive and expressive annotations as
+explained in a series of tutorials on this site.
\ No newline at end of file
diff --git a/docs/source/HedRemodelingTools.md b/docs/source/HedRemodelingTools.md
new file mode 100644
index 0000000..9969e29
--- /dev/null
+++ b/docs/source/HedRemodelingTools.md
@@ -0,0 +1,305 @@
+# HED remodeling tools
+
+This tutorial works through the process of restructuring event files using the HED event remodeling tools. The tools are designed to be run on an entire BIDS dataset.
+
+* [**What is HED annotation?**](what-is-hed-annotation-anchor)
+* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
+
+(what-is-event-restructuring-anchor)=
+## What is event restructuring?
+
+
+(a-recipe-for-simple-annotation-anchor)=
+## Installation and running of the restructuring
+
+(remodeling-operations)=
+## Remodeling operations
+
+
+### Add structure
+
+Use: Add trial or block markers --- used for epoching around the start of a trial. The duration is the duration of the trial or block respectively.
+
+
+
+### Add trial numbers
+Add a column with the trial numbers.
+
+
+
+### Derive column
+
+Create a new column or overwrite values in an existing column using a mapping from existing columns. Can also be used to overwrite values on existing columns, only values with the predefined combinations will be overwritten.
+
+
+(parameters-for-derive-column-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The following example ....
+
+```json
+{
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+}
+```
+Results in the following:
+
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+
+### Factor column
+
+Factor each of the specified values in the indicated column into a column containing 1’s and 0’s indicating presence and absence. If no values are specified, all unique values in that column are factored.
+
+### Factor HED
+
+Produce a list of factor columns based on the specified HED condition-variable values.
+
+### Merge events
+One long event is represented by multiple repeat events. Merges these same events occurring consecutively into one event with duration of the new event updated as the sum of all merged events.
+
+### Remove columns
+
+Remove the specified columns if present.
+
+
+(parameters-for-remove-columns-anchor)=
+```{admonition} Parameters for the remove_columns operation.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_names | list of str | A list of columns to remove.|
+```
+
+Example command:
+```json
+{
+ "column_names": ["sample", "ethn_target", "ethn_distractor"]
+}
+```
+
+```{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+### Remove rows
+
+Remove rows where specified columns take particular values.
+
+(parameters-for-remove-rows-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The following example ....
+
+```json
+{
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+}
+```
+Results in the following:
+
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+### Rename columns
+
+Rename columns by providing old name and new name.
+
+(parameters-for-rename-columns-anchor)=
+```{admonition} Parameters for rename_columns.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| mapping | dict | The keys are the old column names and the values are the new names.|
+| ignore_missing | bool | If false, an error is thrown if any keys are missing. |
+
+```
+The following example ....
+
+```json
+{
+ "mapping": {
+ "face_type": "xxx",
+ "hand": "response_hand"
+ },
+ "ignore_missing": true
+}
+
+```
+Results in the following:
+
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+### Reorder columns
+
+Reorder the columns in the specified order. Columns not included are discarded or placed at the end. If a specified column is not in the data --- do what?
+
+(parameters-for-reorder-columns-anchor)=
+```{admonition} Parameters for reorder_columns.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_names | list of str | A list of columns in the order they should appear in the data.|
+| keep_missing | boolean | If true, existing columns that aren't in column_names are moved to the end and in the same relative order that they originally appeared in the data. |
+
+```
+
+
+```json
+{
+ "column_names": ["onset", "duration", "trial_type", "response_time"],
+ "keep_missing": false
+}
+```
+
+Results in the following:
+
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+### Split event
+
+The split_event is the most complicated of the remodeling operations and generally
+Multiple information and responses are encoded in a single event. Split this event into multiple lines in the event file and adjust the meanings of the columns — usually this means removing the original event and replacing it with new events at various offsets.
+The final result has rows ordered by increasing offsets.
+
+Rename columns by providing old name and new name.
+
+(parameters-for-split-event-anchor)=
+```{admonition} Parameters for split_event.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column that will be used for split-event codes.|
+| split_dict | dict | Dictionary specifying how the split should occur. |
+|remove_parent_event | bool | If true, remove parent event. |
+
+```
+
+The `column_name` is the column that the split event codes are written.
+If this column does not exist in the `events.tsv` file it is added prior to the split processing.
+
+(parameters-for-split-dict-anchor)=
+```{admonition} values for split_dict.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| onset_source | list | A list of column names and numbers representing values added to the onset of the parent event.|
+| split_dict | dict | Dictionary specifying how the split should occur. |
+|remove_parent_event | bool | If true, remove parent event. |
+
+```
+
+The
+The following example ....
+
+```json
+{
+ "mapping": {
+ "face_type": "xxx",
+ "hand": "response_hand"
+ },
+ "ignore_missing": true
+}
+
+```
+Results in the following:
+
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
diff --git a/docs/source/HedSearchingAndSummary.md b/docs/source/HedSearchingAndSummary.md
new file mode 100644
index 0000000..99471e0
--- /dev/null
+++ b/docs/source/HedSearchingAndSummary.md
@@ -0,0 +1,171 @@
+# Event restructuring
+
+
+
+This tutorial takes you through the steps of annotating the events
+using HED (Hierarchical Event Descriptors).
+The tutorial focuses on how to make good choices of HED annotations
+to make your data usable for downstream analysis.
+The mechanics of putting your selected HED annotations into
+[BIDS (Brain Imaging Data Structure)](https://bids.neuroimaging.io/) format
+is covered in the [**BIDS annotation quickstart**](./BidsAnnotationQuickstart.md) guide.
+
+* [**What is HED annotation?**](what-is-hed-annotation-anchor)
+* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
+
+(what-is-hed-annotation-anchor)=
+## What is HED annotation?
+
+A HED annotation consists of a comma separated list of tags selected from
+a HED vocabulary or schema.
+An important reason for using an agreed-upon vocabulary rather than
+free-form tagging for annotation is to avoid confusion and ambiguity
+and to promote data-sharing.
+
+The basic terms are organized into trees for easier access and search.
+The [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html) allows
+you to explore these terms.
+
+(a-recipe-for-simple-annotation-anchor)=
+## A recipe for simple annotation
+In thinking about how to annotate an event, you should always start
+by selecting a tag from the *Event* subtree to indicate the general event category.
+Possible choices are: *Sensory-event*, *Agent-action*, *Data-feature*, *Experiment-control*,
+*Experiment-procedure*, *Experiment-structure*, and *Measurement-event*.
+See the [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html)
+to view the available tags.
+
+Most experiments will only have a few types of distinct events.
+The simplest way to create a minimal HED annotation for your events is:
+
+1. Select one of the 7 tags from the *Event* subtree to designate the general category of the event.
+2. Use the following table to select the appropriate supporting tags given that event type.
+
+(standard-hed-tag-selections-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Event tag | Support tag type | Example tags | Reason |
+| ------------- | -------------------- | ------------ | ------ |
+| **Sensory-event** | *Sensory-presentation* | *Visual-presentation*
*Auditory-presentation*| Which sense? |
+| | *Task-event-role* | *Experimental-stimulus*
*Instructional* | What task role? |
+| | *Task-stimulus-role* | *Cue*
*Target* | Stimulus purpose? |
+| | *Item* | *(Face, Image)*
*Siren* | What is presented? |
+| | *Sensory-attribute* | *Red* | What modifiers are needed? |
+| **Agent-action** | *Agent-task-role* | *Experiment-participant* | Who is agent? |
+| | *Action* | *Move*
*Press* | What action is performed? |
+| | *Task-action-type* | *Appropriate-action*
*Near-miss* | What task relationship? |
+| | *Item* | *Arm*
*Mouse-button* | What is action target? |
+| **Data-feature** | *Data-source-type* | *Expert-annotation*
*Computed-feature* | Where did the feature come from? |
+| | *Label* | *Label/Blinker_BlinkMax* | Tool name?
Feature type? |
+| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | Feature value or type? |
+| **Experiment-control** | *Agent* | *Controller-Agent* | What is the controller? |
+| | *Informational* | *Label/Stop-recording* | What did the controller do? |
+| **Experiment-procedure** | *Task-event-role* | *Task-activity* | What procedure? |
+| **Experiment-structure** | *Organizational-property* | *Time-block*
*Condition-variable* | What structural property? |
+| **Measurement-event** | *Data-source-type* | *Instrument-measurement*
*Observation* | Source of the data. |
+| | *Label* | *Label/Oximeter_O2Level* | Instrument name?
Measurement type? |
+| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | What value or type?
+```
+
+
+As in BIDS, we assume that the event metadata is given in tabular form.
+Each table row represents the metadata associated with a single data event marker,
+as shown in the following excerpt of the `events.tsv` file for a simple Go/No-go experiment.
+The `onset` column gives the time in seconds of the marker relative
+to the beginning of the associated data file.
+
+(example-go-no-go-event-table-anchor)=
+````{admonition} Event file from a simple Go/No-go experiment.
+
+| onset | duration | event_type | value | stim_file |
+| ----- | -------- | ---------- | ----- | --------- |
+| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
+| 5.370 | n/a | response | correct_response | n/a |
+| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
+| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
+| 8.940 | n/a | response | correct_response | n/a |
+| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
+| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
+| 12.943 | n/a | response | incorrect_response | n/a |
+````
+
+In the Go/No-go experiment, the experimental participant is presented
+with a series of target and distractor animal images.
+The participant is instructed to lift a finger off a button
+when a target animal image appears.
+Since in this experiment, the `value` column has distinct values
+for all possible unique event types, the `event_type` column is redundant.
+In this case, we can choose to assign all the annotations to
+the `value` column as demonstrated in the following example.
+
+````{admonition} Version 1: Assigning all annotations to the value column.
+
+| value | Event category | Supporting tags |
+| ------- | -------------- | --------------- |
+| animal_target | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
+| animal_distractor | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Non-target*, *Distractor*, (*Animal*, *Image*) |
+| correct_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Correct-action* |
+| incorrect_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Incorrect-action* |
+
+````
+
+The table above shows the event category and the supporting tags as suggested in the
+[**Standard hed tags for minimal annotation**](standard-hed-tag-selections-anchor) table.
+
+A better format for your annotations is the
+[**4-column spreadsheet format**](four-column-spreadsheet-format-anchor) described in
+[**BIDS annotation quickstart**](BidsAnnotationQuickstart.md), since there are online
+tools to convert this format into a JSON sidecar that can be deployed directly in
+a BIDS dataset.
+
+````{admonition} 4-column spreadsheet format for the previous example.
+
+| column_name| column_value | description | HED |
+| ------- | -------------- | ----------- | ------- |
+| value | animal_target | An target animal image was
presented on a screen. |*Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
+| value | animal_distractor | A non-target animal distractor
image was presented
on a screen. | *Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*, *Non-target*,
*Distractor*, (*Animal*, *Image*)|
+| value | correct_response | Participant correctly
lifted finger off button. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Correct-action* |
+| value | incorrect_response | Participant lifted finger off
the button but should not have. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Incorrect-action* |
+
+````
+
+HED tools assemble the annotations for each event into a single HED tag string.
+An exactly equivalent version of the previous example splits the HED tag annotation between
+the `event_type` and `value` columns as shown in the next example.
+
+````{admonition} Version 2: Assigning annotations to multiple event file columns.
+
+| column_name | column_value | description | HED |
+| ------- | -------------- | --------------- | ------ |
+| event_type | stimulus | An image of an animal
was presented on a
computer screen.| *Sensory-event*,
*Visual-presentation*,
*experimental-stimulus* |
+| event_type | response | Participant lifted finger
off button.| *Agent-action*,
*Experiment-participant*,
(*Lift*, *Finger*) |
+| value | animal_target | A target animal image. | *Target*, (*Animal*, *Image*) |
+| value | animal_distractor | A non-target animal image
meant as a distractor. | *Non-target*, *Distractor*,
(*Animal*, *Image*) |
+| value | correct_response | The previous stimulus
was a target animal. | *Correct-action* |
+| value | incorrect_response | The previous stimulus
was not a target animal. | *Incorrect-action* |
+| stim_file | n/a | Filename of stimulus image. | (*Image*, *Pathname/#*) |
+````
+In version 2, the annotations that are common
+to all stimuli and responses are assigned to `event_type`.
+We have also included the annotation for the `stim_file` column in the last row
+of this table.
+
+The assembled annotation for the first event (with onset 5.035) in the
+[**event file excerpt from go/no-go**](example-go-no-go-event-table-anchor) above is:
+
+> *Sensory-event*, *Visual-presentation*, *Experimental-stimulus*, *Target*, (*Animal*, *Image*), (*Image*, *Pathname/105064.jpg*)
+
+Mapping annotations and column information across multiple column values often makes
+the annotation process simpler, especially when annotations become more complex.
+Multiple column representation also can make analysis easier,
+particularly if the columns represent information such as design variables.
+
+See [**BIDS annotation quick start**](BidsAnnotationQuickstart.md#bids-annotation-quickstart) for how to
+create templates to fill in with your annotations using online tools.
+Once you have completed the annotation and converted it to a sidecar,
+you simply need to place this sidecar in the root directory of your BIDS dataset.
+
+This quick start demonstrates the most basic HED annotations.
+HED is capable of much more extensive and expressive annotations as
+explained in a series of tutorials on this site.
\ No newline at end of file
diff --git a/hedcode/jupyter_notebooks/bids_validate_dataset.ipynb b/hedcode/jupyter_notebooks/bids_validate_dataset.ipynb
index 3dc2f79..08f359d 100644
--- a/hedcode/jupyter_notebooks/bids_validate_dataset.ipynb
+++ b/hedcode/jupyter_notebooks/bids_validate_dataset.ipynb
@@ -53,8 +53,8 @@
"name": "stdout",
"output_type": "stream",
"text": [
- "Using HEDTOOLS version: {'date': '2022-06-20T14:40:24-0500', 'dirty': False, 'error': None, 'full-revisionid': 'c4ecd1834cd31a05ebad3e97dc57e537550da044', 'version': '0.1.0'}\n",
- "HED Examples version: {'version': '0+untagged.233.ge70e761.dirty', 'full-revisionid': 'e70e761ea596de4fbebe926e1274ec64d85db4f1', 'dirty': True, 'error': None, 'date': '2022-06-20T11:11:00-0500'}\n",
+ "Using HEDTOOLS version: {'date': '2022-07-05T18:08:32-0500', 'dirty': True, 'error': None, 'full-revisionid': '63fc2f3a91c897d6c6d7ad163c33d80145b472cc', 'version': '0.1.0+38.g63fc2f3.dirty'}\n",
+ "HED Examples version: {'version': '0.1.0+0.gf9bf968.dirty', 'full-revisionid': 'f9bf968253e528ef49ad3b066d87f05bfefc8bc8', 'dirty': True, 'error': None, 'date': '2022-06-21T09:41:35-0500'}\n",
"BIDS path is: ../../datasets/eeg_ds003654s_hed\n",
"No HED validation errors\n",
"BIDS path is: ../../datasets/eeg_ds003654s_hed_column\n",
diff --git a/hedcode/jupyter_notebooks/bids_validate_dataset_with_libraries.ipynb b/hedcode/jupyter_notebooks/bids_validate_dataset_with_libraries.ipynb
index 4d91a60..8546104 100644
--- a/hedcode/jupyter_notebooks/bids_validate_dataset_with_libraries.ipynb
+++ b/hedcode/jupyter_notebooks/bids_validate_dataset_with_libraries.ipynb
@@ -53,7 +53,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
- "Handling a BIDS data set that uses library schema: ../../../datasets/eeg_ds003654s_hed_library\n",
+ "Handling a BIDS data set that uses library schema: ../../datasets/eeg_ds003654s_hed_library\n",
"No HED validation errors\n",
"\n",
"Now validating with the prerelease schema.\n",
diff --git a/hedcode/matlab_scripts/web_services/runAllTests.m b/hedcode/matlab_scripts/web_services/runAllTests.m
index 1e5d415..a26c179 100644
--- a/hedcode/matlab_scripts/web_services/runAllTests.m
+++ b/hedcode/matlab_scripts/web_services/runAllTests.m
@@ -1,4 +1,5 @@
host = 'https://hedtools.ucsd.edu/hed';
+host = 'http://127.0.0.1:5000/';
errorMap = containers.Map('KeyType', 'char', 'ValueType', 'any');
errorMap('testGetServices') = testGetServices(host);
errorMap('testEventServices') = testEventServices(host);
From dc922c2bf0f9e640321fa73e2016dfd3a53cb615 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Thu, 21 Jul 2022 14:00:28 -0500
Subject: [PATCH 002/143] Started working on documentation for the HED
remodeling tools
---
docs/source/EventRestructuring.md | 125 ----
...y.md => HedConditionsAndDesignMatrices.md} | 4 +-
docs/source/HedRemodelingTools.md | 678 ++++++++++++++----
...ricesWithHed.md => HedSearchAndSummary.md} | 4 +-
docs/source/index.rst | 9 +
5 files changed, 536 insertions(+), 284 deletions(-)
delete mode 100644 docs/source/EventRestructuring.md
rename docs/source/{HedSearchingAndSummary.md => HedConditionsAndDesignMatrices.md} (97%)
rename docs/source/{DesignMatricesWithHed.md => HedSearchAndSummary.md} (97%)
diff --git a/docs/source/EventRestructuring.md b/docs/source/EventRestructuring.md
deleted file mode 100644
index 42c7553..0000000
--- a/docs/source/EventRestructuring.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# Event restructuring
-
-This tutorial works through the process of restructuring event files using the HED event remodeling tools. The tools are designed to be run on an entire BIDS dataset.
-
-* [**What is HED annotation?**](what-is-hed-annotation-anchor)
-* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
-
-(what-is-event-restructuring-anchor)=
-## What is event restructuring?
-
-
-(a-recipe-for-simple-annotation-anchor)=
-## Installation and running of the restructuring
-
-
-(standard-hed-tag-selections-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
-:class: tip
-
-| Event tag | Support tag type | Example tags | Reason |
-| ------------- | -------------------- | ------------ | ------ |
-| **Sensory-event** | *Sensory-presentation* | *Visual-presentation*
*Auditory-presentation*| Which sense? |
-```
-
-
-As in BIDS, we assume that the event metadata is given in tabular form.
-Each table row represents the metadata associated with a single data event marker,
-as shown in the following excerpt of the `events.tsv` file for a simple Go/No-go experiment.
-The `onset` column gives the time in seconds of the marker relative
-to the beginning of the associated data file.
-
-(example-go-no-go-event-table-anchor)=
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
-````
-
-In the Go/No-go experiment, the experimental participant is presented
-with a series of target and distractor animal images.
-The participant is instructed to lift a finger off a button
-when a target animal image appears.
-Since in this experiment, the `value` column has distinct values
-for all possible unique event types, the `event_type` column is redundant.
-In this case, we can choose to assign all the annotations to
-the `value` column as demonstrated in the following example.
-
-````{admonition} Version 1: Assigning all annotations to the value column.
-
-| value | Event category | Supporting tags |
-| ------- | -------------- | --------------- |
-| animal_target | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
-| animal_distractor | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Non-target*, *Distractor*, (*Animal*, *Image*) |
-| correct_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Correct-action* |
-| incorrect_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Incorrect-action* |
-
-````
-
-The table above shows the event category and the supporting tags as suggested in the
-[**Standard hed tags for minimal annotation**](standard-hed-tag-selections-anchor) table.
-
-A better format for your annotations is the
-[**4-column spreadsheet format**](four-column-spreadsheet-format-anchor) described in
-[**BIDS annotation quickstart**](BidsAnnotationQuickstart.md), since there are online
-tools to convert this format into a JSON sidecar that can be deployed directly in
-a BIDS dataset.
-
-````{admonition} 4-column spreadsheet format for the previous example.
-
-| column_name| column_value | description | HED |
-| ------- | -------------- | ----------- | ------- |
-| value | animal_target | An target animal image was
presented on a screen. |*Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
-| value | animal_distractor | A non-target animal distractor
image was presented
on a screen. | *Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*, *Non-target*,
*Distractor*, (*Animal*, *Image*)|
-| value | correct_response | Participant correctly
lifted finger off button. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Correct-action* |
-| value | incorrect_response | Participant lifted finger off
the button but should not have. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Incorrect-action* |
-
-````
-
-HED tools assemble the annotations for each event into a single HED tag string.
-An exactly equivalent version of the previous example splits the HED tag annotation between
-the `event_type` and `value` columns as shown in the next example.
-
-````{admonition} Version 2: Assigning annotations to multiple event file columns.
-
-| column_name | column_value | description | HED |
-| ------- | -------------- | --------------- | ------ |
-| event_type | stimulus | An image of an animal
was presented on a
computer screen.| *Sensory-event*,
*Visual-presentation*,
*experimental-stimulus* |
-| event_type | response | Participant lifted finger
off button.| *Agent-action*,
*Experiment-participant*,
(*Lift*, *Finger*) |
-| value | animal_target | A target animal image. | *Target*, (*Animal*, *Image*) |
-| value | animal_distractor | A non-target animal image
meant as a distractor. | *Non-target*, *Distractor*,
(*Animal*, *Image*) |
-| value | correct_response | The previous stimulus
was a target animal. | *Correct-action* |
-| value | incorrect_response | The previous stimulus
was not a target animal. | *Incorrect-action* |
-| stim_file | n/a | Filename of stimulus image. | (*Image*, *Pathname/#*) |
-````
-In version 2, the annotations that are common
-to all stimuli and responses are assigned to `event_type`.
-We have also included the annotation for the `stim_file` column in the last row
-of this table.
-
-The assembled annotation for the first event (with onset 5.035) in the
-[**event file excerpt from go/no-go**](example-go-no-go-event-table-anchor) above is:
-
-> *Sensory-event*, *Visual-presentation*, *Experimental-stimulus*, *Target*, (*Animal*, *Image*), (*Image*, *Pathname/105064.jpg*)
-
-Mapping annotations and column information across multiple column values often makes
-the annotation process simpler, especially when annotations become more complex.
-Multiple column representation also can make analysis easier,
-particularly if the columns represent information such as design variables.
-
-See [**BIDS annotation quick start**](BidsAnnotationQuickstart.md#bids-annotation-quickstart) for how to
-create templates to fill in with your annotations using online tools.
-Once you have completed the annotation and converted it to a sidecar,
-you simply need to place this sidecar in the root directory of your BIDS dataset.
-
-This quick start demonstrates the most basic HED annotations.
-HED is capable of much more extensive and expressive annotations as
-explained in a series of tutorials on this site.
\ No newline at end of file
diff --git a/docs/source/HedSearchingAndSummary.md b/docs/source/HedConditionsAndDesignMatrices.md
similarity index 97%
rename from docs/source/HedSearchingAndSummary.md
rename to docs/source/HedConditionsAndDesignMatrices.md
index 99471e0..61cec8f 100644
--- a/docs/source/HedSearchingAndSummary.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -1,6 +1,6 @@
-# Event restructuring
-
+# HED conditions and design matrices
+**Under construction**
This tutorial takes you through the steps of annotating the events
using HED (Hierarchical Event Descriptors).
diff --git a/docs/source/HedRemodelingTools.md b/docs/source/HedRemodelingTools.md
index 9969e29..496c7f7 100644
--- a/docs/source/HedRemodelingTools.md
+++ b/docs/source/HedRemodelingTools.md
@@ -1,35 +1,167 @@
-# HED remodeling tools
+# Event file restructuring
+
+**UNDER DEVELOPMENT**
This tutorial works through the process of restructuring event files using the HED event remodeling tools. The tools are designed to be run on an entire BIDS dataset.
-* [**What is HED annotation?**](what-is-hed-annotation-anchor)
-* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
+* [**What is restructuring?**](what-is-event-file-restructuring-anchor)
+* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor)
+* [**Running remodeling tools**](running-remodeling-tools-anchor)
+* [**Remodeling operations**](remodeling-operations-anchor)
+ * [**Add structure**](add-structure-anchor) Docs not written
+ * [**Add trial numbers**](add-trial-numbers-anchor) Docs not written
+ * [**Derive column**](derive-column-anchor) Docs not written
+ * [**Factor column**](factor-column-anchor) Docs not written
+ * [**Factor HED**](factor-column-anchor) Docs not written
+ * [**Merge events**](merge-events-anchor) Docs not written
+ * [**Remove columns**](remove-columns-anchor)
+ * [**Rename columns**](rename-columns-anchor)
+ * [**Reorder columns**](reorder-columns-anchor)
+ * [**Split event**](split-event-anchor)
+
+
+(what-is-event-file-restructuring-anchor)=
+## What is event file restructuring?
+
+**Need brief introduction to event remodeling here**
-(what-is-event-restructuring-anchor)=
-## What is event restructuring?
+(installation-of-remodeling-tools-anchor)=
+## Installation of remodeling tools
+**Need information about installation.**
-(a-recipe-for-simple-annotation-anchor)=
-## Installation and running of the restructuring
+(running-remodeling-tools-anchor)=
+## Running remodeling tools
-(remodeling-operations)=
+**Need information about how to run**
+
+(remodeling-operations-anchor)=
## Remodeling operations
+The examples in this chapter use the following excerpt from sub-0013
+stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneuro.org) as ds002790.
+
+(sample-remodeling-events-file-anchor)=
+````{admonition} Excerpt from event file for a stop-go task.
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+(add-structure-anchor)=
### Add structure
+**NOT WRITTEN - PLACEHOLDER**
+
Use: Add trial or block markers --- used for epoching around the start of a trial. The duration is the duration of the trial or block respectively.
+(parameters-for-add-structure-anchor)=
+```{admonition} Parameters for the *add_structure* command.
+:class: tip
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list | Names of the columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The following example ....
+
+````{admonition} Parameters for the *add_structure* command.
+:class: tip
+
+```json
+{
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+}
+```
+````
+
+The results of executing the *add_structure* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Stop-go event file XXX.
+
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(add-trial-numbers-anchor)=
### Add trial numbers
+
+**NOT WRITTEN - PLACEHOLDER**
+
Add a column with the trial numbers.
+(parameters-for-add-trial-numbers-anchor)=
+```{admonition} Parameters for the *add_trial_numbers* command.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The following example ....
+
+````{admonition} An example .
+:class: tip
+
+```json
+{
+ "command": "add_trial_numbers"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+ }
+}
+```
+````
+
+The results of executing this command on the [**sample events file**](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Results of adding trial numbers to the file.
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+(derive-column-anchor)=
### Derive column
-Create a new column or overwrite values in an existing column using a mapping from existing columns. Can also be used to overwrite values on existing columns, only values with the predefined combinations will be overwritten.
+**NOT WRITTEN - PLACEHOLDER**
+
+Create a new column or overwrite values in an existing column using a mapping from existing columns.
+This command can be used to overwrite values particular values in existing columns
+based on predefined combinations of values in other columns.
(parameters-for-derive-column-anchor)=
@@ -42,49 +174,206 @@ Create a new column or overwrite values in an existing column using a mapping fr
| source_columns | list of str | A list of columns to be used for remapping. |
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The following example ....
+The following example creates a *match_side column* with values *left* and *right*
+based on particular combinations of values in the *response_accuracy* and
+*response_hand* columns.
+
+````{admonition} Create a *match_side* column with values *left* and *right*.
+:class: tip
```json
{
- "column_name": "match_side",
- "source_columns": ["response_accuracy", "response_hand"],
- "mapping": {
- "left": [["correct", "left"], ["incorrect", "right"]],
- "right": [["correct", "right"], ["incorrect", "left"]]
+ "command": "add_trial_numbers"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
}
}
```
-Results in the following:
-
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
````
+The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Adding a *match_side* column using the *derive_column* command.
+
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+(factor-column-anchor)=
### Factor column
+**NOT WRITTEN - PLACEHOLDER**
+
Factor each of the specified values in the indicated column into a column containing 1’s and 0’s indicating presence and absence. If no values are specified, all unique values in that column are factored.
+(parameters-for-factor-column-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The following example ....
+
+````{admonition} Create XXXX.
+:class: tip
+
+```json
+{
+ "command": "factor_column"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+ }
+}
+```
+````
+
+The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Results of factoring column XXX.
+
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(factor-hed-anchor)=
### Factor HED
+**NOT WRITTEN - PLACEHOLDER**
+
Produce a list of factor columns based on the specified HED condition-variable values.
+(parameters-for-factor-hed-anchor)=
+```{admonition} Parameters for factor_hed.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+
+The following example ....
+
+````{admonition} Create XXXX.
+:class: tip
+
+```json
+{
+ "command": "factor_hed"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+ }
+}
+```
+````
+
+The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Results of *factor_hed*.
+
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(merge-events-anchor)=
### Merge events
+
+**NOT WRITTEN - PLACEHOLDER**
+
One long event is represented by multiple repeat events. Merges these same events occurring consecutively into one event with duration of the new event updated as the sum of all merged events.
+(parameters-for-merge-events-anchor)=
+```{admonition} Standard HED tag selections for minimal annotation.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The following example ....
+
+````{admonition} Merge events.
+:class: tip
+
+```json
+{
+ "command": "merge_events"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+ }
+}
+```
+````
+
+The results of executing the example *merge_events* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} The results of the *merge_events* command.
+
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(remove-columns-anchor)=
### Remove columns
Remove the specified columns if present.
+If one of the specified columns is not in the file and the *ignore_missing*
+parameter is *false*, a `KeyError` is raised for missing column.
(parameters-for-remove-columns-anchor)=
@@ -93,75 +382,94 @@ Remove the specified columns if present.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_names | list of str | A list of columns to remove.|
+| remove_names | list of str | A list of columns to remove.|
+| ignore_missing | boolean | If true, missing columns are ignored, otherwise raise an error. |
```
-Example command:
+The following example command removes the columns *stop_signal_delay*,
+*response_accuracy*, and *face*.
+
+````{admonition} An example .
+:class: tip
+
```json
-{
- "column_names": ["sample", "ethn_target", "ethn_distractor"]
+{
+ "command": "remove_columns",
+ "description": "Remove columns before the next step.",
+ "parameters": {
+ "remove_names": ["stop_signal_delay", "response_accuracy", "face"],
+ "ignore_missing": true
+ }
}
```
+````
-```{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
+The results of executing this command on the
+[sample events file](sample-remodeling-events-file-anchor) are shown below.
+Although *face* is not the name of a column in the dataframe,
+it is ignored because *ignore_missing* is true.
+If *ignore_missing* had been false, a `KeyError` would have been generated.
+
+```{admonition} Results of *remove_column*.
+| onset | duration | trial_type | response_time | response_hand | sex |
+| ----- | -------- | ---------- | ------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | 0.565 | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.49 | right | female |
+| 9.5856 | 0.5084 | go | 0.45 | right | female |
+| 13.5939 | 0.5083 | succesful_stop | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.633 | left | male |
+| 21.6103 | 0.5083 | go | 0.443 | left | male |
````
+(remove-rows-anchor)=
### Remove rows
-Remove rows where specified columns take particular values.
+Remove rows in which the named column has one of the specified values.
(parameters-for-remove-rows-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
+```{admonition} Parameters for remove_rows.
:class: tip
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| column_name | str | The name of the column to be tested.|
+| remove_values | list | A list of values to be tested for removal. |
```
-The following example ....
+
+The following example command removes the rows whose *trial_type* column has either
+*succesful_stop* or *unsuccesful_stop*.
+
+````{admonition} Example remove_rows command.
+:class: tip
```json
-{
- "column_name": "match_side",
- "source_columns": ["response_accuracy", "response_hand"],
- "mapping": {
- "left": [["correct", "left"], ["incorrect", "right"]],
- "right": [["correct", "right"], ["incorrect", "left"]]
+{
+ "command": "remove_rows",
+ "description": "Remove rows where trial_type is either succesful_stop or unsuccesful_stop.",
+ "parameters": {
+ "column_name": "trial_type",
+ "remove_values": ["succesful_stop", "unsuccesful_stop"]
}
}
```
-Results in the following:
-
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
````
+The results of executing this command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} After removing rows with *trial_type* equal to *succesful_stop* or *unsuccesful_stop*.
+
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(rename-columns-anchor)=
### Rename columns
-Rename columns by providing old name and new name.
+Rename columns by providing a dictionary of old names to new names.
(parameters-for-rename-columns-anchor)=
```{admonition} Parameters for rename_columns.
@@ -170,40 +478,56 @@ Rename columns by providing old name and new name.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
| mapping | dict | The keys are the old column names and the values are the new names.|
-| ignore_missing | bool | If false, an error is thrown if any keys are missing. |
+| ignore_missing | bool | If false, a key error is raised if a dictionary key is not a column name . |
```
-The following example ....
+The command in the following example specifies that *response_hand* column be renamed *hand_used*
+and that the *sex* column be renamed *image_sex*.
+The *face* entry in the mapping will be ignored because *ignore_missing* is true.
+If *ignore_missing* is false, a `KeyError` exception is raised if a column specified in
+the mapping does not correspond to a column name in the dataframe.
+
+````{admonition} Example rename_columns command.
+:class: tip
```json
-{
- "mapping": {
- "face_type": "xxx",
- "hand": "response_hand"
- },
- "ignore_missing": true
+{
+ "command": "rename_columns",
+ "description": "Remove columns before splitting events.",
+ "parameters": {
+ "mapping": {
+ "face": "face_image",
+ "response_hand": "hand_used",
+ "sex": "image_sex"
+ },
+ "ignore_missing": true
+ }
}
```
-Results in the following:
-
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
````
+The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Renaming columns in staop
+| onset | duration | trial_type | stop_signal_delay | hand_used | response_accuracy | response_hand | image_sex |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(reorder-columns-anchor)=
### Reorder columns
-Reorder the columns in the specified order. Columns not included are discarded or placed at the end. If a specified column is not in the data --- do what?
+Reorder the columns in the specified order. If *ignore_missing* is true,
+the dataframe columns not included are discarded.
+On the other hand, if *ignore_missing* is false,
+column names that do not appear in the reorder list are moved to the end
+of the dataframe in the same order that they appear.
(parameters-for-reorder-columns-anchor)=
```{admonition} Parameters for reorder_columns.
@@ -211,42 +535,71 @@ Reorder the columns in the specified order. Columns not included are discarded o
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_names | list of str | A list of columns in the order they should appear in the data.|
-| keep_missing | boolean | If true, existing columns that aren't in column_names are moved to the end and in the same relative order that they originally appeared in the data. |
+| column_order | list | A list of columns in the order they should appear in the data.|
+| ignore_missing | boolean | If false, existing columns that aren't in column_names
are moved to the end and in the same relative
order that they originally appeared in the data. |
```
+The command in the following example specifies that the first four columns of the dataset
+should be: *onset*, *duration*, *trial_type*, *response_hand*, and *response_time*.
+Since *ignore_missing* is true, these will be the only columns retained.
+
+````{admonition} Example reorder_columns command.
+:class: tip
```json
-{
- "column_names": ["onset", "duration", "trial_type", "response_time"],
- "keep_missing": false
+{
+ "command": "reorder_columns",
+ "description": "Reorder columns.",
+ "parameters": {
+ "column_order": ["onset", "duration", "trial_type", "response_hand", "response_time"],
+ "ignore_missing": true
+ }
}
```
+````
+
-Results in the following:
+The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Event file from a simple Go/No-go experiment.
+````{admonition} Results of reorder_columns.
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
+| onset | duration | trial_type | response_hand | response_time |
+| ----- | -------- | ---------- | ------------- | ------------- |
+| 0.0776 | 0.5083 | go | right | 0.565 |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.49 |
+| 9.5856 | 0.5084 | go | right | 0.45 |
+| 13.5939 | 0.5083 | succesful_stop | n/a | n/a |
+| 17.1021 | 0.5083 | unsuccesful_stop | left | 0.633 |
+| 21.6103 | 0.5083 | go | left | 0.443 |
````
+(split-event-anchor)=
### Split event
-The split_event is the most complicated of the remodeling operations and generally
-Multiple information and responses are encoded in a single event. Split this event into multiple lines in the event file and adjust the meanings of the columns — usually this means removing the original event and replacing it with new events at various offsets.
-The final result has rows ordered by increasing offsets.
+The *split_event* is the most complicated of the remodeling operations and is often used to
+convert event files from using *trial-level* encoding to *event-level* encoding.
+In *trial-level* encoding each row of the event file represents all the events in a single trial
+(usually some variation of cue-stimulus-response-feedback-ready sequence).
+In *event-level* encoding, each row represents the marker for a single event.
+In this case a trial consists of a sequence of multiple events.
+
+The *split_event* command requires an *anchor_column*, which could be an existing
+column or a column that must be added to the dataframe.
+The purpose of the *anchor_column* is to hold the codes for the new events.
+
+The *new_events* dictionary has the new events to be created.
+The keys are the new event codes to be inserted into the *anchor_column*.
+The values in *new_events* are themselves dictionaries.
+Each of these dictionaries has three keys:
+
+- *onset_source*, a list specifying the items to be added to the *onset*
+of the event row being split. These items can be any combination of numerical values and column names.
+- *duration* a list of any combinations of numerical values and column names whose values are to be added
+to compute the duration.
+- *copy_columns* a list of column names whose values should be copied into the new events.
+Unlisted columns are filled with n/a.
-Rename columns by providing old name and new name.
(parameters-for-split-event-anchor)=
```{admonition} Parameters for split_event.
@@ -254,52 +607,67 @@ Rename columns by providing old name and new name.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column that will be used for split-event codes.|
-| split_dict | dict | Dictionary specifying how the split should occur. |
-|remove_parent_event | bool | If true, remove parent event. |
+| anchor_event | str | The name of the column that will be used for split-event codes.|
+| event_selection | dict | Dictionary which events should be split (currently ignored and all events are split). |
+| new_events | dict | Dictionary whose keys are the codes to be inserted as new events and whose values
+are dictionaries with keys onset_source, duration, and copy_columns. |
+| add_trial_numbers | boolean | If true, a column of trial numbers are added before the split. |
+| remove_parent_event | boolean | If true, remove parent event. |
```
-The `column_name` is the column that the split event codes are written.
-If this column does not exist in the `events.tsv` file it is added prior to the split processing.
+The command in the following example specifies that *response_hand* column be renamed *hand_used*
+and that the *sex* column be renamed *image_sex*.
+The *face* entry in the mapping will be ignored because *ignore_missing* is true.
+If *ignore_missing* is false, a `KeyError` exception is raised if a column specified in
+the mapping does not correspond to a column name in the dataframe.
-(parameters-for-split-dict-anchor)=
-```{admonition} values for split_dict.
+````{admonition} An example split_event command.
:class: tip
-| Parameter | Type | Description |
-| ------------ | ---- | ----------- |
-| onset_source | list | A list of column names and numbers representing values added to the onset of the parent event.|
-| split_dict | dict | Dictionary specifying how the split should occur. |
-|remove_parent_event | bool | If true, remove parent event. |
-
-```
-
-The
-The following example ....
-
```json
-{
- "mapping": {
- "face_type": "xxx",
- "hand": "response_hand"
- },
- "ignore_missing": true
+{
+ "command": "split_event",
+ "description": "Takes trial-level encoding and turns it into event-level encoding.",
+ "parameters": {
+ "anchor_column": "trial_type",
+ "event_selection": {},
+ "new_events": {
+ "response": {
+ "onset": ["response_time"],
+ "duration": [0],
+ "column_columns": ["response_accuracy", "response_hand", "sex"]
+ },
+ "stop_signal": {
+ "onset": ["stop_signal_delay"],
+ "duration": [0.5],
+ "column_columns": ["response_accuracy", "response_hand", "sex"]
+ }
+ },
+ "add_trial_numbers": true,
+ "remove_parent_event": false
+ }
}
-
```
-Results in the following:
-
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
````
+
+The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Results of the split_events command.
+| onset | duration | trial_type | response_accuracy | response_hand | sex | trial_number |
+| ----- | -------- | ---------- | ----------------- | ------------- | --- | ------------ |
+| 0.0776 | 0.5083 | go | correct | right | female | 1 |
+| 0.6426 | 0.0 | response | correct | right | female | 1 |
+| 5.5774 | 0.5083 | unsuccesful_stop | correct | right | female | 2 |
+| 5.7774 | 0.5 | stop_signal | correct | right | female | 2 |
+| 6.0674 | 0.0 | response | correct | right | female | 2 |
+| 9.5856 | 0.5084 | go | correct | right | female | 3 |
+| 10.0356 | 0.0 | response | correct | right | female | 3 |
+| 13.5939 | 0.5083 | succesful_stop | n/a | right | female | 4 |
+| 13.7939 | 0.5 | stop_signal | n/a | right | female | 4 |
+| 17.1021 | 0.5083 | unsuccesful_stop | correct | left | male | 5 |
+| 17.3521 | 0.5 | stop_signal | correct | left | male | 5 |
+| 17.7351 | 0.0 | response | correct | left | male | 5 |
+| 21.6103 | 0.5083 | go | correct | left | male | 6 |
+| 22.0533 | 0.0 | response | correct | left | male | 6 |
+````
\ No newline at end of file
diff --git a/docs/source/DesignMatricesWithHed.md b/docs/source/HedSearchAndSummary.md
similarity index 97%
rename from docs/source/DesignMatricesWithHed.md
rename to docs/source/HedSearchAndSummary.md
index 99471e0..889dee1 100644
--- a/docs/source/DesignMatricesWithHed.md
+++ b/docs/source/HedSearchAndSummary.md
@@ -1,6 +1,6 @@
-# Event restructuring
-
+# HED search and summary
+**Under construction**
This tutorial takes you through the steps of annotating the events
using HED (Hierarchical Event Descriptors).
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 52f1f37..5f95903 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -15,6 +15,15 @@ HED examples and tutorials
BidsAnnotationQuickstart.md
HedAnnotationQuickstart.md
HedValidation.md
+ HedSearchAndSummary.md
+ HedConditionsAndDesignMatrices.md
+ HedRemodelingTools.md
+
+
+.. toctree::
+ :maxdepth: 3
+ :caption: HED Tools:
+
TaggingWithCTagger.md
DataCuration101.md
HedToolsOnline.md
From dec9403290cc9dc6370023e634c3a7ecc1fbf5e3 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Sat, 23 Jul 2022 05:34:07 -0500
Subject: [PATCH 003/143] Worked on the documentation for event restructuring
---
docs/source/HedConditionsAndDesignMatrices.md | 168 -----------
docs/source/HedRemodelingTools.md | 261 +++++++++++-------
docs/source/HedSearchAndSummary.md | 167 -----------
3 files changed, 163 insertions(+), 433 deletions(-)
diff --git a/docs/source/HedConditionsAndDesignMatrices.md b/docs/source/HedConditionsAndDesignMatrices.md
index 61cec8f..a7566ac 100644
--- a/docs/source/HedConditionsAndDesignMatrices.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -1,171 +1,3 @@
# HED conditions and design matrices
**Under construction**
-
-This tutorial takes you through the steps of annotating the events
-using HED (Hierarchical Event Descriptors).
-The tutorial focuses on how to make good choices of HED annotations
-to make your data usable for downstream analysis.
-The mechanics of putting your selected HED annotations into
-[BIDS (Brain Imaging Data Structure)](https://bids.neuroimaging.io/) format
-is covered in the [**BIDS annotation quickstart**](./BidsAnnotationQuickstart.md) guide.
-
-* [**What is HED annotation?**](what-is-hed-annotation-anchor)
-* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
-
-(what-is-hed-annotation-anchor)=
-## What is HED annotation?
-
-A HED annotation consists of a comma separated list of tags selected from
-a HED vocabulary or schema.
-An important reason for using an agreed-upon vocabulary rather than
-free-form tagging for annotation is to avoid confusion and ambiguity
-and to promote data-sharing.
-
-The basic terms are organized into trees for easier access and search.
-The [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html) allows
-you to explore these terms.
-
-(a-recipe-for-simple-annotation-anchor)=
-## A recipe for simple annotation
-In thinking about how to annotate an event, you should always start
-by selecting a tag from the *Event* subtree to indicate the general event category.
-Possible choices are: *Sensory-event*, *Agent-action*, *Data-feature*, *Experiment-control*,
-*Experiment-procedure*, *Experiment-structure*, and *Measurement-event*.
-See the [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html)
-to view the available tags.
-
-Most experiments will only have a few types of distinct events.
-The simplest way to create a minimal HED annotation for your events is:
-
-1. Select one of the 7 tags from the *Event* subtree to designate the general category of the event.
-2. Use the following table to select the appropriate supporting tags given that event type.
-
-(standard-hed-tag-selections-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
-:class: tip
-
-| Event tag | Support tag type | Example tags | Reason |
-| ------------- | -------------------- | ------------ | ------ |
-| **Sensory-event** | *Sensory-presentation* | *Visual-presentation*
*Auditory-presentation*| Which sense? |
-| | *Task-event-role* | *Experimental-stimulus*
*Instructional* | What task role? |
-| | *Task-stimulus-role* | *Cue*
*Target* | Stimulus purpose? |
-| | *Item* | *(Face, Image)*
*Siren* | What is presented? |
-| | *Sensory-attribute* | *Red* | What modifiers are needed? |
-| **Agent-action** | *Agent-task-role* | *Experiment-participant* | Who is agent? |
-| | *Action* | *Move*
*Press* | What action is performed? |
-| | *Task-action-type* | *Appropriate-action*
*Near-miss* | What task relationship? |
-| | *Item* | *Arm*
*Mouse-button* | What is action target? |
-| **Data-feature** | *Data-source-type* | *Expert-annotation*
*Computed-feature* | Where did the feature come from? |
-| | *Label* | *Label/Blinker_BlinkMax* | Tool name?
Feature type? |
-| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | Feature value or type? |
-| **Experiment-control** | *Agent* | *Controller-Agent* | What is the controller? |
-| | *Informational* | *Label/Stop-recording* | What did the controller do? |
-| **Experiment-procedure** | *Task-event-role* | *Task-activity* | What procedure? |
-| **Experiment-structure** | *Organizational-property* | *Time-block*
*Condition-variable* | What structural property? |
-| **Measurement-event** | *Data-source-type* | *Instrument-measurement*
*Observation* | Source of the data. |
-| | *Label* | *Label/Oximeter_O2Level* | Instrument name?
Measurement type? |
-| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | What value or type?
-```
-
-
-As in BIDS, we assume that the event metadata is given in tabular form.
-Each table row represents the metadata associated with a single data event marker,
-as shown in the following excerpt of the `events.tsv` file for a simple Go/No-go experiment.
-The `onset` column gives the time in seconds of the marker relative
-to the beginning of the associated data file.
-
-(example-go-no-go-event-table-anchor)=
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
-````
-
-In the Go/No-go experiment, the experimental participant is presented
-with a series of target and distractor animal images.
-The participant is instructed to lift a finger off a button
-when a target animal image appears.
-Since in this experiment, the `value` column has distinct values
-for all possible unique event types, the `event_type` column is redundant.
-In this case, we can choose to assign all the annotations to
-the `value` column as demonstrated in the following example.
-
-````{admonition} Version 1: Assigning all annotations to the value column.
-
-| value | Event category | Supporting tags |
-| ------- | -------------- | --------------- |
-| animal_target | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
-| animal_distractor | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Non-target*, *Distractor*, (*Animal*, *Image*) |
-| correct_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Correct-action* |
-| incorrect_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Incorrect-action* |
-
-````
-
-The table above shows the event category and the supporting tags as suggested in the
-[**Standard hed tags for minimal annotation**](standard-hed-tag-selections-anchor) table.
-
-A better format for your annotations is the
-[**4-column spreadsheet format**](four-column-spreadsheet-format-anchor) described in
-[**BIDS annotation quickstart**](BidsAnnotationQuickstart.md), since there are online
-tools to convert this format into a JSON sidecar that can be deployed directly in
-a BIDS dataset.
-
-````{admonition} 4-column spreadsheet format for the previous example.
-
-| column_name| column_value | description | HED |
-| ------- | -------------- | ----------- | ------- |
-| value | animal_target | An target animal image was
presented on a screen. |*Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
-| value | animal_distractor | A non-target animal distractor
image was presented
on a screen. | *Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*, *Non-target*,
*Distractor*, (*Animal*, *Image*)|
-| value | correct_response | Participant correctly
lifted finger off button. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Correct-action* |
-| value | incorrect_response | Participant lifted finger off
the button but should not have. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Incorrect-action* |
-
-````
-
-HED tools assemble the annotations for each event into a single HED tag string.
-An exactly equivalent version of the previous example splits the HED tag annotation between
-the `event_type` and `value` columns as shown in the next example.
-
-````{admonition} Version 2: Assigning annotations to multiple event file columns.
-
-| column_name | column_value | description | HED |
-| ------- | -------------- | --------------- | ------ |
-| event_type | stimulus | An image of an animal
was presented on a
computer screen.| *Sensory-event*,
*Visual-presentation*,
*experimental-stimulus* |
-| event_type | response | Participant lifted finger
off button.| *Agent-action*,
*Experiment-participant*,
(*Lift*, *Finger*) |
-| value | animal_target | A target animal image. | *Target*, (*Animal*, *Image*) |
-| value | animal_distractor | A non-target animal image
meant as a distractor. | *Non-target*, *Distractor*,
(*Animal*, *Image*) |
-| value | correct_response | The previous stimulus
was a target animal. | *Correct-action* |
-| value | incorrect_response | The previous stimulus
was not a target animal. | *Incorrect-action* |
-| stim_file | n/a | Filename of stimulus image. | (*Image*, *Pathname/#*) |
-````
-In version 2, the annotations that are common
-to all stimuli and responses are assigned to `event_type`.
-We have also included the annotation for the `stim_file` column in the last row
-of this table.
-
-The assembled annotation for the first event (with onset 5.035) in the
-[**event file excerpt from go/no-go**](example-go-no-go-event-table-anchor) above is:
-
-> *Sensory-event*, *Visual-presentation*, *Experimental-stimulus*, *Target*, (*Animal*, *Image*), (*Image*, *Pathname/105064.jpg*)
-
-Mapping annotations and column information across multiple column values often makes
-the annotation process simpler, especially when annotations become more complex.
-Multiple column representation also can make analysis easier,
-particularly if the columns represent information such as design variables.
-
-See [**BIDS annotation quick start**](BidsAnnotationQuickstart.md#bids-annotation-quickstart) for how to
-create templates to fill in with your annotations using online tools.
-Once you have completed the annotation and converted it to a sidecar,
-you simply need to place this sidecar in the root directory of your BIDS dataset.
-
-This quick start demonstrates the most basic HED annotations.
-HED is capable of much more extensive and expressive annotations as
-explained in a series of tutorials on this site.
\ No newline at end of file
diff --git a/docs/source/HedRemodelingTools.md b/docs/source/HedRemodelingTools.md
index 496c7f7..975166e 100644
--- a/docs/source/HedRemodelingTools.md
+++ b/docs/source/HedRemodelingTools.md
@@ -7,9 +7,10 @@ This tutorial works through the process of restructuring event files using the H
* [**What is restructuring?**](what-is-event-file-restructuring-anchor)
* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor)
* [**Running remodeling tools**](running-remodeling-tools-anchor)
-* [**Remodeling operations**](remodeling-operations-anchor)
- * [**Add structure**](add-structure-anchor) Docs not written
- * [**Add trial numbers**](add-trial-numbers-anchor) Docs not written
+* [**Remodeling operations**](remodeling-operations-anchor)
+ * [**Add structure column**](add-structure-column-anchor) Docs not written
+ * [**Add structure events**](add-structure-events-anchor) Docs not written
+ * [**Add structure numbers**](add-structure-numbers-anchor) Docs not written
* [**Derive column**](derive-column-anchor) Docs not written
* [**Factor column**](factor-column-anchor) Docs not written
* [**Factor HED**](factor-column-anchor) Docs not written
@@ -43,6 +44,57 @@ stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneu
(sample-remodeling-events-file-anchor)=
````{admonition} Excerpt from event file for a stop-go task.
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(add-structure-column-anchor)=
+### Add structure column
+
+**NOT WRITTEN - PLACEHOLDER**
+
+Add a column of numbers corresponding to a structure elements such as trials or blocks.
+
+(parameters-for-add-structure-column-anchor)=
+```{admonition} Parameters for the *add_structure_column* command.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list | Names of the columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+
+The *add_structure_column* command in the following example specifies . . .
+
+
+````{admonition} An example *add_structure_column* command.
+:class: tip
+
+```json
+{
+ "column_name": "add_structure_column",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+}
+```
+````
+
+The results of executing this *add_structure_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+
+````{admonition} Results of the previous *add_structure_column* command.
+
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
@@ -53,15 +105,15 @@ stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneu
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
-(add-structure-anchor)=
-### Add structure
+(add-structure-events-anchor)=
+### Add structure events
**NOT WRITTEN - PLACEHOLDER**
-Use: Add trial or block markers --- used for epoching around the start of a trial. The duration is the duration of the trial or block respectively.
+Add events representing the start of a structural element such as a trial or a block.
-(parameters-for-add-structure-anchor)=
-```{admonition} Parameters for the *add_structure* command.
+(parameters-for-add-structure-event-anchor)=
+```{admonition} Parameters for the *add_structure_events* command.
:class: tip
| Parameter | Type | Description |
@@ -71,14 +123,14 @@ Use: Add trial or block markers --- used for epoching around the start of a tria
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The following example ....
+The *add_structure_events* command in the following example specifies . . .
-````{admonition} Parameters for the *add_structure* command.
+````{admonition} An example *add_structure_events* command.
:class: tip
```json
{
- "column_name": "match_side",
+ "column_name": "add_structure_events",
"source_columns": ["response_accuracy", "response_hand"],
"mapping": {
"left": [["correct", "left"], ["incorrect", "right"]],
@@ -88,9 +140,10 @@ The following example ....
```
````
-The results of executing the *add_structure* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *add_structure_events* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
-````{admonition} Stop-go event file XXX.
+````{admonition} Results of the previous *add_structure_events* command.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -102,15 +155,17 @@ The results of executing the *add_structure* command on the [sample events file]
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
-(add-trial-numbers-anchor)=
-### Add trial numbers
+(add-structure-numbers-anchor)=
+### Add structure numbers
**NOT WRITTEN - PLACEHOLDER**
-Add a column with the trial numbers.
+Add a column with numbers corresponding to a structural element.
-(parameters-for-add-trial-numbers-anchor)=
-```{admonition} Parameters for the *add_trial_numbers* command.
+**TODO** clarify the difference between add_structure_numbers and add_structure_column.
+
+(parameters-for-add-structure-numbers-anchor)=
+```{admonition} Parameters for the *add_structure_numbers* command.
:class: tip
| Parameter | Type | Description |
@@ -119,14 +174,14 @@ Add a column with the trial numbers.
| source_columns | list of str | A list of columns to be used for remapping. |
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The following example ....
+The *add_structure_numbers* command in the following example specifies . . .
````{admonition} An example .
:class: tip
```json
{
- "command": "add_trial_numbers"
+ "command": "add_structure_numbers"
"description": "xxx"
"parameters": {
"column_name": "match_side",
@@ -140,9 +195,10 @@ The following example ....
```
````
-The results of executing this command on the [**sample events file**](sample-remodeling-events-file-anchor) are:
+The results of executing this *add_structure_numbers* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
-````{admonition} Results of adding trial numbers to the file.
+````{admonition} Results of executing the previous *add_structure_numbers* command.
| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -165,7 +221,7 @@ based on predefined combinations of values in other columns.
(parameters-for-derive-column-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
+```{admonition} Parameters for the *derive_column* command.
:class: tip
| Parameter | Type | Description |
@@ -174,16 +230,14 @@ based on predefined combinations of values in other columns.
| source_columns | list of str | A list of columns to be used for remapping. |
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The following example creates a *match_side column* with values *left* and *right*
-based on particular combinations of values in the *response_accuracy* and
-*response_hand* columns.
+The *derive_column* command in the following example specifies . . .
-````{admonition} Create a *match_side* column with values *left* and *right*.
+````{admonition} An example *derive_column* command.
:class: tip
```json
{
- "command": "add_trial_numbers"
+ "command": "derive_column"
"description": "xxx"
"parameters": {
"column_name": "match_side",
@@ -197,7 +251,7 @@ based on particular combinations of values in the *response_accuracy* and
```
````
-The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *derive_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
````{admonition} Adding a *match_side* column using the *derive_column* command.
@@ -214,53 +268,60 @@ The results of executing this command on the [sample events file](sample-remodel
(factor-column-anchor)=
### Factor column
-**NOT WRITTEN - PLACEHOLDER**
-
-Factor each of the specified values in the indicated column into a column containing 1’s and 0’s indicating presence and absence. If no values are specified, all unique values in that column are factored.
+For each of the specified values in the indicated column create a column containing 1’s and 0’s
+indicating presence or absence of the value.
+If no values are specified, all unique values in that column are factored.
(parameters-for-factor-column-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
+```{admonition} Parameters for the *factor_column* command.
:class: tip
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| column_name | str | The name of the column to be factored.|
+| factor_values | list | A list of column values to be included as factors. |
+| factor_names | list| A list of column names for created factors
of the same length as factor_values. |
+| overwrite_existing| bool | If true an existing factor column is overwritten. |
```
-The following example ....
+The *factor_column* command in the following example specifies that factor columns
+should be created for *succesful_stop* and *unsuccesful_stop* of the *trial_type* column.
+The resulting columns are called *stopped* and *stop_failed*, respectively.
+If the *factor_values* is an empty list,
+factors are created for all unique values in the *column_name* column.
+The *factor_names* parameters must be the same length as *factor_values*.
+If *factor_names* is empty, the newly created columns are of the
+form *column_name.factor_value*.
-````{admonition} Create XXXX.
+
+````{admonition} A sample *factor_column* command.
:class: tip
```json
{
"command": "factor_column"
- "description": "xxx"
+ "description": "Create factors for the succesful_stop and unsuccesful_stop values."
"parameters": {
- "column_name": "match_side",
- "source_columns": ["response_accuracy", "response_hand"],
- "mapping": {
- "left": [["correct", "left"], ["incorrect", "right"]],
- "right": [["correct", "right"], ["incorrect", "left"]]
- }
+ "column_name": "trial_type",
+ "factor_values": ["succesful_stop", "unsuccesful_stop"],
+ "factor_names": ["stopped", "stop_failed"],
+ "overwrite_existing": true
}
}
```
````
-The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *factor_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
````{admonition} Results of factoring column XXX.
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
-| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
-| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex | stopped | stop_failed |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ---------- | ---------- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female | 0 | 0 |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female | 0 | 1 |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 0 | 0|
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female | 1 | 0 |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | 0 | 1 |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | 0 | 0 |
````
(factor-hed-anchor)=
@@ -271,7 +332,7 @@ The results of executing this command on the [sample events file](sample-remodel
Produce a list of factor columns based on the specified HED condition-variable values.
(parameters-for-factor-hed-anchor)=
-```{admonition} Parameters for factor_hed.
+```{admonition} Parameters for *factor_hed* command.
:class: tip
| Parameter | Type | Description |
@@ -281,9 +342,9 @@ Produce a list of factor columns based on the specified HED condition-variable v
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The following example ....
+The *factor_hed* command in the following example specifies . . .
-````{admonition} Create XXXX.
+````{admonition} Example *factor_hed* command.
:class: tip
```json
@@ -302,7 +363,7 @@ The following example ....
```
````
-The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *factor_hed* command on the [sample events file](sample-remodeling-events-file-anchor) are:
````{admonition} Results of *factor_hed*.
@@ -324,7 +385,7 @@ The results of executing this command on the [sample events file](sample-remodel
One long event is represented by multiple repeat events. Merges these same events occurring consecutively into one event with duration of the new event updated as the sum of all merged events.
(parameters-for-merge-events-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
+```{admonition} Parameters for the *merge_events* command.
:class: tip
| Parameter | Type | Description |
@@ -333,9 +394,10 @@ One long event is represented by multiple repeat events. Merges these same event
| source_columns | list of str | A list of columns to be used for remapping. |
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The following example ....
-````{admonition} Merge events.
+The *merge_events* command in the following example specifies . . .
+
+````{admonition} A sample *merge_events* command.
:class: tip
```json
@@ -354,7 +416,7 @@ The following example ....
```
````
-The results of executing the example *merge_events* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *merge_events* command on the [sample events file](sample-remodeling-events-file-anchor) are:
````{admonition} The results of the *merge_events* command.
@@ -377,7 +439,7 @@ parameter is *false*, a `KeyError` is raised for missing column.
(parameters-for-remove-columns-anchor)=
-```{admonition} Parameters for the remove_columns operation.
+```{admonition} Parameters for the *remove_columns* operation.
:class: tip
| Parameter | Type | Description |
@@ -386,10 +448,10 @@ parameter is *false*, a `KeyError` is raised for missing column.
| ignore_missing | boolean | If true, missing columns are ignored, otherwise raise an error. |
```
-The following example command removes the columns *stop_signal_delay*,
-*response_accuracy*, and *face*.
+The *remove_column* command in the following example removes the *stop_signal_delay*,
+*response_accuracy*, and *face* columns.
-````{admonition} An example .
+````{admonition} An example *remove_column* command.
:class: tip
```json
@@ -410,7 +472,7 @@ Although *face* is not the name of a column in the dataframe,
it is ignored because *ignore_missing* is true.
If *ignore_missing* had been false, a `KeyError` would have been generated.
-```{admonition} Results of *remove_column*.
+```{admonition} Results of executing the *remove_column*.
| onset | duration | trial_type | response_time | response_hand | sex |
| ----- | -------- | ---------- | ------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | 0.565 | right | female |
@@ -436,10 +498,10 @@ Remove rows in which the named column has one of the specified values.
| remove_values | list | A list of values to be tested for removal. |
```
-The following example command removes the rows whose *trial_type* column has either
-*succesful_stop* or *unsuccesful_stop*.
+The following example *remove_rows* command removes the rows whose *trial_type* column
+has either *succesful_stop* or *unsuccesful_stop*.
-````{admonition} Example remove_rows command.
+````{admonition} Sample remove_rows command.
:class: tip
```json
@@ -454,10 +516,10 @@ The following example command removes the rows whose *trial_type* column has eit
```
````
-The results of executing this command on the
+The results of executing the previous *remove_rows* command on the
[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} After removing rows with *trial_type* equal to *succesful_stop* or *unsuccesful_stop*.
+````{admonition} The results of executing the previous *remove_rows* command.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -466,28 +528,31 @@ The results of executing this command on the
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
+After removing rows with *trial_type* equal to *succesful_stop* or *unsuccesful_stop* only the
+three *go* trials remain.
+
(rename-columns-anchor)=
### Rename columns
Rename columns by providing a dictionary of old names to new names.
(parameters-for-rename-columns-anchor)=
-```{admonition} Parameters for rename_columns.
+```{admonition} Parameters for *rename_columns*.
:class: tip
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| mapping | dict | The keys are the old column names and the values are the new names.|
+| column_mapping | dict | The keys are the old column names and the values are the new names.|
| ignore_missing | bool | If false, a key error is raised if a dictionary key is not a column name . |
```
-The command in the following example specifies that *response_hand* column be renamed *hand_used*
-and that the *sex* column be renamed *image_sex*.
+The *rename_columns* command in the following example specifies that *response_hand* column be
+renamed *hand_used* and that the *sex* column be renamed *image_sex*.
The *face* entry in the mapping will be ignored because *ignore_missing* is true.
If *ignore_missing* is false, a `KeyError` exception is raised if a column specified in
the mapping does not correspond to a column name in the dataframe.
-````{admonition} Example rename_columns command.
+````{admonition} Example *rename_columns* command.
:class: tip
```json
@@ -495,8 +560,9 @@ the mapping does not correspond to a column name in the dataframe.
"command": "rename_columns",
"description": "Remove columns before splitting events.",
"parameters": {
- "mapping": {
- "face": "face_image",
+ "column_mapping": {
+ "random_column": "new_random_column",
+ "stop_signal_delay": "stop_delay",
"response_hand": "hand_used",
"sex": "image_sex"
},
@@ -507,15 +573,15 @@ the mapping does not correspond to a column name in the dataframe.
```
````
-The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *rename_columns* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Renaming columns in staop
-| onset | duration | trial_type | stop_signal_delay | hand_used | response_accuracy | response_hand | image_sex |
+````{admonition} After the *rename_columns* command is executed, the sample events file is:
+| onset | duration | trial_type | stop_delay | response_time | response_accuracy | hand_used | image_sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
@@ -530,7 +596,7 @@ column names that do not appear in the reorder list are moved to the end
of the dataframe in the same order that they appear.
(parameters-for-reorder-columns-anchor)=
-```{admonition} Parameters for reorder_columns.
+```{admonition} Parameters for *reorder_columns*.
:class: tip
| Parameter | Type | Description |
@@ -540,11 +606,11 @@ of the dataframe in the same order that they appear.
```
-The command in the following example specifies that the first four columns of the dataset
-should be: *onset*, *duration*, *trial_type*, *response_hand*, and *response_time*.
+The *reorder_columns* command in the following example specifies that the first four
+columns of the dataset should be: *onset*, *duration*, *trial_type*, *response_hand*, and *response_time*.
Since *ignore_missing* is true, these will be the only columns retained.
-````{admonition} Example reorder_columns command.
+````{admonition} Example *reorder_columns* command.
:class: tip
```json
@@ -560,9 +626,9 @@ Since *ignore_missing* is true, these will be the only columns retained.
````
-The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *reorder_columns* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of reorder_columns.
+````{admonition} Results of *reorder_columns*.
| onset | duration | trial_type | response_hand | response_time |
| ----- | -------- | ---------- | ------------- | ------------- |
@@ -609,15 +675,14 @@ Unlisted columns are filled with n/a.
| ------------ | ---- | ----------- |
| anchor_event | str | The name of the column that will be used for split-event codes.|
| event_selection | dict | Dictionary which events should be split (currently ignored and all events are split). |
-| new_events | dict | Dictionary whose keys are the codes to be inserted as new events and whose values
-are dictionaries with keys onset_source, duration, and copy_columns. |
-| add_trial_numbers | boolean | If true, a column of trial numbers are added before the split. |
+| new_events | dict | Dictionary whose keys are the codes to be inserted as new events and whose values are dictionaries with keys *onset_source*, *duration*, and *copy_columns*. |
+| add_event_numbers | boolean | If true, a column of event numbers are added before the split. |
| remove_parent_event | boolean | If true, remove parent event. |
```
-The command in the following example specifies that *response_hand* column be renamed *hand_used*
-and that the *sex* column be renamed *image_sex*.
+The *split_event* command in the following example specifies that *response_hand*
+column be renamed *hand_used* and that the *sex* column be renamed *image_sex*.
The *face* entry in the mapping will be ignored because *ignore_missing* is true.
If *ignore_missing* is false, a `KeyError` exception is raised if a column specified in
the mapping does not correspond to a column name in the dataframe.
@@ -644,16 +709,16 @@ the mapping does not correspond to a column name in the dataframe.
"column_columns": ["response_accuracy", "response_hand", "sex"]
}
},
- "add_trial_numbers": true,
+ "add_event_numbers": true,
"remove_parent_event": false
}
}
```
````
-The results of executing this command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *split_event* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of the split_events command.
+````{admonition} Results of the split_event command.
| onset | duration | trial_type | response_accuracy | response_hand | sex | trial_number |
| ----- | -------- | ---------- | ----------------- | ------------- | --- | ------------ |
| 0.0776 | 0.5083 | go | correct | right | female | 1 |
@@ -663,7 +728,7 @@ The results of executing this command on the [sample events file](sample-remodel
| 6.0674 | 0.0 | response | correct | right | female | 2 |
| 9.5856 | 0.5084 | go | correct | right | female | 3 |
| 10.0356 | 0.0 | response | correct | right | female | 3 |
-| 13.5939 | 0.5083 | succesful_stop | n/a | right | female | 4 |
+| 13.5939 | 0.5083 | succesful_stop | n/a | n/a | female | 4 |
| 13.7939 | 0.5 | stop_signal | n/a | right | female | 4 |
| 17.1021 | 0.5083 | unsuccesful_stop | correct | left | male | 5 |
| 17.3521 | 0.5 | stop_signal | correct | left | male | 5 |
diff --git a/docs/source/HedSearchAndSummary.md b/docs/source/HedSearchAndSummary.md
index 889dee1..543b429 100644
--- a/docs/source/HedSearchAndSummary.md
+++ b/docs/source/HedSearchAndSummary.md
@@ -2,170 +2,3 @@
**Under construction**
-This tutorial takes you through the steps of annotating the events
-using HED (Hierarchical Event Descriptors).
-The tutorial focuses on how to make good choices of HED annotations
-to make your data usable for downstream analysis.
-The mechanics of putting your selected HED annotations into
-[BIDS (Brain Imaging Data Structure)](https://bids.neuroimaging.io/) format
-is covered in the [**BIDS annotation quickstart**](./BidsAnnotationQuickstart.md) guide.
-
-* [**What is HED annotation?**](what-is-hed-annotation-anchor)
-* [**A recipe for simple annotation**](a-recipe-for-simple-annotation-anchor)
-
-(what-is-hed-annotation-anchor)=
-## What is HED annotation?
-
-A HED annotation consists of a comma separated list of tags selected from
-a HED vocabulary or schema.
-An important reason for using an agreed-upon vocabulary rather than
-free-form tagging for annotation is to avoid confusion and ambiguity
-and to promote data-sharing.
-
-The basic terms are organized into trees for easier access and search.
-The [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html) allows
-you to explore these terms.
-
-(a-recipe-for-simple-annotation-anchor)=
-## A recipe for simple annotation
-In thinking about how to annotate an event, you should always start
-by selecting a tag from the *Event* subtree to indicate the general event category.
-Possible choices are: *Sensory-event*, *Agent-action*, *Data-feature*, *Experiment-control*,
-*Experiment-procedure*, *Experiment-structure*, and *Measurement-event*.
-See the [**Expandable HED vocabulary viewer**](https://www.hedtags.org/display_hed.html)
-to view the available tags.
-
-Most experiments will only have a few types of distinct events.
-The simplest way to create a minimal HED annotation for your events is:
-
-1. Select one of the 7 tags from the *Event* subtree to designate the general category of the event.
-2. Use the following table to select the appropriate supporting tags given that event type.
-
-(standard-hed-tag-selections-anchor)=
-```{admonition} Standard HED tag selections for minimal annotation.
-:class: tip
-
-| Event tag | Support tag type | Example tags | Reason |
-| ------------- | -------------------- | ------------ | ------ |
-| **Sensory-event** | *Sensory-presentation* | *Visual-presentation*
*Auditory-presentation*| Which sense? |
-| | *Task-event-role* | *Experimental-stimulus*
*Instructional* | What task role? |
-| | *Task-stimulus-role* | *Cue*
*Target* | Stimulus purpose? |
-| | *Item* | *(Face, Image)*
*Siren* | What is presented? |
-| | *Sensory-attribute* | *Red* | What modifiers are needed? |
-| **Agent-action** | *Agent-task-role* | *Experiment-participant* | Who is agent? |
-| | *Action* | *Move*
*Press* | What action is performed? |
-| | *Task-action-type* | *Appropriate-action*
*Near-miss* | What task relationship? |
-| | *Item* | *Arm*
*Mouse-button* | What is action target? |
-| **Data-feature** | *Data-source-type* | *Expert-annotation*
*Computed-feature* | Where did the feature come from? |
-| | *Label* | *Label/Blinker_BlinkMax* | Tool name?
Feature type? |
-| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | Feature value or type? |
-| **Experiment-control** | *Agent* | *Controller-Agent* | What is the controller? |
-| | *Informational* | *Label/Stop-recording* | What did the controller do? |
-| **Experiment-procedure** | *Task-event-role* | *Task-activity* | What procedure? |
-| **Experiment-structure** | *Organizational-property* | *Time-block*
*Condition-variable* | What structural property? |
-| **Measurement-event** | *Data-source-type* | *Instrument-measurement*
*Observation* | Source of the data. |
-| | *Label* | *Label/Oximeter_O2Level* | Instrument name?
Measurement type? |
-| | *Data-value* | *Percentage/32.5*
*Time-interval/1.5 s* | What value or type?
-```
-
-
-As in BIDS, we assume that the event metadata is given in tabular form.
-Each table row represents the metadata associated with a single data event marker,
-as shown in the following excerpt of the `events.tsv` file for a simple Go/No-go experiment.
-The `onset` column gives the time in seconds of the marker relative
-to the beginning of the associated data file.
-
-(example-go-no-go-event-table-anchor)=
-````{admonition} Event file from a simple Go/No-go experiment.
-
-| onset | duration | event_type | value | stim_file |
-| ----- | -------- | ---------- | ----- | --------- |
-| 5.035 | n/a | stimulus | animal_target | 105064.jpg |
-| 5.370 | n/a | response | correct_response | n/a |
-| 6.837 | n/a | stimulus | animal_distractor | 38068.jpg |
-| 8.651 | n/a | stimulus | animal_target | 136095.jpg |
-| 8.940 | n/a | response | correct_response | n/a |
-| 10.801 | n/a | stimulus | animal_distractor | 38014.jpg |
-| 12.684 | n/a | stimulus | animal_distractor | 82063.jpg |
-| 12.943 | n/a | response | incorrect_response | n/a |
-````
-
-In the Go/No-go experiment, the experimental participant is presented
-with a series of target and distractor animal images.
-The participant is instructed to lift a finger off a button
-when a target animal image appears.
-Since in this experiment, the `value` column has distinct values
-for all possible unique event types, the `event_type` column is redundant.
-In this case, we can choose to assign all the annotations to
-the `value` column as demonstrated in the following example.
-
-````{admonition} Version 1: Assigning all annotations to the value column.
-
-| value | Event category | Supporting tags |
-| ------- | -------------- | --------------- |
-| animal_target | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
-| animal_distractor | *Sensory-event* | *Visual-presentation*, *Experimental-stimulus*,
*Non-target*, *Distractor*, (*Animal*, *Image*) |
-| correct_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Correct-action* |
-| incorrect_response | *Agent-action* | *Experiment-participant*, (*Lift*, *Finger*), *Incorrect-action* |
-
-````
-
-The table above shows the event category and the supporting tags as suggested in the
-[**Standard hed tags for minimal annotation**](standard-hed-tag-selections-anchor) table.
-
-A better format for your annotations is the
-[**4-column spreadsheet format**](four-column-spreadsheet-format-anchor) described in
-[**BIDS annotation quickstart**](BidsAnnotationQuickstart.md), since there are online
-tools to convert this format into a JSON sidecar that can be deployed directly in
-a BIDS dataset.
-
-````{admonition} 4-column spreadsheet format for the previous example.
-
-| column_name| column_value | description | HED |
-| ------- | -------------- | ----------- | ------- |
-| value | animal_target | An target animal image was
presented on a screen. |*Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*,
*Target*, (*Animal*, *Image*) |
-| value | animal_distractor | A non-target animal distractor
image was presented
on a screen. | *Sensory-event*, *Visual-presentation*,
*Experimental-stimulus*, *Non-target*,
*Distractor*, (*Animal*, *Image*)|
-| value | correct_response | Participant correctly
lifted finger off button. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Correct-action* |
-| value | incorrect_response | Participant lifted finger off
the button but should not have. | *Agent-action*, *Experiment-participant*,
(*Lift*, *Finger*), *Incorrect-action* |
-
-````
-
-HED tools assemble the annotations for each event into a single HED tag string.
-An exactly equivalent version of the previous example splits the HED tag annotation between
-the `event_type` and `value` columns as shown in the next example.
-
-````{admonition} Version 2: Assigning annotations to multiple event file columns.
-
-| column_name | column_value | description | HED |
-| ------- | -------------- | --------------- | ------ |
-| event_type | stimulus | An image of an animal
was presented on a
computer screen.| *Sensory-event*,
*Visual-presentation*,
*experimental-stimulus* |
-| event_type | response | Participant lifted finger
off button.| *Agent-action*,
*Experiment-participant*,
(*Lift*, *Finger*) |
-| value | animal_target | A target animal image. | *Target*, (*Animal*, *Image*) |
-| value | animal_distractor | A non-target animal image
meant as a distractor. | *Non-target*, *Distractor*,
(*Animal*, *Image*) |
-| value | correct_response | The previous stimulus
was a target animal. | *Correct-action* |
-| value | incorrect_response | The previous stimulus
was not a target animal. | *Incorrect-action* |
-| stim_file | n/a | Filename of stimulus image. | (*Image*, *Pathname/#*) |
-````
-In version 2, the annotations that are common
-to all stimuli and responses are assigned to `event_type`.
-We have also included the annotation for the `stim_file` column in the last row
-of this table.
-
-The assembled annotation for the first event (with onset 5.035) in the
-[**event file excerpt from go/no-go**](example-go-no-go-event-table-anchor) above is:
-
-> *Sensory-event*, *Visual-presentation*, *Experimental-stimulus*, *Target*, (*Animal*, *Image*), (*Image*, *Pathname/105064.jpg*)
-
-Mapping annotations and column information across multiple column values often makes
-the annotation process simpler, especially when annotations become more complex.
-Multiple column representation also can make analysis easier,
-particularly if the columns represent information such as design variables.
-
-See [**BIDS annotation quick start**](BidsAnnotationQuickstart.md#bids-annotation-quickstart) for how to
-create templates to fill in with your annotations using online tools.
-Once you have completed the annotation and converted it to a sidecar,
-you simply need to place this sidecar in the root directory of your BIDS dataset.
-
-This quick start demonstrates the most basic HED annotations.
-HED is capable of much more extensive and expressive annotations as
-explained in a series of tutorials on this site.
\ No newline at end of file
From d99a198b07144e2175fb5103146abbee7c890f3a Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Mon, 25 Jul 2022 09:52:11 -0500
Subject: [PATCH 004/143] Continuing to correct event restructuring examples
---
docs/source/HedRemodelingTools.md | 23 +++++++++++++----------
1 file changed, 13 insertions(+), 10 deletions(-)
diff --git a/docs/source/HedRemodelingTools.md b/docs/source/HedRemodelingTools.md
index 975166e..ea3294b 100644
--- a/docs/source/HedRemodelingTools.md
+++ b/docs/source/HedRemodelingTools.md
@@ -281,6 +281,7 @@ If no values are specified, all unique values in that column are factored.
| column_name | str | The name of the column to be factored.|
| factor_values | list | A list of column values to be included as factors. |
| factor_names | list| A list of column names for created factors
of the same length as factor_values. |
+| ignore_missing| bool | If true, columns corresponding to factor values
that do not appear in column are included. |
| overwrite_existing| bool | If true an existing factor column is overwritten. |
```
The *factor_column* command in the following example specifies that factor columns
@@ -304,6 +305,7 @@ form *column_name.factor_value*.
"column_name": "trial_type",
"factor_values": ["succesful_stop", "unsuccesful_stop"],
"factor_names": ["stopped", "stop_failed"],
+ "ignore_missing": false,
"overwrite_existing": true
}
}
@@ -314,12 +316,12 @@ The results of executing this *factor_column* command on the [sample events file
````{admonition} Results of factoring column XXX.
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex | stopped | stop_failed |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ---------- | ---------- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female | 0 | 0 |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female | 0 | 1 |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 0 | 0|
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female | 1 | 0 |
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | stopped | stop_failed |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ---------- | ---------- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | 0 | 0 |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | 0 | 1 |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 0 | 0 |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | 1 | 0 |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | 0 | 1 |
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | 0 | 0 |
````
@@ -448,10 +450,11 @@ parameter is *false*, a `KeyError` is raised for missing column.
| ignore_missing | boolean | If true, missing columns are ignored, otherwise raise an error. |
```
-The *remove_column* command in the following example removes the *stop_signal_delay*,
-*response_accuracy*, and *face* columns.
+The *remove_column* command in the following example removes the *stop_signal_delay* and
+*response_accuracy* columns. The *face* column is not in the dataframe, but it is ignored,
+since *ignore_missing* is True.
-````{admonition} An example *remove_column* command.
+````{admonition} An example *remove_columns* command.
:class: tip
```json
@@ -478,7 +481,7 @@ If *ignore_missing* had been false, a `KeyError` would have been generated.
| 0.0776 | 0.5083 | go | 0.565 | right | female |
| 5.5774 | 0.5083 | unsuccesful_stop | 0.49 | right | female |
| 9.5856 | 0.5084 | go | 0.45 | right | female |
-| 13.5939 | 0.5083 | succesful_stop | n/a | right | female |
+| 13.5939 | 0.5083 | succesful_stop | n/a | n/a | female |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.633 | left | male |
| 21.6103 | 0.5083 | go | 0.443 | left | male |
````
From 77b60845a671ce0dcb8faa10a668a6a09130363e Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Tue, 26 Jul 2022 10:48:34 -0500
Subject: [PATCH 005/143] Updated the link to event restructuring
---
...lingTools.md => EventFileRestructuring.md} | 88 +++++++++++++++----
docs/source/index.rst | 2 +-
2 files changed, 72 insertions(+), 18 deletions(-)
rename docs/source/{HedRemodelingTools.md => EventFileRestructuring.md} (88%)
diff --git a/docs/source/HedRemodelingTools.md b/docs/source/EventFileRestructuring.md
similarity index 88%
rename from docs/source/HedRemodelingTools.md
rename to docs/source/EventFileRestructuring.md
index ea3294b..dd01e40 100644
--- a/docs/source/HedRemodelingTools.md
+++ b/docs/source/EventFileRestructuring.md
@@ -8,13 +8,14 @@ This tutorial works through the process of restructuring event files using the H
* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor)
* [**Running remodeling tools**](running-remodeling-tools-anchor)
* [**Remodeling operations**](remodeling-operations-anchor)
- * [**Add structure column**](add-structure-column-anchor) Docs not written
- * [**Add structure events**](add-structure-events-anchor) Docs not written
- * [**Add structure numbers**](add-structure-numbers-anchor) Docs not written
- * [**Derive column**](derive-column-anchor) Docs not written
- * [**Factor column**](factor-column-anchor) Docs not written
- * [**Factor HED**](factor-column-anchor) Docs not written
- * [**Merge events**](merge-events-anchor) Docs not written
+ * [**Add structure column**](add-structure-column-anchor) Docs in process
+ * [**Add structure events**](add-structure-events-anchor) Docs in process
+ * [**Add structure numbers**](add-structure-numbers-anchor) Docs in process
+ * [**Derive column**](derive-column-anchor) Docs in process
+ * [**Factor column**](factor-column-anchor)
+ * [**Factor HED tags**](factor-hed-tags-anchor) Docs in process
+ * [**Factor HED type**](factor-hed-type-anchor) Docs in process
+ * [**Merge events**](merge-events-anchor) Docs in process
* [**Remove columns**](remove-columns-anchor)
* [**Rename columns**](rename-columns-anchor)
* [**Reorder columns**](reorder-columns-anchor)
@@ -326,15 +327,15 @@ The results of executing this *factor_column* command on the [sample events file
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | 0 | 0 |
````
-(factor-hed-anchor)=
-### Factor HED
+(factor-hed-tags-anchor)=
+### Factor HED tags
**NOT WRITTEN - PLACEHOLDER**
Produce a list of factor columns based on the specified HED condition-variable values.
-(parameters-for-factor-hed-anchor)=
-```{admonition} Parameters for *factor_hed* command.
+(parameters-for-factor-hed-tags-anchor)=
+```{admonition} Parameters for *factor_hed_tags* command.
:class: tip
| Parameter | Type | Description |
@@ -344,14 +345,14 @@ Produce a list of factor columns based on the specified HED condition-variable v
| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
-The *factor_hed* command in the following example specifies . . .
+The *factor_hed-tags* command in the following example specifies . . .
-````{admonition} Example *factor_hed* command.
+````{admonition} Example *factor_hed_tags* command.
:class: tip
```json
{
- "command": "factor_hed"
+ "command": "factor_hed_tags"
"description": "xxx"
"parameters": {
"column_name": "match_side",
@@ -365,16 +366,69 @@ The *factor_hed* command in the following example specifies . . .
```
````
-The results of executing this *factor_hed* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *factor_hed-tags* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of *factor_hed*.
+````{admonition} Results of *factor_hed_tags*.
| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
+(factor-hed-type-anchor)=
+### Factor HED type
+
+**NOT WRITTEN - PLACEHOLDER**
+
+Produce a list of factor columns based on the specified HED condition-variable values.
+
+(parameters-for-factor-hed-type-anchor)=
+```{admonition} Parameters for *factor_hed_type* command.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| column_name | str | The name of the column to be created or modified.|
+| source_columns | list of str | A list of columns to be used for remapping. |
+| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+
+The *factor_hed-type* command in the following example specifies . . .
+
+````{admonition} Example *factor_hed-type* command.
+:class: tip
+
+```json
+{
+ "command": "factor_hed_type"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+ }
+}
+```
+````
+
+The results of executing this *factor_hed-type* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Results of *factor_hed_type*.
+
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 5f95903..b97b4cb 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -17,7 +17,7 @@ HED examples and tutorials
HedValidation.md
HedSearchAndSummary.md
HedConditionsAndDesignMatrices.md
- HedRemodelingTools.md
+ EventFileRestructuring.md
.. toctree::
From 3b62eeb59e5f172a570d033c540ff8648e26b6a6 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Wed, 27 Jul 2022 10:35:49 -0500
Subject: [PATCH 006/143] Added documentation for split_event
---
docs/source/EventFileRestructuring.md | 151 ++++++++++++++------------
1 file changed, 80 insertions(+), 71 deletions(-)
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index dd01e40..cc3eb36 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -4,10 +4,10 @@
This tutorial works through the process of restructuring event files using the HED event remodeling tools. The tools are designed to be run on an entire BIDS dataset.
-* [**What is restructuring?**](what-is-event-file-restructuring-anchor)
-* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor)
-* [**Running remodeling tools**](running-remodeling-tools-anchor)
-* [**Remodeling operations**](remodeling-operations-anchor)
+* [**What is restructuring?**](what-is-event-file-restructuring-anchor) Docs in process
+* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor) Docs in process
+* [**Running remodeling tools**](running-remodeling-tools-anchor) Docs in process
+* [**Remodeling operations**](remodeling-operations-anchor) Docs in process
* [**Add structure column**](add-structure-column-anchor) Docs in process
* [**Add structure events**](add-structure-events-anchor) Docs in process
* [**Add structure numbers**](add-structure-numbers-anchor) Docs in process
@@ -151,7 +151,7 @@ The results of executing this *add_structure_events* command on the [sample even
| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
@@ -647,10 +647,13 @@ The results of executing the previous *rename_columns* command on the [sample ev
### Reorder columns
Reorder the columns in the specified order. If *ignore_missing* is true,
-the dataframe columns not included are discarded.
+and items in the reorder list do not exist in the file, these columns are ignored.
On the other hand, if *ignore_missing* is false,
-column names that do not appear in the reorder list are moved to the end
-of the dataframe in the same order that they appear.
+a column name not appearing in the reorder list causes a *ValueError* to be raised.
+
+The *keep_others* parameter controls whether or not columns in the dataframe that
+do not appear in the reorder list are dropped (*keep_others* is false) or
+put at the end of the dataframe in the order they appear (*keep_others* is true).
(parameters-for-reorder-columns-anchor)=
```{admonition} Parameters for *reorder_columns*.
@@ -659,7 +662,8 @@ of the dataframe in the same order that they appear.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
| column_order | list | A list of columns in the order they should appear in the data.|
-| ignore_missing | boolean | If false, existing columns that aren't in column_names
are moved to the end and in the same relative
order that they originally appeared in the data. |
+| ignore_missing | bool | If true and a column in column_order does not appear in the dataframe
a ValueError is raised, otherwise these columns are ignored. |
+| keep_others | bool | If true, existing columns that aren't in column_order
are moved to the end in the same relative
order that they originally appeared in the data,
otherwise these columns are dropped.|
```
@@ -675,8 +679,9 @@ Since *ignore_missing* is true, these will be the only columns retained.
"command": "reorder_columns",
"description": "Reorder columns.",
"parameters": {
- "column_order": ["onset", "duration", "trial_type", "response_hand", "response_time"],
- "ignore_missing": true
+ "column_order": ["onset", "duration", "response_time", "trial_type"],
+ "ignore_missing": true,
+ "keep_others": false
}
}
```
@@ -687,23 +692,23 @@ The results of executing the previous *reorder_columns* command on the [sample e
````{admonition} Results of *reorder_columns*.
-| onset | duration | trial_type | response_hand | response_time |
-| ----- | -------- | ---------- | ------------- | ------------- |
-| 0.0776 | 0.5083 | go | right | 0.565 |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.49 |
-| 9.5856 | 0.5084 | go | right | 0.45 |
-| 13.5939 | 0.5083 | succesful_stop | n/a | n/a |
-| 17.1021 | 0.5083 | unsuccesful_stop | left | 0.633 |
-| 21.6103 | 0.5083 | go | left | 0.443 |
+| onset | duration | response_time | trial_type |
+| ----- | -------- | ---------- | ------------- |
+| 0.0776 | 0.5083 | 0.565 | go |
+| 5.5774 | 0.5083 | 0.49 | unsuccesful_stop |
+| 9.5856 | 0.5084 | 0.45 | go |
+| 13.5939 | 0.5083 | n/a | succesful_stop |
+| 17.1021 | 0.5083 | 0.633 | unsuccesful_stop |
+| 21.6103 | 0.5083 | 0.443 | go |
````
(split-event-anchor)=
### Split event
-The *split_event* is the most complicated of the remodeling operations and is often used to
-convert event files from using *trial-level* encoding to *event-level* encoding.
+The *split_event*, which is one of the more complicated remodeling operations,
+is often used to convert event files from using *trial-level* encoding to *event-level* encoding.
In *trial-level* encoding each row of the event file represents all the events in a single trial
-(usually some variation of cue-stimulus-response-feedback-ready sequence).
+(usually some variation of the cue-stimulus-response-feedback-ready sequence).
In *event-level* encoding, each row represents the marker for a single event.
In this case a trial consists of a sequence of multiple events.
@@ -731,65 +736,69 @@ Unlisted columns are filled with n/a.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
| anchor_event | str | The name of the column that will be used for split-event codes.|
-| event_selection | dict | Dictionary which events should be split (currently ignored and all events are split). |
-| new_events | dict | Dictionary whose keys are the codes to be inserted as new events and whose values are dictionaries with keys *onset_source*, *duration*, and *copy_columns*. |
-| add_event_numbers | boolean | If true, a column of event numbers are added before the split. |
-| remove_parent_event | boolean | If true, remove parent event. |
+| new_events | dict | Dictionary whose keys are the codes to be inserted as new events
and whose values are dictionaries with
keys *onset_source*, *duration*, and *copy_columns*. |
+| add_event_numbers | bool | If true, adds a column called *event_numbers*. |
+| remove_parent_event | bool | If true, remove parent event. |
```
-The *split_event* command in the following example specifies that *response_hand*
-column be renamed *hand_used* and that the *sex* column be renamed *image_sex*.
-The *face* entry in the mapping will be ignored because *ignore_missing* is true.
-If *ignore_missing* is false, a `KeyError` exception is raised if a column specified in
-the mapping does not correspond to a column name in the dataframe.
+The *split_event* command in the following example specifies that new rows should be added
+to encode the response and stop signal. The anchor column is still trial_type.
+In a full processing example, it might make sense to rename *trial_type* to be
+*event_type* and to delete the *response_time* and the *stop_signal_delay*
+since these items have been unfolded into separate events.
-````{admonition} An example split_event command.
+````{admonition} An example *split_event* command.
:class: tip
```json
-{
- "command": "split_event",
- "description": "Takes trial-level encoding and turns it into event-level encoding.",
- "parameters": {
- "anchor_column": "trial_type",
- "event_selection": {},
- "new_events": {
- "response": {
- "onset": ["response_time"],
- "duration": [0],
- "column_columns": ["response_accuracy", "response_hand", "sex"]
- },
- "stop_signal": {
- "onset": ["stop_signal_delay"],
- "duration": [0.5],
- "column_columns": ["response_accuracy", "response_hand", "sex"]
- }
- },
- "add_event_numbers": true,
- "remove_parent_event": false
+{
+ "command": "split_events",
+ "description": "add response events to the trials.",
+ "parameters": {
+ "anchor_column": "trial_type",
+ "event_numbers_column": "trial_number",
+ "new_events": {
+ "response": {
+ "onset_source": ["response_time"],
+ "duration": [0],
+ "copy_columns": ["response_accuracy", "response_hand", "sex", "trial_number"]
+ },
+ "stop_signal": {
+ "onset_source": ["stop_signal_delay"],
+ "duration": [0.5],
+ "copy_columns": ["trial_number"]
+ }
+ },
+ "remove_parent_event": false
+ }
}
-}
```
````
The results of executing this *split_event* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of the split_event command.
-| onset | duration | trial_type | response_accuracy | response_hand | sex | trial_number |
-| ----- | -------- | ---------- | ----------------- | ------------- | --- | ------------ |
-| 0.0776 | 0.5083 | go | correct | right | female | 1 |
-| 0.6426 | 0.0 | response | correct | right | female | 1 |
-| 5.5774 | 0.5083 | unsuccesful_stop | correct | right | female | 2 |
-| 5.7774 | 0.5 | stop_signal | correct | right | female | 2 |
-| 6.0674 | 0.0 | response | correct | right | female | 2 |
-| 9.5856 | 0.5084 | go | correct | right | female | 3 |
-| 10.0356 | 0.0 | response | correct | right | female | 3 |
-| 13.5939 | 0.5083 | succesful_stop | n/a | n/a | female | 4 |
-| 13.7939 | 0.5 | stop_signal | n/a | right | female | 4 |
-| 17.1021 | 0.5083 | unsuccesful_stop | correct | left | male | 5 |
-| 17.3521 | 0.5 | stop_signal | correct | left | male | 5 |
-| 17.7351 | 0.0 | response | correct | left | male | 5 |
-| 21.6103 | 0.5083 | go | correct | left | male | 6 |
-| 22.0533 | 0.0 | response | correct | left | male | 6 |
-````
\ No newline at end of file
+````{admonition} Results of the previous *split_event* command.
+
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | trial_number |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | -------- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | 1 |
+| 0.6426 | 0 | response | n/a | n/a | correct | right | female | 1 |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | 2 |
+| 5.7774 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a | 2 |
+| 6.0674 | 0 | response | n/a | n/a | correct | right | female | 2 |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 3 |
+| 10.0356 | 0 | response | n/a | n/a | correct | right | female | 3 |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | 4 |
+| 13.7939 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a | 4 |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | 5 |
+| 17.3521 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a | 5 |
+| 17.7351 | 0 | response | n/a | n/a | correct | left | male | 5 |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | 6 |
+| 22.0533 | 0 | response | n/a | n/a | correct | left | male | 6 |
+````
+
+Note that the event numbers are added before the splitting and then
+copied as the new events are created.
+This strategy results in a trial number column associated with the events,
+an alternative to the more complicated process of adding a structure column after splitting.
\ No newline at end of file
From 37051700a1b7643d969036cca68e3f6f4ca8cefb Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Wed, 27 Jul 2022 16:30:38 -0500
Subject: [PATCH 007/143] Added italics for parameters
---
docs/source/EventFileRestructuring.md | 142 +++++++++++-------
...b-0013_task-stopsignal_acq-seq_events.json | 63 ++++++++
2 files changed, 154 insertions(+), 51 deletions(-)
create mode 100644 docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index cc3eb36..c041f84 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -101,7 +101,7 @@ The results of executing this *add_structure_column* command on the [sample even
| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
@@ -119,9 +119,9 @@ Add events representing the start of a structural element such as a trial or a b
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list | Names of the columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *column_name* | str | The name of the column to be created or modified.|
+| *source_columns* | list | Names of the columns to be used for remapping. |
+| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
The *add_structure_events* command in the following example specifies . . .
@@ -171,9 +171,9 @@ Add a column with numbers corresponding to a structural element.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *column_name* | str | The name of the column to be created or modified.|
+| *source_columns* | list of str | A list of columns to be used for remapping. |
+| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
The *add_structure_numbers* command in the following example specifies . . .
@@ -227,9 +227,9 @@ based on predefined combinations of values in other columns.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *column_name* | str | The name of the column to be created or modified.|
+| *source_columns* | list of str | A list of columns to be used for remapping. |
+| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
The *derive_column* command in the following example specifies . . .
@@ -279,11 +279,11 @@ If no values are specified, all unique values in that column are factored.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be factored.|
-| factor_values | list | A list of column values to be included as factors. |
-| factor_names | list| A list of column names for created factors
of the same length as factor_values. |
-| ignore_missing| bool | If true, columns corresponding to factor values
that do not appear in column are included. |
-| overwrite_existing| bool | If true an existing factor column is overwritten. |
+| *column_name* | str | The name of the column to be factored.|
+| *factor_values* | list | A list of column values to be included as factors. |
+| *factor_names* | list| A list of column names for created factors
of the same length as factor_values. |
+| *ignore_missing* | bool | If true, columns corresponding to factor values
that do not appear in column are included. |
+| *overwrite_existing* | bool | If true an existing factor column is overwritten. |
```
The *factor_column* command in the following example specifies that factor columns
should be created for *succesful_stop* and *unsuccesful_stop* of the *trial_type* column.
@@ -340,9 +340,9 @@ Produce a list of factor columns based on the specified HED condition-variable v
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *column_name* | str | The name of the column to be created or modified.|
+| *source_columns* | list of str | A list of columns to be used for remapping. |
+| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
The *factor_hed-tags* command in the following example specifies . . .
@@ -383,9 +383,19 @@ The results of executing this *factor_hed-tags* command on the [sample events fi
(factor-hed-type-anchor)=
### Factor HED type
-**NOT WRITTEN - PLACEHOLDER**
+The factor HED type operation produces factor columns in an event file
+based on values of the specified HED type tag.
+The most common type is the HED *Condition-variable* tag, which corresponds to
+factor vectors based in the experimental design.
+Other commonly use type tags include *Task*, *Control-variable*, and *Time-block*.
-Produce a list of factor columns based on the specified HED condition-variable values.
+We assume that the dataset has been annotated using HED tags to properly document
+the experiment conditions and focus on how such an annotated dataset can be
+used with event remodeling to produce factor columns in the event file corresponding to these
+condition variables.
+
+For additional information on how to encode experimental designs using HED please see
+[HED conditions and design matrices](https://hed-examples.readthedocs.io/en/latest/HedConditionsAndDesignMatrices.html).
(parameters-for-factor-hed-type-anchor)=
```{admonition} Parameters for *factor_hed_type* command.
@@ -393,20 +403,20 @@ Produce a list of factor columns based on the specified HED condition-variable v
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *type_tag* | str | A HED tag used to produce the factors (most commonly *Condition-variable*).|
+| *type_values* | list | A list of values to factor for the *type_tag*.
If empty all values of that type_tag are used. |
+| *overwrite_existing* | bool | If true an existing factor column is overwritten. |
```
-The *factor_hed-type* command in the following example specifies . . .
+To simplifyThe *factor_hed_type* command in the following example specifies . . .
-````{admonition} Example *factor_hed-type* command.
+````{admonition} Example *factor_hed_type* command.
:class: tip
```json
{
"command": "factor_hed_type"
- "description": "xxx"
+ "description": "Factor based on the sex of the images being presented."
"parameters": {
"column_name": "match_side",
"source_columns": ["response_accuracy", "response_hand"],
@@ -419,18 +429,48 @@ The *factor_hed-type* command in the following example specifies . . .
```
````
-The results of executing this *factor_hed-type* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+In order to use the JSON file. The full file is at:
+
+
+````{admonition} Example *factor_hed_type* command.
+:class: tip
+
+```json
+{
+ "trial_type": {
+ "HED": {
+ "succesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/succesful_stop",
+ "unsuccesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/unsuccesful_stop",
+ "go": "Sensory-presentation, Visual-presentation, Image, Label/go"
+ },
+ "sex": {
+ "HED": {
+ "male": "Def/Male-image-cond",
+ "female": "Def/Female-image-cond"
+ }
+ },
+ "hed_defs": {
+ "HED": {
+ "def_male": "(Definition/Male-image-cond, (Condition-variable/Image-sex, (Male, (Image, Face))))",
+ "def_female": "(Definition/Female-image-cond, (Condition-variable/Image-sex, (Female, (Image, Face))))"
+ }
+ }
+}
+```
+````
+
+The results of executing this *factor_hed_type* command on the [sample events file](sample-remodeling-events-file-anchor) are:
````{admonition} Results of *factor_hed_type*.
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
-| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
-| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex | Image-sex.Female-image-cond | Image-sex.Male-image-cond |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ------- | ---------- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female | 1 | 0 |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female | 1 | 0 |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 1 | 0 |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | 1 | 0 |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | 0 | 1 |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | 0 | 1 |
````
(merge-events-anchor)=
@@ -446,9 +486,9 @@ One long event is represented by multiple repeat events. Merges these same event
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be created or modified.|
-| source_columns | list of str | A list of columns to be used for remapping. |
-| mapping | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *column_name* | str | The name of the column to be created or modified.|
+| *source_columns* | list of str | A list of columns to be used for remapping. |
+| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
```
The *merge_events* command in the following example specifies . . .
@@ -500,8 +540,8 @@ parameter is *false*, a `KeyError` is raised for missing column.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| remove_names | list of str | A list of columns to remove.|
-| ignore_missing | boolean | If true, missing columns are ignored, otherwise raise an error. |
+| *remove_names* | list of str | A list of columns to remove.|
+| *ignore_missing* | boolean | If true, missing columns are ignored, otherwise raise an error. |
```
The *remove_column* command in the following example removes the *stop_signal_delay* and
@@ -551,8 +591,8 @@ Remove rows in which the named column has one of the specified values.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_name | str | The name of the column to be tested.|
-| remove_values | list | A list of values to be tested for removal. |
+| *column_name* | str | The name of the column to be tested.|
+| *remove_values* | list | A list of values to be tested for removal. |
```
The following example *remove_rows* command removes the rows whose *trial_type* column
@@ -599,8 +639,8 @@ Rename columns by providing a dictionary of old names to new names.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_mapping | dict | The keys are the old column names and the values are the new names.|
-| ignore_missing | bool | If false, a key error is raised if a dictionary key is not a column name . |
+| *column_mapping* | dict | The keys are the old column names and the values are the new names.|
+| *ignore_missing* | bool | If false, a key error is raised if a dictionary key is not a column name. |
```
The *rename_columns* command in the following example specifies that *response_hand* column be
@@ -661,9 +701,9 @@ put at the end of the dataframe in the order they appear (*keep_others* is true)
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| column_order | list | A list of columns in the order they should appear in the data.|
-| ignore_missing | bool | If true and a column in column_order does not appear in the dataframe
a ValueError is raised, otherwise these columns are ignored. |
-| keep_others | bool | If true, existing columns that aren't in column_order
are moved to the end in the same relative
order that they originally appeared in the data,
otherwise these columns are dropped.|
+| *column_order* | list | A list of columns in the order they should appear in the data.|
+| *ignore_missing* | bool | If true and a column in *column_order* does not appear in the dataframe
a *ValueError* is raised, otherwise these columns are ignored. |
+| *keep_others* | bool | If true, existing columns that aren't in *column_order*
are moved to the end in the same relative
order that they originally appeared in the data,
otherwise these columns are dropped.|
```
@@ -735,10 +775,10 @@ Unlisted columns are filled with n/a.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| anchor_event | str | The name of the column that will be used for split-event codes.|
-| new_events | dict | Dictionary whose keys are the codes to be inserted as new events
and whose values are dictionaries with
keys *onset_source*, *duration*, and *copy_columns*. |
-| add_event_numbers | bool | If true, adds a column called *event_numbers*. |
-| remove_parent_event | bool | If true, remove parent event. |
+| *anchor_event* | str | The name of the column that will be used for split-event codes.|
+| *new_events* | dict | Dictionary whose keys are the codes to be inserted as new events
and whose values are dictionaries with
keys *onset_source*, *duration*, and *copy_columns*. |
+| *add_event_numbers* | bool | If true, adds a column called *event_numbers*. |
+| *remove_parent_event* | bool | If true, remove parent event. |
```
diff --git a/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json b/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json
new file mode 100644
index 0000000..205666d
--- /dev/null
+++ b/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json
@@ -0,0 +1,63 @@
+{
+ "trial_type": {
+ "Description": "Description for trial_type",
+ "HED": {
+ "succesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/succesful_stop",
+ "unsuccesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/unsuccesful_stop",
+ "go": "Sensory-presentation, Visual-presentation, Image, Label/go"
+ },
+ "Levels": {
+ "succesful_stop": "Presentation of a face image in a trial with a stop signal in which participant inhibited response.",
+ "unsuccesful_stop": "Presentation of a face image in a trial with a stop signal in which participant did not inhibit response.",
+ "go": "Presentation of a face image in a trial with no stop signal"
+ }
+ },
+ "stop_signal_delay": {
+ "Description": "Stop-signal cue delay from onset.",
+ "HED": "((Cue, Think/Inhibit), Delay/# s)"
+ },
+ "response_time": {
+ "Description": "Response time delay from onset.",
+ "HED": "(Participant-response, Delay/# s)"
+ },
+ "response_accuracy": {
+ "Description": "Indicates whether a response correctly indicated",
+ "HED": {
+ "incorrect": "(Incorrect-action, (Identify, (Image, Sex)))",
+ "correct": "(Correct-action, (Identify, (Image, Sex)))"
+ },
+ "Levels": {
+ "incorrect": "Used the wrong hand to indicate the sex of the face image.",
+ "correct": "Used the correct hand to indicate the sex of the face image."
+ }
+ },
+ "response_hand": {
+ "Description": "Description for response_hand",
+ "HED": {
+ "left": "(Hand, (Left-side-of, Body))",
+ "right": "(Hand, (Right-side-of, Body))"
+ },
+ "Levels": {
+ "left": "A response using the left hand.",
+ "right": "A response using the right hand."
+ }
+ },
+ "sex": {
+ "Description": "The sex of the image",
+ "HED": {
+ "male": "Def/Male-image-cond",
+ "female": "Def/Female-image-cond"
+ },
+ "Levels": {
+ "male": "The image was the face of a male person.",
+ "female": "The image was the face of a female person."
+ }
+ },
+ "hed_defs": {
+ "Description": "HED user-defined terms for the dataset.",
+ "HED": {
+ "def_male": "(Definition/Male-image-cond, (Condition-variable/Image-sex, (Male, (Image, Face))))",
+ "def_female": "(Definition/Female-image-cond, (Condition-variable/Image-sex, (Female, (Image, Face))))"
+ }
+ }
+}
\ No newline at end of file
From d0c8cb990eac6e176584888231dd0e8a215abbf1 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Sat, 30 Jul 2022 13:15:53 -0500
Subject: [PATCH 008/143] Worked on the ConditionsAndDesign tutorial
---
docs/source/EventFileRestructuring.md | 26 +-
docs/source/HedConditionsAndDesignMatrices.md | 278 +++++++++++++++++-
docs/source/package.json | 14 +
3 files changed, 308 insertions(+), 10 deletions(-)
create mode 100644 docs/source/package.json
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index c041f84..aff01f7 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -25,7 +25,14 @@ This tutorial works through the process of restructuring event files using the H
(what-is-event-file-restructuring-anchor)=
## What is event file restructuring?
-**Need brief introduction to event remodeling here**
+Event file restructuring generally falls into four categories: cleanup,
+row modifications, column modifications, and structure modifications.
+
+#### Cleanup operations
+
+Cleanup operations include: *rename_columns*, *reorder_columns*, and *remove_columns*.
+
+#### Row modifications
(installation-of-remodeling-tools-anchor)=
## Installation of remodeling tools
@@ -44,7 +51,7 @@ The examples in this chapter use the following excerpt from sub-0013
stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneuro.org) as ds002790.
(sample-remodeling-events-file-anchor)=
-````{admonition} Excerpt from event file for a stop-go task.
+````{admonition} Excerpt from event file for a stop-go task of AOMIC-PIOP2 (ds002790).
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
@@ -405,7 +412,9 @@ For additional information on how to encode experimental designs using HED pleas
| ------------ | ---- | ----------- |
| *type_tag* | str | A HED tag used to produce the factors (most commonly *Condition-variable*).|
| *type_values* | list | A list of values to factor for the *type_tag*.
If empty all values of that type_tag are used. |
-| *overwrite_existing* | bool | If true an existing factor column is overwritten. |
+| *overwrite_existing* | bool | If true, an existing factor columns is overwritten. |
+| *include_hed_strings* | bool | If true, a column *hed_expand* with HED strings is included. |
+| *one_hot_factors* | bool | If true, the factors use one-hot representation (zeros and ones). |
```
To simplifyThe *factor_hed_type* command in the following example specifies . . .
@@ -418,12 +427,11 @@ To simplifyThe *factor_hed_type* command in the following example specifies . .
"command": "factor_hed_type"
"description": "Factor based on the sex of the images being presented."
"parameters": {
- "column_name": "match_side",
- "source_columns": ["response_accuracy", "response_hand"],
- "mapping": {
- "left": [["correct", "left"], ["incorrect", "right"]],
- "right": [["correct", "right"], ["incorrect", "left"]]
- }
+ "type_tag": "Condition-variable",
+ "type_values": [],
+ "overwrite_existing": true,
+ "include_hed_strings": false,
+ "one_hot_factors": true
}
}
```
diff --git a/docs/source/HedConditionsAndDesignMatrices.md b/docs/source/HedConditionsAndDesignMatrices.md
index a7566ac..254f6af 100644
--- a/docs/source/HedConditionsAndDesignMatrices.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -1,3 +1,279 @@
# HED conditions and design matrices
-**Under construction**
+This tutorial discusses how information from neuroimaging experiments should be
+stored and annotated so that the underlying experimental design and experimental conditions
+for a dataset can be automatically extracted, summarized, and used in analysis.
+The mechanisms for doing this use HED (Hierarchical Event Descriptors) in conjunction
+with a [BIDS](https://bids.neuroimaging.io/)
+(Brain Imaging Data Structure) representation of the dataset.
+
+The tutorial assumes that you have a basic understanding of HED and
+how HED annotations are used in BIDS.
+Please review [**Annotating a BIDS dataset**](https://bids-standard.github.io/bids-starter-kit/tutorials/annotation.html),
+the [**BIDS annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/BidsAnnotationQuickstart.html), and the
+[**HED annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/HedAnnotationQuickstart.html)
+tutorials as needed.
+
+
+
+* [**Neuroimaging experimental design**](neuroimaging-experimental-anchor)
+ * [**Design matrices and factor variables**](design-matrices-and-factor-variables-anchor)
+ * [**Types of condition encoding**](types-of-condition-encoding-anchor)
+* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor) Docs in process
+* [**Running remodeling tools**](running-remodeling-tools-anchor) Docs in process
+* [**Remodeling operations**](remodeling-operations-anchor) Docs in process
+ * [**Add structure column**](add-structure-column-anchor) Docs in process
+ * [**Add structure events**](add-structure-events-anchor) Docs in process
+
+This tutorial introduces tools and strategies for including this information
+as part of a dataset without excessive effort on the part of the researcher.
+The discussion mainly focuses on categorical variables, but HED
+also can encode numerical values as discussed later in the tutorial.
+
+(neuroimaging-experimental-anchor)=
+## Neuroimaging experimental design
+Traditional neuroimaging experiments are carefully designed to control and
+document the external conditions under which the experiment is conducted.
+Often a few items such as the task or the properties of a stimulus are
+systematically varied as the stimulus is presented and participant responses
+are recorded.
+
+For example, in an experiment to test for differences in
+brain responses to pictures of houses versus pictures of faces,
+the researcher would label time points in the recording corresponding
+to presentations of the respective pictures so that differences in
+brain responses between the two types of pictures could be observed.
+An fMRI analysis might determine which brain regions
+showed a significant response differential between the two types of responses.
+An EEG/MEG analysis might also focus on the differences in time courses
+between the responses to the two types of images.
+
+Thus, the starting point for many analyses is the association of
+labels corresponding to different **experimental conditions** with
+time points in the data recording.
+In BIDS, this association is stored an `events.tsv` file paired
+with the data recording,
+but this information may also be stored as part of the recording
+itself, depending on the technology and the format of the recording.
+
+(design-matrices-and-factor-variables-anchor)=
+### Design matrices and factor variables
+
+The type of information included for the experimental conditions
+and how this information is stored depends very much on the experiment.
+Most analysis tools require a vector (sometimes called a **factor vector**)
+of elements associated with the event markers for each type of experimental condition.
+
+For linear modeling and other types of regression, these factor vectors are assembled
+into **design matrix** to use as input for the analysis.
+Design matrices can also include other types of columns depending on the modeling strategy.
+
+(types-of-condition-encoding-anchor)=
+### Types of condition encoding
+
+Consider the simple example introduced above of an experiment which
+varies the stimuli between pictures of houses and faces to measure
+differences in response.
+The following example shows three possible types of encodings
+(**categorical**, **ordinal**, and **one-hot**) that might be sued
+for this association. The table shows an excerpt from a putative events file,
+with the onset column (required by BIDS) containing the time of the event marker
+relative to the start of the associated data recording.
+The duration column (also required by BIDS) contains the duration of the
+image presentation in seconds.
+
+(different-encodings-of-design-variables-anchor)=
+````{admonition} Example 1: Different encodings of a column with categorical values.
+| onset | duration | categorical | ordinal | one_hot.house | one_hot.face |
+| ----- | -------- |----------- |-------- | ------------- | ------------ |
+| 2.010 | 0.1 | house | 1 | 1 | 0 |
+| 3.210 | 0.1 | house | 1 | 1 | 0 |
+| 4.630 | 0.1 | face | 2 | 0 | 1 |
+| 6.012 | 0.1 | house | 1 | 1 | 0 |
+| 7.440 | 0.1 | face | 2 | 0 | 1 |
+````
+
+The **categorical** encoding assigns laboratory-specific names to the
+different types of stimuli.
+In theory, this categorical column consisting of the strings *house* and *face*
+could be used as a factor vector or as part of a design matrix for regression.
+However, many analysis tools require that these names be assigned numerical
+values.
+
+The **ordinal** encoding assigns an arbitrary sequence of numbers corresponding
+to the unique values.
+If there are only 2 values, the values -1 and 1 are often used.
+Ordinal encodings impose an order based on the values
+chosen, which may have undesirable affects on the results of analyses such
+as regression if the ordering/relative sizes do not reflect the
+properties of the encoded experimental conditions.
+
+In the example above, the experimental conditions houses and faces do not
+have an ordering/size relationship reflected by the encoding (house=1, face=2).
+In addition, neither categorical nor ordinal encoding
+can represent items falling into multiple categories of the same condition at the same time.
+For these reasons, many statistical tools require one-hot encoding.
+
+In **one-hot** encoding, each possible value of the condition is represented
+by its own column with 1's representing the presence of that condition value
+and experimental conditions and 0's otherwise. One-hot encodes all values
+without bias and allows for a given event to be a member of multiple categories.
+This representation is required for many machine-learning models.
+A disadvantage is that it can generate a large number of columns if there
+are many unique categorical values. It can also cause a problem if not all
+files contain the same values, as then different files may have different columns.
+
+(hed-annotation-for-conditions-anchor)
+## HED annotation for conditions
+
+As mentioned above, HED (Hierarchical Event Descriptors) provide several mechanisms for easily
+annotating the experimental conditions represented by a BIDS dataset so that
+the information can be automatically extracted, summarized and used by tools.
+
+HED has three ways of annotating experimental conditions: condition variables without definitions,
+condition variables with definitions but no levels, and condition variables with levels.
+All three mechanisms use the *Condition-variable* tag as part of the annotation.
+The three mechanisms can be used in any combination to document the experimental design
+for a dataset.
+
+(condition-variables-without-definitions-anchor)=
+### Condition variables without definitions
+
+The simplest way to encode experimental conditions is to use named *Condition-variable*
+tags for each condition value. The following is a sample excerpt from
+a possible event file for the experiment to distinguish brain responses
+for houses and faces. We assume that the participant has been
+instructed to push a button to indicate that he/she has identified
+the image as a either a house or a face.
+
+(sample-house-face-example-anchor)=
+````{admonition} Example 2. Excerpt from a sample event file from house-face experiment.
+| onset | duration | event_type | response_time | stim_file |
+| ----- | -------- |----------- |-------- | ---------- |
+| 2.010 | 0.1 | house | 0.23 | ranch1.png |
+| 3.210 | 0.1 | house | 0.12 | colonial68.png |
+| 4.630 | 0.1 | face | 0.41 | female43.png |
+| 6.012 | 0.1 | house | 0.35 | castle2.png |
+| 7.440 | 0.1 | face | 0.32 | male81.png |
+````
+
+As explained in [**BIDS annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/BidsAnnotationQuickstart.html),
+the most commonly used strategy for annotating events in a BIDS dataset is
+to create a single JSON file located in the dataset root containing the annotations
+for the columns. The following shows a minimal example
+
+````{admonition} Example 3: Minimal JSON sidecar with HED annotations for Example 1.
+:class: tip
+
+```json
+{
+ "event_type": {
+ "HED": {
+ "house": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Building/House), Condition-variable/House-cond",
+ "face": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Face), Condition-variable/Face-cond"
+ }
+ },
+ "response_time": {
+ "HED": "(Participant-response, (Press, Push-button), Delay/#)"
+ },
+ "stim_file": {
+ "HED": "(Image, Pathname/#)"
+ }
+}
+```
+````
+
+Each row in an `events.tsv` file represents a time marker in the corresponding data recording.
+At analysis time, HED tools look up each column value in the JSON file and concatenate the
+corresponding HED annotation into a single string representing the annotation for that row.
+Annotations without #'s are used directly, while annotations with # have the corresponding
+column values substituted when the annotation is assembled.
+
+````{admonition} Example 3: HED annotation for first event in Example 1 using JSON sidecar of Example 2.
+:class: tip
+> "*Sensory-presentation*, *Visual-presentation*, *Experimental-stimulus*,
+> (*Image*, *Building/House*), *Condition-variable/House-cond*,
+> (*Participant-response*, (*Press*, *Push-button*), *Delay/0.23*),
+> (*Image*, *Pathname/ranch1.png*)"
+````
+
+HED tools have the capability of automatically detecting *Condition-variable*
+tags in annotated HED datasets and creating factor vectors and summaries automatically.
+Example 4 shows the event file after HED tools have appended one-hot factor vectors.
+
+
+````{admonition} Example 4. Example 2 after HED tools have extracted one-hot factor vectors.
+| onset | duration | event_type | response_time | stim_file | House-cond | Face-cond |
+| ----- | -------- |----------- |-------- | ---------- |----------- | ----------- |
+| 2.010 | 0.1 | house | 0.23 | ranch1.png | 1 | 0 |
+| 3.210 | 0.1 | house | 0.12 | colonial68.png | 1 | 0 |
+| 4.630 | 0.1 | face | 0.41 | female43.png | 0 | 1 |
+| 6.012 | 0.1 | house | 0.35 | castle2.png | 1 | 0 |
+| 7.440 | 0.1 | face | 0.32 | male81.png | 0 | 1 |
+````
+
+Example 5 shows the JSON summary that HED tools can extract once a dataset has been
+annotated using HED. This very simple example only had two condition variables
+and only used direct references to condition variables.
+The summary shows that of the total of 5 events in the file 3 events were under
+the house condition and 2 events were under the face condition.
+
+````{admonition} Example 5: The HED tools summary of condition variables for Example 4.
+:class: tip
+
+```json
+{
+ "house-cond": {
+ "name": "house-cond",
+ "variable_type": "condition-variable",
+ "levels": 0,
+ "direct_references": 3,
+ "total events": 5,
+ "number events": 3,
+ "number_multiple": 0,
+ "multiple maximum": 1,
+ "level counts": {}
+ },
+ "face-cond": {
+ "name": "face-cond",
+ "variable_type": "condition-variable",
+ "levels": 0,
+ "direct_references": 2,
+ "total events": 5,
+ "number events": 2,
+ "number_multiple": 0,
+ "multiple maximum": 1,
+ "level counts": {}
+ }
+}
+````
+There were no events in multiple categories of the same condition variables
+(which would not be possible since these condition variables were referenced
+directly rather than assigned levels).
+All names are translated to lower case as HED is case-insensitive with respect to analysis.
+
+These HED summaries can be created for other tags besides *Condition-variable*,
+hence the variable_type is given in the summary of Example 5.
+Other commonly created summaries are for *Task* and *Control-variable*.
+
+
+## Definitions
+(sample-design-matrix-events-file-anchor)=
+````{admonition} Excerpt from event file for a stop-go task.
+
+| onset | duration | sample | event_type | face_type | rep_status | trial | rep_lag | value | stim_file |
+| ----- | -------- | ------ | ---------- | --------- | ---------- | ----- | ------- | ----- | --------- |
+| 0.004 | n/a | 1.0 | setup_right_sym | n/a | n/a | n/a | n/a | 3 | n/a |
+| 24.2098181818 | n/a | 6052.4545 | show_face_initial | unfamiliar_face | first_show | 1 | n/a | 13 | u032.bmp |
+| 25.0352727273 | n/a | 6258.8182 | show_circle | n/a | n/a | 1 | n/a | 0 | circle.bmp |
+| 25.158 | n/a | 6289.5 | left_press | n/a | n/a | 1 | n/a | 256 | n/a |
+| 26.7352727273 | n/a | 6683.8182 | show_cross | n/a | n/a | 2 | n/a | 1 | cross.bmp |
+| 27.2498181818 | n/a | 6812.4545 | show_face | unfamiliar_face | immediate_repeat | 2 | 1 | 14 | u032.bmp |
+| 27.8970909091 | n/a | 6974.2727 | left_press | n/a | n/a | 2 | n/a | 256 | n/a |
+| 28.0998181818 | n/a | 7024.9545 | show_circle | n/a | n/a | 2 | n/a | 0 | circle.bmp |
+| 29.7998181818 | n/a | 7449.9545 | show_cross | n/a | n/a | 3 | n/a | 1 | cross.bmp |
+| 30.3570909091 | n/a | 7589.2727 | show_face | unfamiliar_face | first_show | 3 | n/a | 13 | u088.bmp |
+````
+
+
+
diff --git a/docs/source/package.json b/docs/source/package.json
new file mode 100644
index 0000000..28539dd
--- /dev/null
+++ b/docs/source/package.json
@@ -0,0 +1,14 @@
+{
+ "event_type": {
+ "HED": {
+ "house": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Building/House), Condition-variable/House-cond",
+ "face": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Face), Condition-variable/Face-cond"
+ }
+ },
+ "response_time": {
+ "HED": "Participant-response, Delay/#"
+ },
+ "stim_file": {
+ "HED": "(Image, Pathname/#)"
+ }
+}
From 98f299645d1bb69b4553b22415c007ec8cd54116 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Sat, 30 Jul 2022 18:37:51 -0500
Subject: [PATCH 009/143] Updated condition variables
---
docs/source/HedConditionsAndDesignMatrices.md | 346 +++++++++++++-----
1 file changed, 262 insertions(+), 84 deletions(-)
diff --git a/docs/source/HedConditionsAndDesignMatrices.md b/docs/source/HedConditionsAndDesignMatrices.md
index 254f6af..3772a90 100644
--- a/docs/source/HedConditionsAndDesignMatrices.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -19,11 +19,10 @@ tutorials as needed.
* [**Neuroimaging experimental design**](neuroimaging-experimental-anchor)
* [**Design matrices and factor variables**](design-matrices-and-factor-variables-anchor)
* [**Types of condition encoding**](types-of-condition-encoding-anchor)
-* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor) Docs in process
-* [**Running remodeling tools**](running-remodeling-tools-anchor) Docs in process
-* [**Remodeling operations**](remodeling-operations-anchor) Docs in process
- * [**Add structure column**](add-structure-column-anchor) Docs in process
- * [**Add structure events**](add-structure-events-anchor) Docs in process
+* [**HED annotations for conditions**](hed-annotations-for-conditions-anchor)
+ * [**Direct condition variables**](direct-condition-variables-anchor)
+ * [**Defined condition variables**](defined-condition-variables-anchor)
+ * [**Column vs row conditions**](column-vs-row-conditions-anchor)
This tutorial introduces tools and strategies for including this information
as part of a dataset without excessive effort on the part of the researcher.
@@ -123,8 +122,8 @@ A disadvantage is that it can generate a large number of columns if there
are many unique categorical values. It can also cause a problem if not all
files contain the same values, as then different files may have different columns.
-(hed-annotation-for-conditions-anchor)
-## HED annotation for conditions
+(hed-annotations-for-conditions-anchor)=
+## HED annotations for conditions
As mentioned above, HED (Hierarchical Event Descriptors) provide several mechanisms for easily
annotating the experimental conditions represented by a BIDS dataset so that
@@ -136,25 +135,23 @@ All three mechanisms use the *Condition-variable* tag as part of the annotation.
The three mechanisms can be used in any combination to document the experimental design
for a dataset.
-(condition-variables-without-definitions-anchor)=
-### Condition variables without definitions
+(direct-condition-variables-anchor)=
+### Direct condition variables
The simplest way to encode experimental conditions is to use named *Condition-variable*
tags for each condition value. The following is a sample excerpt from
-a possible event file for the experiment to distinguish brain responses
-for houses and faces. We assume that the participant has been
-instructed to push a button to indicate that he/she has identified
-the image as a either a house or a face.
+a simplified event file for an experiment to distinguish brain responses
+for houses and faces.
(sample-house-face-example-anchor)=
-````{admonition} Example 2. Excerpt from a sample event file from house-face experiment.
-| onset | duration | event_type | response_time | stim_file |
-| ----- | -------- |----------- |-------- | ---------- |
-| 2.010 | 0.1 | house | 0.23 | ranch1.png |
-| 3.210 | 0.1 | house | 0.12 | colonial68.png |
-| 4.630 | 0.1 | face | 0.41 | female43.png |
-| 6.012 | 0.1 | house | 0.35 | castle2.png |
-| 7.440 | 0.1 | face | 0.32 | male81.png |
+````{admonition} Example 2. Excerpt from a sample event file from a simplified house-face experiment.
+| onset | duration | event_type | stim_file |
+| ----- | -------- |----------- | ---------- |
+| 2.010 | 0.1 | show_house | ranch1.png |
+| 3.210 | 0.1 | show_house | colonial68.png |
+| 4.630 | 0.1 | show_face | female43.png |
+| 6.012 | 0.1 | show_house | castle2.png |
+| 7.440 | 0.1 | show_face | male81.png |
````
As explained in [**BIDS annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/BidsAnnotationQuickstart.html),
@@ -167,18 +164,15 @@ for the columns. The following shows a minimal example
```json
{
- "event_type": {
- "HED": {
- "house": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Building/House), Condition-variable/House-cond",
- "face": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Face), Condition-variable/Face-cond"
- }
- },
- "response_time": {
- "HED": "(Participant-response, (Press, Push-button), Delay/#)"
- },
- "stim_file": {
- "HED": "(Image, Pathname/#)"
- }
+ "event_type": {
+ "HED": {
+ "show_house": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Building/House), Condition-variable/House-cond",
+ "show_face": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Face), Condition-variable/Face-cond"
+ }
+ },
+ "stim_file": {
+ "HED": "(Image, Pathname/#)"
+ }
}
```
````
@@ -191,89 +185,273 @@ column values substituted when the annotation is assembled.
````{admonition} Example 3: HED annotation for first event in Example 1 using JSON sidecar of Example 2.
:class: tip
-> "*Sensory-presentation*, *Visual-presentation*, *Experimental-stimulus*,
-> (*Image*, *Building/House*), *Condition-variable/House-cond*,
-> (*Participant-response*, (*Press*, *Push-button*), *Delay/0.23*),
+
+> "*Sensory-presentation*, *Visual-presentation*, *Experimental-stimulus*,
+> (*Image*, *Building/House*), *Condition-variable/House-cond*,
> (*Image*, *Pathname/ranch1.png*)"
````
+Notice that *Building/House* is a partial path rather than a single tag.
+This is because *House* is currently not part of the base HED vocabulary.
+However, users are allowed to extend tags at most nodes in the HED schema,
+but they must use a path that includes a least one ancestor that is in the HED schema.
+
HED tools have the capability of automatically detecting *Condition-variable*
tags in annotated HED datasets and creating factor vectors and summaries automatically.
Example 4 shows the event file after HED tools have appended one-hot factor vectors.
-````{admonition} Example 4. Example 2 after HED tools have extracted one-hot factor vectors.
-| onset | duration | event_type | response_time | stim_file | House-cond | Face-cond |
-| ----- | -------- |----------- |-------- | ---------- |----------- | ----------- |
-| 2.010 | 0.1 | house | 0.23 | ranch1.png | 1 | 0 |
-| 3.210 | 0.1 | house | 0.12 | colonial68.png | 1 | 0 |
-| 4.630 | 0.1 | face | 0.41 | female43.png | 0 | 1 |
-| 6.012 | 0.1 | house | 0.35 | castle2.png | 1 | 0 |
-| 7.440 | 0.1 | face | 0.32 | male81.png | 0 | 1 |
+````{admonition} Example 4. Event file from Example 2 after one-hot factor vector extraction.
+
+| onset | duration | event_type | stim_file | house-cond | face-cond |
+| ----- | -------- |----------- |-------- | ---------- |----------- |
+| 2.010 | 0.1 | show_house | ranch1.png | 1 | 0 |
+| 3.210 | 0.1 | show_house | colonial68.png | 1 | 0 |
+| 4.630 | 0.1 | show_face | female43.png | 0 | 1 |
+| 6.012 | 0.1 | show_house | castle2.png | 1 | 0 |
+| 7.440 | 0.1 | show_face | male81.png | 0 | 1 |
````
-Example 5 shows the JSON summary that HED tools can extract once a dataset has been
-annotated using HED. This very simple example only had two condition variables
-and only used direct references to condition variables.
-The summary shows that of the total of 5 events in the file 3 events were under
-the house condition and 2 events were under the face condition.
+Example 5 shows a JSON summary that HED tools can extract from a single events file
+once a dataset has been annotated using HED.
+This very simple example only had two condition variables
+and only used direct references to these condition variables.
+Dataset-wide summaries can also be extracted.
+
````{admonition} Example 5: The HED tools summary of condition variables for Example 4.
:class: tip
```json
{
- "house-cond": {
- "name": "house-cond",
- "variable_type": "condition-variable",
- "levels": 0,
- "direct_references": 3,
- "total events": 5,
- "number events": 3,
+ "house-cond": {
+ "name": "house-cond",
+ "variable_type": "condition-variable",
+ "levels": 0,
+ "direct_references": 3,
+ "total events": 5,
+ "number events": 3,
"number_multiple": 0,
"multiple maximum": 1,
"level counts": {}
- },
- "face-cond": {
- "name": "face-cond",
- "variable_type": "condition-variable",
- "levels": 0,
- "direct_references": 2,
- "total events": 5,
- "number events": 2,
+ },
+ "face-cond": {
+ "name": "face-cond",
+ "variable_type": "condition-variable",
+ "levels": 0,
+ "direct_references": 2,
+ "total events": 5,
+ "number events": 2,
"number_multiple": 0,
"multiple maximum": 1,
"level counts": {}
- }
+ }
}
````
+The summary shows that of the total of 5 events in the file 3 events were under
+the house condition and 2 events were under the face condition.
There were no events in multiple categories of the same condition variables
(which would not be possible since these condition variables were referenced
-directly rather than assigned levels).
-All names are translated to lower case as HED is case-insensitive with respect to analysis.
+directly rather than using assigned levels).
+All names are translated to lower case as HED is case-insensitive with respect to analysis,
+and the summary and factorization tools convert to lower case before processing.
These HED summaries can be created for other tags besides *Condition-variable*,
-hence the variable_type is given in the summary of Example 5.
+hence the *variable_type* is given in the summary of Example 5.
Other commonly created summaries are for *Task* and *Control-variable*.
+In this example, the two conditions: *house-cond* and *face-cond* are
+treated is though they are unrelated. These direct condition variables
+are very easy to annotate--- just make up a name and stick the tags anywhere
+you want to create factor variables or summaries.
+However, a more common situation is for a condition variable to have multiple levels,
+which direct use condition variables do not support.
-## Definitions
-(sample-design-matrix-events-file-anchor)=
-````{admonition} Excerpt from event file for a stop-go task.
-
-| onset | duration | sample | event_type | face_type | rep_status | trial | rep_lag | value | stim_file |
-| ----- | -------- | ------ | ---------- | --------- | ---------- | ----- | ------- | ----- | --------- |
-| 0.004 | n/a | 1.0 | setup_right_sym | n/a | n/a | n/a | n/a | 3 | n/a |
-| 24.2098181818 | n/a | 6052.4545 | show_face_initial | unfamiliar_face | first_show | 1 | n/a | 13 | u032.bmp |
-| 25.0352727273 | n/a | 6258.8182 | show_circle | n/a | n/a | 1 | n/a | 0 | circle.bmp |
-| 25.158 | n/a | 6289.5 | left_press | n/a | n/a | 1 | n/a | 256 | n/a |
-| 26.7352727273 | n/a | 6683.8182 | show_cross | n/a | n/a | 2 | n/a | 1 | cross.bmp |
-| 27.2498181818 | n/a | 6812.4545 | show_face | unfamiliar_face | immediate_repeat | 2 | 1 | 14 | u032.bmp |
-| 27.8970909091 | n/a | 6974.2727 | left_press | n/a | n/a | 2 | n/a | 256 | n/a |
-| 28.0998181818 | n/a | 7024.9545 | show_circle | n/a | n/a | 2 | n/a | 0 | circle.bmp |
-| 29.7998181818 | n/a | 7449.9545 | show_cross | n/a | n/a | 3 | n/a | 1 | cross.bmp |
-| 30.3570909091 | n/a | 7589.2727 | show_face | unfamiliar_face | first_show | 3 | n/a | 13 | u088.bmp |
+Another disadvantage of direct condition variables is that there is
+no information about what the conditions represent beyond the arbitrarily chosen condition names.
+
+A third disadvantage is that direct condition variables can not be used to
+anchor events with temporal extent.
+
+The next section introduces the use of defined condition variables,
+which address both of these disadvantages.
+
+(defined-condition-variables-anchor)=
+## Defined condition variables
+
+
+````{admonition} Example 6: A revised JSON sidecar using defined conditions for Example 1.
+:class: tip
+
+```json
+{
+ "event_type": {
+ "HED": {
+ "show_house": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Building/House), Def/House-cond",
+ "show_face": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Face), Def/Face-cond"
+ }
+ },
+ "stim_file": {
+ "HED": "(Image, Pathname/#)"
+ },
+ "my_definitions": {
+ "HED": {
+ "house_cond_def": (Definition/House-cond, (Condition-variable/Presentation-type, (Image, Building/House))),
+ "face_cond_def": (Definition/Face-cond, (Condition-variable/Presentation-type, (Image, Face)))"
+}
+```
````
+Example 6 defines a condition variable called *Presentation-type* with two levels:
+*House-cond* and *Face-cond*.
+The definitions of *House-cond* and *Face-cond* both include the same *Presentation-type*
+*Condition-variable* so tools can recognize these as levels of the same variable and
+automatically extract 2-factor experimental design.
+
+Notice that the (*Image*, *Building/House*) tags are included both in the definition of
+the *House-cond* level of the *Presentation-type* condition variable
+and in the tags for the event_type *show_house*.
+Similarly, the (*Image*, *Face*) tags appear in both the definition of the
+*Face-cond* level of the *Presentation-type* condition variable
+and in the tags for the event_type *show_face*.
+We have included them in both places because generally the condition variable definitions
+are removed prior to searching for HED tags because the tags in the definitions
+define the meaning of the conditions.
+
+````{admonition} Example 7: The summary extracted when the JSON sidecar of Example 6 is used.
+:class: tip
+```json
+{
+ "presentation-type": {
+ "name": "presentation-type",
+ "variable_type": "condition-variable",
+ "levels": 2,
+ "direct_references": 0,
+ "total events": 5,
+ "number events": 5,
+ "number_multiple": 0,
+ "multiple maximum": 1,
+ "level counts": {
+ "house-cond": 3,
+ "face-cond": 2
+ }
+ }
+}
+```
+````
+
+(column-vs-row-conditions-anchor)=
+## Column vs row conditions
+
+In this section, we look at a more complicated example based on the Wakeman-Henson face-processing dataset.
+This dataset, which is available on [OpenNeuro](https://openneuro.org) under accession number
+ds003654, was used in as a case study on HED annotation described in the
+[Capturing the nature of events paper](https://www.sciencedirect.com/science/article/pii/S1053811921010387).
+
+The experiment is based on a 3 x 3 x 2 experimental design: face type x repetition status x key choice.
+The experimental stimulus is each trial was the visual presentation of one of 3 possible types of images:
+a well-known face, an unfamiliar face, and a scrambled face image.
+The type of face was randomized across trials.
+
+The repetition status condition variable also had one of three possible values and indicated:
+whether the stimulus image had not been seen before (first show),
+was just seen in the previous trial (immediate repeat),
+or had been seen in a several trials ago (delayed repeat).
+The repetition status was randomized across trials.
+The final condition variable in the experimental design was the key assignment.
+In the right symmetry condition, participants pressed the right mouse button
+to indicate that the presented face had above average symmetry,
+while in the left symmetry condition, participants pressed the left mouse button
+to indicate that the presented face had above average symmetry.
+The key assignment was held constant for each recording, but the key choice was
+counter-balanced across participants.
+
+
+(sample-design-matrix-events-file-anchor)=
+```{admonition} Example 8: An excerpt from the Wakeman-Henson face-processing dataset..
+
+| onset | duration | event_type | face_type | rep_status | trial | rep_lag | value | stim_file |
+| ----- | -------- | ---------- | --------- | ---------- | ----- | ------- | ----- | --------- |
+| 0.004 | n/a | setup_right_sym | n/a | n/a | n/a | n/a | 3 | n/a |
+| 24.2098 | n/a | show_face_initial | unfamiliar_face | first_show | 1 | n/a | 13 | u032.bmp |
+| 25.0353 | n/a | show_circle | n/a | n/a | 1 | n/a | 0 | circle.bmp |
+| 25.158 | n/a | left_press | n/a | n/a | 1 | n/a | 256 | n/a |
+| 26.7353 | n/a | show_cross | n/a | n/a | 2 | n/a | 1 | cross.bmp |
+| 27.2498 | n/a | show_face | unfamiliar_face | immediate_repeat | 2 | 1 | 14 | u032.bmp |
+| 27.8971 | n/a | left_press | n/a | n/a | 2 | n/a | 256 | n/a |
+| 28.0998 | n/a | show_circle | n/a | n/a | 2 | n/a | 0 | circle.bmp |
+| 29.7998 | n/a | show_cross | n/a | n/a | 3 | n/a | 1 | cross.bmp |
+| 30.3571 | n/a | show_face | unfamiliar_face | first_show | 3 | n/a | 13 | u088.bmp |
+```
+
+Example 8 illustrates two different ways of using defined conditions for encoding.
+The key assignment is marked by inserting an event with temporal extent at the beginning
+of the file. The *setup_right_sym* event is encoded in the JSON sidecar as:
+
+The condition variab
+
+```{admonition} Example 9: HED tools automatic extraction of the design matrix in categorical form for Example 8.
+
+| onset | key-assignment | face-type | repetition-type |
+| ----- | -------------- | ---- ---- | --------------- |
+| 0.004 | right-sym-com | n/a | n/a |
+| 24.2098 | right-sym-com | unfamiliar-face-cond | first-show-cond |
+| 25.0353 | right-sym-com | n/a | n/a |
+| 25.158 | right-sym-com | n/a| n/a |
+| 26.7353 | right-sym-com | n/a | n/a |
+| 27.2498 | right-sym-com | unfamiliar-face-cond | immediate-repeat-cond |
+| 27.8971 | right-sym-com | n/a | n/a |
+| 28.0998 | right-sym-com | n/a | n/a |
+| 29.7998 | right-sym-com | n/a | n/a |
+| 30.3571 | right-sym-com | unfamiliar-face-cond | first-show-cond |
+```
+
+
+
+{
+ "key-assignment": {
+ "name": "key-assignment",
+ "variable_type": "condition-variable",
+ "levels": 1,
+ "direct_references": 0,
+ "total events": 200,
+ "number events": 200,
+ "number_multiple": 0,
+ "multiple maximum": 1,
+ "level counts": {
+ "right-sym-cond": 200
+ }
+ },
+ "face-type": {
+ "name": "face-type",
+ "variable_type": "condition-variable",
+ "levels": 3,
+ "direct_references": 0,
+ "total events": 200,
+ "number events": 52,
+ "number_multiple": 0,
+ "multiple maximum": 1,
+ "level counts": {
+ "unfamiliar-face-cond": 20,
+ "famous-face-cond": 14,
+ "scrambled-face-cond": 18
+ }
+ },
+ "repetition-type": {
+ "name": "repetition-type",
+ "variable_type": "condition-variable",
+ "levels": 3,
+ "direct_references": 0,
+ "total events": 200,
+ "number events": 52,
+ "number_multiple": 0,
+ "multiple maximum": 1,
+ "level counts": {
+ "first-show-cond": 28,
+ "immediate-repeat-cond": 12,
+ "delayed-repeat-cond": 12
+ }
+ }
+}
\ No newline at end of file
From 65dbd2aa59026a1a5de8089ba4362d1295f02165 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Mon, 1 Aug 2022 09:32:02 -0500
Subject: [PATCH 010/143] Updated the restructuring documentation
---
docs/source/EventFileRestructuring.md | 162 +++++-----
docs/source/HedConditionsAndDesignMatrices.md | 283 +++++++++++++-----
.../data/task-FacePerception_events.json | 138 +++++++++
docs/source/package.json | 22 +-
4 files changed, 441 insertions(+), 164 deletions(-)
create mode 100644 docs/source/_static/data/task-FacePerception_events.json
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index aff01f7..559010b 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -11,11 +11,11 @@ This tutorial works through the process of restructuring event files using the H
* [**Add structure column**](add-structure-column-anchor) Docs in process
* [**Add structure events**](add-structure-events-anchor) Docs in process
* [**Add structure numbers**](add-structure-numbers-anchor) Docs in process
- * [**Derive column**](derive-column-anchor) Docs in process
* [**Factor column**](factor-column-anchor)
* [**Factor HED tags**](factor-hed-tags-anchor) Docs in process
* [**Factor HED type**](factor-hed-type-anchor) Docs in process
* [**Merge events**](merge-events-anchor) Docs in process
+ * [**Remap columns**](remap-columns-anchor) Docs in process
* [**Remove columns**](remove-columns-anchor)
* [**Rename columns**](rename-columns-anchor)
* [**Reorder columns**](reorder-columns-anchor)
@@ -32,7 +32,14 @@ row modifications, column modifications, and structure modifications.
Cleanup operations include: *rename_columns*, *reorder_columns*, and *remove_columns*.
-#### Row modifications
+#### Row and columns
+
+*factor_column*, *factor_hed_tags*, and *factor_hed_type*
+
+#### Restructuring
+
+Restructuring operations include: *add_structure_column*, *add_structure_events*,
+*add_structure_numbers*, *merge_events*, *remap_columns*, and *split_event*
(installation-of-remodeling-tools-anchor)=
## Installation of remodeling tools
@@ -218,61 +225,6 @@ The results of executing this *add_structure_numbers* command on the [sample eve
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
-(derive-column-anchor)=
-### Derive column
-
-**NOT WRITTEN - PLACEHOLDER**
-
-Create a new column or overwrite values in an existing column using a mapping from existing columns.
-This command can be used to overwrite values particular values in existing columns
-based on predefined combinations of values in other columns.
-
-
-(parameters-for-derive-column-anchor)=
-```{admonition} Parameters for the *derive_column* command.
-:class: tip
-
-| Parameter | Type | Description |
-| ------------ | ---- | ----------- |
-| *column_name* | str | The name of the column to be created or modified.|
-| *source_columns* | list of str | A list of columns to be used for remapping. |
-| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
-```
-The *derive_column* command in the following example specifies . . .
-
-````{admonition} An example *derive_column* command.
-:class: tip
-
-```json
-{
- "command": "derive_column"
- "description": "xxx"
- "parameters": {
- "column_name": "match_side",
- "source_columns": ["response_accuracy", "response_hand"],
- "mapping": {
- "left": [["correct", "left"], ["incorrect", "right"]],
- "right": [["correct", "right"], ["incorrect", "left"]]
- }
- }
-}
-```
-````
-
-The results of executing the previous *derive_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-
-````{admonition} Adding a *match_side* column using the *derive_column* command.
-
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
-| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
-| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
-````
-
(factor-column-anchor)=
### Factor column
@@ -287,14 +239,15 @@ If no values are specified, all unique values in that column are factored.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
| *column_name* | str | The name of the column to be factored.|
-| *factor_values* | list | A list of column values to be included as factors. |
-| *factor_names* | list| A list of column names for created factors
of the same length as factor_values. |
-| *ignore_missing* | bool | If true, columns corresponding to factor values
that do not appear in column are included. |
-| *overwrite_existing* | bool | If true an existing factor column is overwritten. |
+| *factor_values* | list | Column values to be included as factors. |
+| *factor_names* | list| Column names for created factors. Must be the same length as *factor_values*. |
+| *ignore_missing* | bool | If true, include columns for factor values not in events. |
+| *overwrite_existing* | bool | If true, existing factor columns are overwritten. |
```
The *factor_column* command in the following example specifies that factor columns
should be created for *succesful_stop* and *unsuccesful_stop* of the *trial_type* column.
The resulting columns are called *stopped* and *stop_failed*, respectively.
+
If the *factor_values* is an empty list,
factors are created for all unique values in the *column_name* column.
The *factor_names* parameters must be the same length as *factor_values*.
@@ -337,9 +290,12 @@ The results of executing this *factor_column* command on the [sample events file
(factor-hed-tags-anchor)=
### Factor HED tags
-**NOT WRITTEN - PLACEHOLDER**
-
-Produce a list of factor columns based on the specified HED condition-variable values.
+Produce a one-hot factor based on a HED tag search.
+The search is based on a list of query filters, which are applied in succession
+to the assembled HED strings for the event file.
+Only events that satisfy each query filter as applied in succession
+will have 1 for the factors.
+If an event fails one of the queries it does not get a factor
(parameters-for-factor-hed-tags-anchor)=
```{admonition} Parameters for *factor_hed_tags* command.
@@ -347,9 +303,11 @@ Produce a list of factor columns based on the specified HED condition-variable v
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| *column_name* | str | The name of the column to be created or modified.|
-| *source_columns* | list of str | A list of columns to be used for remapping. |
-| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *factor_name* | str | Name of the column to create for the factor. |
+| *remove_types* | list | Structural HED tags to be removed (usually *Condition-variable* and *Task*). |
+| *filter_queries* | list | Queries to be applied in succession to filter. |
+| *overwrite_existing* | bool | Overwrite the contents of factor_name column. |
+
```
The *factor_hed-tags* command in the following example specifies . . .
@@ -410,11 +368,10 @@ For additional information on how to encode experimental designs using HED pleas
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| *type_tag* | str | A HED tag used to produce the factors (most commonly *Condition-variable*).|
-| *type_values* | list | A list of values to factor for the *type_tag*.
If empty all values of that type_tag are used. |
-| *overwrite_existing* | bool | If true, an existing factor columns is overwritten. |
-| *include_hed_strings* | bool | If true, a column *hed_expand* with HED strings is included. |
-| *one_hot_factors* | bool | If true, the factors use one-hot representation (zeros and ones). |
+| *type_tag* | str | HED tag used to find the factors (most commonly *Condition-variable*).|
+| *type_values* | list | Values to factor for the *type_tag*.
If empty all values of that type_tag are used. |
+| *overwrite_existing* | bool | If true, existing factor columns are overwritten. |
+| *factor_encoding* | str | Indicates type of encoding. Valid encodings are 'categorical' and 'one-hot'. |
```
To simplifyThe *factor_hed_type* command in the following example specifies . . .
@@ -430,8 +387,7 @@ To simplifyThe *factor_hed_type* command in the following example specifies . .
"type_tag": "Condition-variable",
"type_values": [],
"overwrite_existing": true,
- "include_hed_strings": false,
- "one_hot_factors": true
+ "factor_encoding": "one-hot"
}
}
```
@@ -534,6 +490,64 @@ The results of executing the previous *merge_events* command on the [sample even
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
+
+(remap-columns-anchor)=
+### Remap columns
+
+This command maps the values that appear in a specified m columns of an event file
+into values in n columns using a defined mapping.
+This is often used for recoding the event file.
+The mapping must have targets for all combinations of values that appear in the m columns.
+Create a new column or overwrite values in an existing column using a mapping from existing columns.
+This command can be used to overwrite values particular values in existing columns
+based on predefined combinations of values in other columns.
+
+
+(parameters-for-remap-columns-anchor)=
+```{admonition} Parameters for the *remap_columns* command.
+:class: tip
+
+| Parameter | Type | Description |
+| ------------ | ---- | ----------- |
+| *column_name* | str | The name of the column to be created or modified.|
+| *source_columns* | list of str | A list of columns to be used for remapping. |
+| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+```
+The *remap_columns* command in the following example specifies . . .
+
+````{admonition} An example *remap_columns* command.
+:class: tip
+
+```json
+{
+ "command": "remap_columns"
+ "description": "xxx"
+ "parameters": {
+ "column_name": "match_side",
+ "source_columns": ["response_accuracy", "response_hand"],
+ "mapping": {
+ "left": [["correct", "left"], ["incorrect", "right"]],
+ "right": [["correct", "right"], ["incorrect", "left"]]
+ }
+ }
+}
+```
+````
+
+The results of executing the previous *derive_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+
+````{admonition} Adding a *match_side* column using the *remap_columns* command.
+
+| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+````
+
(remove-columns-anchor)=
### Remove columns
diff --git a/docs/source/HedConditionsAndDesignMatrices.md b/docs/source/HedConditionsAndDesignMatrices.md
index 3772a90..00072e2 100644
--- a/docs/source/HedConditionsAndDesignMatrices.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -229,22 +229,22 @@ Dataset-wide summaries can also be extracted.
"variable_type": "condition-variable",
"levels": 0,
"direct_references": 3,
- "total events": 5,
- "number events": 3,
- "number_multiple": 0,
- "multiple maximum": 1,
- "level counts": {}
+ "total_events": 5,
+ "number_type_events": 3,
+ "number_multiple_events": 0,
+ "multiple_event_maximum": 1,
+ "level_counts": {}
},
"face-cond": {
"name": "face-cond",
"variable_type": "condition-variable",
"levels": 0,
"direct_references": 2,
- "total events": 5,
- "number events": 2,
- "number_multiple": 0,
- "multiple maximum": 1,
- "level counts": {}
+ "total_events": 5,
+ "number_type_events": 2,
+ "number_multiple_events": 0,
+ "multiple_event_maximum": 1,
+ "level_counts": {}
}
}
````
@@ -296,8 +296,8 @@ which address both of these disadvantages.
},
"my_definitions": {
"HED": {
- "house_cond_def": (Definition/House-cond, (Condition-variable/Presentation-type, (Image, Building/House))),
- "face_cond_def": (Definition/Face-cond, (Condition-variable/Presentation-type, (Image, Face)))"
+ "house_cond_def": "(Definition/House-cond, (Condition-variable/Presentation-type, (Image, Building/House)))",
+ "face_cond_def": "(Definition/Face-cond, (Condition-variable/Presentation-type, (Image, Face)))"
}
```
````
@@ -328,11 +328,11 @@ define the meaning of the conditions.
"variable_type": "condition-variable",
"levels": 2,
"direct_references": 0,
- "total events": 5,
- "number events": 5,
- "number_multiple": 0,
- "multiple maximum": 1,
- "level counts": {
+ "total_events": 5,
+ "number_type_events": 5,
+ "number_multiple_events": 0,
+ "multiple_event_maximum": 1,
+ "level_counts": {
"house-cond": 3,
"face-cond": 2
}
@@ -368,9 +368,13 @@ to indicate that the presented face had above average symmetry.
The key assignment was held constant for each recording, but the key choice was
counter-balanced across participants.
+Example 8 shows an excerpt from the event file of sub-002 run-1.
+(You may find it useful to look at the full event file [sub-002_task-FacePerception_run-1_events.tsv](./_static/data/sub-002_task-FacePerception_run-1_events.tsv) and the dataset's
+JSON sidecar with full HED annotations:
+[task-facePerception_events.json](./_static/data/task-FacePerception_events.json)
(sample-design-matrix-events-file-anchor)=
-```{admonition} Example 8: An excerpt from the Wakeman-Henson face-processing dataset..
+```{admonition} Example 8: An excerpt from the Wakeman-Henson face-processing dataset.
| onset | duration | event_type | face_type | rep_status | trial | rep_lag | value | stim_file |
| ----- | -------- | ---------- | --------- | ---------- | ----- | ------- | ----- | --------- |
@@ -386,72 +390,195 @@ counter-balanced across participants.
| 30.3571 | n/a | show_face | unfamiliar_face | first_show | 3 | n/a | 13 | u088.bmp |
```
-Example 8 illustrates two different ways of using defined conditions for encoding.
-The key assignment is marked by inserting an event with temporal extent at the beginning
-of the file. The *setup_right_sym* event is encoded in the JSON sidecar as:
+Example 8 illustrates two different ways of using defined conditions for encoding:
+**inserting an event with temporal extent** or using **column encoding**.
-The condition variab
+The key assignment condition is marked by inserting an event with *event_type* equal to
+*setup_right_sym* at the beginning of the file.
+As we shall see below, this event is annotated with having temporal extent,
+as defined by HED *Onset* and *Offset* tags,
+so the condition is in effect until the event's extent ends.
-```{admonition} Example 9: HED tools automatic extraction of the design matrix in categorical form for Example 8.
+In the column strategy, an event file column represents the condition variable,
+and the values in that column represent the levels.
+With this encoding, the condition variable is only applicable at a particular
+level when that level name appears in the column.
+An n/a value in that column indicates the condition does not apply to that event.
-| onset | key-assignment | face-type | repetition-type |
-| ----- | -------------- | ---- ---- | --------------- |
-| 0.004 | right-sym-com | n/a | n/a |
-| 24.2098 | right-sym-com | unfamiliar-face-cond | first-show-cond |
-| 25.0353 | right-sym-com | n/a | n/a |
-| 25.158 | right-sym-com | n/a| n/a |
-| 26.7353 | right-sym-com | n/a | n/a |
-| 27.2498 | right-sym-com | unfamiliar-face-cond | immediate-repeat-cond |
-| 27.8971 | right-sym-com | n/a | n/a |
-| 28.0998 | right-sym-com | n/a | n/a |
-| 29.7998 | right-sym-com | n/a | n/a |
-| 30.3571 | right-sym-com | unfamiliar-face-cond | first-show-cond |
+Example 9 shows the portion of the
+[**task-facePerception_events.json**](./_static/data/task-FacePerception_events.json)
+that encodes information about the *setup_right_sym* event found as the first event
+in the event file excerpt of Example 8.
+This file contains definitions for all the condition variables used in the dataset.
+
+
+````{admonition} Example 9: Excerpt of the JSON sidecar relevant to the *setup_right_sym* event.
+:class: tip
+
+```json
+{
+ "event_type": {
+ "HED": {
+ "setup_right_sym": "Experiment-structure, (Def/Right-sym-cond, Onset), (Def/Initialize-recording, Onset)"
+ }
+ },
+ "hed_def_conds": {
+ "HED": {
+ "right_sym_cond_def": "(Definition/Right-sym-cond, (Condition-variable/Key-assignment, ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)), ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical)), Description/Right index finger key press indicates a face with above average symmetry.))"
+ }
+ }
+}
```
+````
+
+Only the *event_type* column is relevant for assembling the annotations for the first row
+of Example 8, since the other annotated columns have n/a values.
+The assembled HED annotation for the first row of Example 8 is shown in Example 10.
+
+````{admonition} Example 10: The HED annotation of the first row of Example 8.
+:class: tip
+> "*Experiment-structure*,
+> (*Def/Right-sym-cond*, *Onset*),
+> (*Def/Initialize-recording*, *Onset*)"
+
+````
+HED represents events of temporal extent using HED definitions with the *Onset*
+and *Offset* tags grouped with a user-defined term.
+The (*Def/Right-sym-cond*, *Onset*) specifies that an event defined by
+*Right-sym-cond* begins at the time-marker represented by this row in the event file.
+This event continues until the end of the file or until an event marker with
+(*Def/Right-sym-cond*, *Offset*) occurs.
+In this case, no *Offset* marker for *Right-sym-cond* appears in the file,
+so the event represented by *Right-sym-cond* occurs over the entire recording.
+The user-defined term is prefixed with *Def/* and indicates what the event
+of temporal extent represents.
+If the definition includes a *Condition-variable*,
+then the event represents the occurrence of that experimental condition.
+The user-defined terms are usually defined in the `events.json` file
+located at the top-level of the BIDS dataset.
+
+Example 11 shows a more readable form for the definition of *Right-sym-cond*.
+
+````{admonition} Example 11: The contents of the definition for *Right-sym-cond*.
+:class: tip
+
+```text
+(
+ Definition/Right-sym-cond, (
+ Condition-variable/Key-assignment,
+ ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)),
+ ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical)),
+ Description/Right index finger key press indicates a face with above average symmetry.
+ )
+)
+```
+````
+The primary use of the definitions for condition variables is to encode
+the experimental design in an actionable format.
+Thus, as a general practice, *Defs* representing condition variables are
+removed prior to searching for other tags to avoid repeats.
+Notice that both *Right-side-of* and *Left-side-of* appear in the definition.
+Thus, if these *Defs* were included, every event would have both left and right tags.
+
+Once a dataset includes the appropriate annotations,
+HED tools can automatically extract the experimental design.
+Example 12 shows the result of extraction of categorical factor vectors for
+the event file of Example 8.
+
+```{admonition} Example 12: HED tools categorical form extraction of the design matrix for Example 8.
+
+| onset | key-assignment | face-type | repetition-type |
+| ----- | -------------- | --------- | --------------- |
+| 0.004 | right-sym-cond | n/a | n/a |
+| 24.2098 | right-sym-cond | unfamiliar-face-cond | first-show-cond |
+| 25.0353 | right-sym-cond | n/a | n/a |
+| 25.158 | right-sym-cond | n/a | n/a |
+| 26.7353 | right-sym-cond | n/a | n/a |
+| 27.2498 | right-sym-cond | unfamiliar-face-cond | immediate-repeat-cond |
+| 27.8971 | right-sym-cond | n/a | n/a |
+| 28.0998 | right-sym-cond | n/a | n/a |
+| 29.7998 | right-sym-cond | n/a | n/a |
+| 30.3571 | right-sym-cond | unfamiliar-face-cond | first-show-cond |
+
+````
+
+In the categorical representation,
+HED uses the condition variable name as the column name.
+The level values appear in the columns for event markers at which
+the condition variable at that level applies.
+Notice that *right-sym-cond* appears in every row because it was used in an event
+that extended to the end of the file.
+On the other hand, the other condition variables were encoded using
+columns and only appear when present in the column.
+
+Note that if an event has multiple levels of the same condition,
+categorical and ordinal encoding cannot be used.
+Only one-hot encoding supports multiple levels in the same event.
+
+Example 13 below shows the condition variable summary that HED produces for the
+full [sub-002_task-FacePerception_run-1_events.tsv](./_static/data/sub-002_task-FacePerception_run-1_events.tsv)
+and JSON sidecar
+[task-facePerception_events.json](./_static/data/task-FacePerception_events.json).
+
+````{admonition} Example 13: The condition variable summary extracted from the full event file.
+:class: tip
+
+```json
{
- "key-assignment": {
- "name": "key-assignment",
- "variable_type": "condition-variable",
- "levels": 1,
- "direct_references": 0,
- "total events": 200,
- "number events": 200,
- "number_multiple": 0,
- "multiple maximum": 1,
- "level counts": {
- "right-sym-cond": 200
- }
- },
- "face-type": {
- "name": "face-type",
- "variable_type": "condition-variable",
- "levels": 3,
- "direct_references": 0,
- "total events": 200,
- "number events": 52,
- "number_multiple": 0,
- "multiple maximum": 1,
- "level counts": {
- "unfamiliar-face-cond": 20,
- "famous-face-cond": 14,
- "scrambled-face-cond": 18
- }
- },
- "repetition-type": {
- "name": "repetition-type",
- "variable_type": "condition-variable",
- "levels": 3,
- "direct_references": 0,
- "total events": 200,
- "number events": 52,
- "number_multiple": 0,
- "multiple maximum": 1,
- "level counts": {
- "first-show-cond": 28,
- "immediate-repeat-cond": 12,
- "delayed-repeat-cond": 12
- }
+ "key-assignment": {
+ "name": "key-assignment",
+ "variable_type": "condition-variable",
+ "levels": 1,
+ "direct_references": 0,
+ "total_events": 552,
+ "number_type_events": 552,
+ "number_multiple_events": 0,
+ "multiple_event_maximum": 1,
+ "level_counts": {
+ "right-sym-cond": 552
+ }
+ },
+ "face-type": {
+ "name": "face-type",
+ "variable_type": "condition-variable",
+ "levels": 3,
+ "direct_references": 0,
+ "total_events": 552,
+ "number_type_events": 146,
+ "number_multiple_events": 0,
+ "multiple_event_maximum": 1,
+ "level_counts": {
+ "unfamiliar-face-cond": 47,
+ "famous-face-cond": 49,
+ "scrambled-face-cond": 50
+ }
+ },
+ "repetition-type": {
+ "name": "repetition-type",
+ "variable_type": "condition-variable",
+ "levels": 3,
+ "direct_references": 0,
+ "total_events": 552,
+ "number_type_events": 146,
+ "number_multiple_events": 0,
+ "multiple_event_maximum": 1,
+ "level_counts": {
+ "first-show-cond": 75,
+ "immediate-repeat-cond": 36,
+ "delayed-repeat-cond": 35
+ }
}
-}
\ No newline at end of file
+}
+```
+````
+
+The file has 552 events.
+Since the *key-assignment* condition variable with level *right-sym-cond*
+applies to every event in this file, the *number_type_events* is also 552.
+On the other hand, the *face-type* condition variable is only applicable in 146 events.
+
+All the condition variables have *number_multiple_events* equal to 0,
+so any of the three possible encodings: categorical, ordinal, or one-hot can be used.
\ No newline at end of file
diff --git a/docs/source/_static/data/task-FacePerception_events.json b/docs/source/_static/data/task-FacePerception_events.json
new file mode 100644
index 0000000..fa018c4
--- /dev/null
+++ b/docs/source/_static/data/task-FacePerception_events.json
@@ -0,0 +1,138 @@
+{
+ "onset": {
+ "Description": "Position of event marker in seconds relative to the start.",
+ "Units": "s"
+ },
+ "duration": {
+ "Description": "Duration of the event in seconds.",
+ "Units": "s"
+ },
+ "event_type": {
+ "LongName": "Event category",
+ "Description": "The main category of the event.",
+ "Levels": {
+ "show_face": "Display a face to mark end of pre-stimulus and start of blink-inhibition.",
+ "show_face_initial": "Display a face at the beginning of the recording.",
+ "show_circle": "Display a white circle to mark end of the stimulus and blink inhibition.",
+ "show_cross": "Display only a white cross to mark start of trial and fixation.",
+ "left_press": "Experiment participant presses a key with left index finger.",
+ "right_press": "Experiment participant presses a key with right index finger.",
+ "setup_left_sym": "Setup for experiment with pressing key with left index finger means a face with above average symmetry.",
+ "setup_right_sym": "Setup for experiment with pressing key with right index finger means a face with above average symmetry.",
+ "double_press": "Experiment participant presses both keys ."
+ },
+ "HED": {
+ "show_face": "Sensory-event, Experimental-stimulus, (Def/Face-image, Onset), (Def/Blink-inhibition-task,Onset),(Def/Cross-only, Offset)",
+ "show_face_initial": "Sensory-event, Experimental-stimulus, (Def/Face-image, Onset), (Def/Blink-inhibition-task,Onset), (Def/Fixation-task, Onset)",
+ "show_circle": "Sensory-event, (Intended-effect, Cue), (Def/Circle-only, Onset), (Def/Face-image, Offset), (Def/Blink-inhibition-task, Offset), (Def/Fixation-task, Offset)",
+ "show_cross": "Sensory-event, (Intended-effect, Cue), (Def/Cross-only, Onset), (Def/Fixation-task, Onset), (Def/Circle-only, Offset)",
+ "left_press": "Agent-action, Participant-response, Def/Press-left-finger",
+ "right_press": "Agent-action, Participant-response, Def/Press-right-finger",
+ "setup_left_sym": "Experiment-structure, (Def/Left-sym-cond, Onset), (Def/Initialize-recording, Onset)",
+ "setup_right_sym": "Experiment-structure, (Def/Right-sym-cond, Onset), (Def/Initialize-recording, Onset)",
+ "double_press": "Agent-action, Indeterminate-action, (Press, Keyboard-key)"
+ }
+ },
+ "face_type": {
+ "Description": "Factor indicating type of face image being displayed.",
+ "Levels": {
+ "famous_face": "A face that should be recognized by the participants.",
+ "unfamiliar_face": "A face that should not be recognized by the participants.",
+ "scrambled_face": "A scrambled face image generated by taking face 2D FFT."
+ },
+ "HED": {
+ "famous_face": "Def/Famous-face-cond",
+ "unfamiliar_face": "Def/Unfamiliar-face-cond",
+ "scrambled_face": "Def/Scrambled-face-cond"
+ }
+ },
+ "rep_status": {
+ "Description": "Factor indicating whether this image has been already seen.",
+ "Levels": {
+ "first_show": "Factor level indicating the first display of this face.",
+ "immediate_repeat": "Factor level indicating this face was the same as previous one.",
+ "delayed_repeat": "Factor level indicating face was seen 5 to 15 trials ago."
+ },
+ "HED": {
+ "first_show": "Def/First-show-cond",
+ "immediate_repeat": "Def/Immediate-repeat-cond",
+ "delayed_repeat": "Def/Delayed-repeat-cond"
+ }
+ },
+ "trial": {
+ "Description": "Indicates which trial this event belongs to.",
+ "HED": "Experimental-trial/#"
+ },
+ "rep_lag": {
+ "Description": "How face images before this one was the image was previously presented.",
+ "HED": "(Face, Item-interval/#)"
+ },
+ "stim_file": {
+ "Description": "Path of the stimulus file in the stimuli directory.",
+ "HED": "(Image, Pathname/#)"
+ },
+ "hed_def_sensory": {
+ "Description": "Metadata dictionary for gathering sensory definitions",
+ "HED": {
+ "cross_only_def": "(Definition/Cross-only, (Visual-presentation, (Foreground-view, (White, Cross), (Center-of, Computer-screen)), (Background-view, Black), Description/A white fixation cross on a black background in the center of the screen.))",
+ "face_image_def": "(Definition/Face-image, (Visual-presentation, (Foreground-view, ((Image, Face, Hair), Color/Grayscale), ((White, Cross), (Center-of, Computer-screen))), (Background-view, Black), Description/A happy or neutral face in frontal or three-quarters frontal pose with long hair cropped presented as an achromatic foreground image on a black background with a white fixation cross superposed.))",
+ "circle_only_def": "(Definition/Circle-only, (Visual-presentation, (Foreground-view, ((White, Circle), (Center-of, Computer-screen))), (Background-view, Black), Description/A white circle on a black background in the center of the screen.))"
+ }
+ },
+ "hed_def_actions": {
+ "Description": "Metadata dictionary for gathering participant action definitions",
+ "HED": {
+ "press_left_finger_def": "(Definition/Press-left-finger, ((Index-finger, (Left-side-of, Experiment-participant)), (Press, Keyboard-key), Description/The participant presses a key with the left index finger to indicate a face symmetry judgment.))",
+ "press_right_finger_def": "(Definition/Press-right-finger, ((Index-finger, (Right-side-of, Experiment-participant)), (Press, Keyboard-key), Description/The participant presses a key with the right index finger to indicate a face symmetry evaluation.))"
+ }
+ },
+ "hed_def_conds": {
+ "Description": "Metadata dictionary for gathering experimental condition definitions",
+ "HED": {
+ "famous_face_cond_def": "(Definition/Famous-face-cond, (Condition-variable/Face-type, (Image, (Face, Famous)), Description/A face that should be recognized by the participants))",
+ "unfamiliar_face_cond_def": "(Definition/Unfamiliar-face-cond, (Condition-variable/Face-type, (Image, (Face, Unfamiliar)), Description/A face that should not be recognized by the participants.))",
+ "scrambled_face_cond_def": "(Definition/Scrambled-face-cond, (Condition-variable/Face-type, (Image, (Face, Disordered)), Description/A scrambled face image generated by taking face 2D FFT.))",
+ "first_show_cond_def": "(Definition/First-show-cond, ((Condition-variable/Repetition-type, (Item-count/1, Face), Item-interval/0), Description/Factor level indicating the first display of this face.))",
+ "immediate_repeat_cond_def": "(Definition/Immediate-repeat-cond, ((Condition-variable/Repetition-type, (Item-count/2, Face), Item-interval/1), Description/Factor level indicating this face was the same as previous one.))",
+ "delayed_repeat_cond_def": "(Definition/Delayed-repeat-cond, (Condition-variable/Repetition-type, (Item-count/2, Face), (Item-interval, (Greater-than-or-equal-to, Item-interval/5)), Description/Factor level indicating face was seen 5 to 15 trials ago.))",
+ "left_sym_cond_def": "(Definition/Left-sym-cond, (Condition-variable/Key-assignment, ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)), ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical)), Description/Left index finger key press indicates a face with above average symmetry.))",
+ "right_sym_cond_def": "(Definition/Right-sym-cond, (Condition-variable/Key-assignment, ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)), ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical)), Description/Right index finger key press indicates a face with above average symmetry.))"
+ }
+ },
+ "hed_def_tasks": {
+ "Description": "Metadata dictionary for gathering task definitions",
+ "HED": {
+ "face_symmetry_evaluation_task_def": "(Definition/Face-symmetry-evaluation-task, (Task, Experiment-participant, (See, Face), (Discriminate, (Face, Symmetrical)), (Press, Keyboard-key), Description/Evaluate degree of image symmetry and respond with key press evaluation.))",
+ "blink_inhibition_task_def": "(Definition/Blink-inhibition-task, (Task, Experiment-participant, Inhibit-blinks, Description/Do not blink while the face image is displayed.))",
+ "fixation_task_def": "(Definition/Fixation-task, (Task, Experiment-participant, (Fixate, Cross), Description/Fixate on the cross at the screen center.))"
+ }
+ },
+ "hed_def_setup": {
+ "Description": "Metadata dictionary for gathering setup definitions",
+ "HED": {
+ "setup_def": "(Definition/Initialize-recording, (Recording))"
+ }
+
+ },
+ "value": {
+ "Description": "Numerical event marker",
+ "Levels": {
+ "x0": "Disappearance of face image and display of the inter-stimulus circle simultaneously",
+ "x1": "Disappearance of face image and display of the inter-stimulus circle simultaneously",
+ "x2": "Initial setup with left finger key press indicating above average symmetry",
+ "x3": "Initial setup with right finger key press indicating above average symmetry",
+ "x5": "Initial presentation of famous face",
+ "x6": "Immediate repeated presentation of famous face",
+ "x7": "Delayed repeated presentation of famous face",
+ "x13": "Initial presentation of unfamiliar face",
+ "x14": "Immediate repeated presentation of unfamiliar face",
+ "x15": "Delayed repeated presentation of unfamiliar face",
+ "x17": "Initial presentation of scrambled face",
+ "x18": "Immediate repeated presentation of scrambled face",
+ "x19": "Delayed repeated presentation of scrambled face",
+ "x256": "Left finger key press",
+ "x4096": "Right finger key press",
+ "x4352": "Left and right finger key presses"
+ }
+ }
+}
diff --git a/docs/source/package.json b/docs/source/package.json
index 28539dd..3cd6b26 100644
--- a/docs/source/package.json
+++ b/docs/source/package.json
@@ -1,14 +1,12 @@
{
- "event_type": {
- "HED": {
- "house": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Building/House), Condition-variable/House-cond",
- "face": "Sensory-presentation, Visual-presentation, Experimental-stimulus, (Image, Face), Condition-variable/Face-cond"
- }
- },
- "response_time": {
- "HED": "Participant-response, Delay/#"
- },
- "stim_file": {
- "HED": "(Image, Pathname/#)"
- }
+ "event_type": {
+ "HED": {
+ "setup_right_sym": "Experiment-structure, (Def/Right-sym-cond, Onset), (Def/Initialize-recording, Onset)"
+ }
+ },
+ "hed_def_conds": {
+ "HED": {
+ "right_sym_cond_def": "(Definition/Right-sym-cond, (Condition-variable/Key-assignment, ((Index-finger, (Right-side-of, Experiment-participant)), (Behavioral-evidence, Symmetrical)), ((Index-finger, (Left-side-of, Experiment-participant)), (Behavioral-evidence, Asymmetrical)), Description/Right index finger key press indicates a face with above average symmetry.))"
+ }
+ }
}
From c72873fc22c8466b2a56258907e02a048234e124 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Tue, 2 Aug 2022 17:44:26 -0500
Subject: [PATCH 011/143] Added implementation of remap_columns
---
docs/source/EventFileRestructuring.md | 68 +++---
docs/source/HedConditionsAndDesignMatrices.md | 201 +++++++++---------
2 files changed, 142 insertions(+), 127 deletions(-)
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index 559010b..747346d 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -61,7 +61,7 @@ stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneu
````{admonition} Excerpt from event file for a stop-go task of AOMIC-PIOP2 (ds002790).
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
-| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | |correct | right | female
| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
@@ -494,13 +494,11 @@ The results of executing the previous *merge_events* command on the [sample even
(remap-columns-anchor)=
### Remap columns
-This command maps the values that appear in a specified m columns of an event file
-into values in n columns using a defined mapping.
-This is often used for recoding the event file.
-The mapping must have targets for all combinations of values that appear in the m columns.
-Create a new column or overwrite values in an existing column using a mapping from existing columns.
-This command can be used to overwrite values particular values in existing columns
-based on predefined combinations of values in other columns.
+This command maps the values that appear in a specified *m* columns of an event file
+into values in *n* columns using a defined mapping.
+This command is often used for recoding the event file.
+The mapping should have targets for all combinations of values that appear in the *m* columns.
+
(parameters-for-remap-columns-anchor)=
@@ -509,45 +507,57 @@ based on predefined combinations of values in other columns.
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| *column_name* | str | The name of the column to be created or modified.|
-| *source_columns* | list of str | A list of columns to be used for remapping. |
-| *mapping* | dict | The keys are the values to be placed in the derived columns and the values are each an array |
+| *source_columns* | list | Columns with combinations of values to be mapped.|
+| *destination_columns* | list | Columns to be mapped into. |
+| *map_list* | list | A list. Each element consists n + m elements
corresponding to the lengths of the source and destination lists respectively. |
+| *ignore_missing* | bool | If false, a combination of
```
-The *remap_columns* command in the following example specifies . . .
+The *map_list* parameter specifies how each unique combination of values from the source
+columns will be mapped into the destination columns.
+If there are *m* source columns and *n* destination columns,
+then each entry in *map_list must be a list with *n* + *m* elements.
+
+The *remap_columns* command in the following example creates a new column called *response_type*
+based on the unique values in the combination of columns *response_accuracy* and *response_hand*.
````{admonition} An example *remap_columns* command.
:class: tip
```json
{
- "command": "remap_columns"
- "description": "xxx"
+ "command": "remap_columns",
+ "description": "Map response_accuracy and response hand into a single column.",
"parameters": {
- "column_name": "match_side",
"source_columns": ["response_accuracy", "response_hand"],
- "mapping": {
- "left": [["correct", "left"], ["incorrect", "right"]],
- "right": [["correct", "right"], ["incorrect", "left"]]
- }
+ "destination_columns": ["response_type"],
+ "map_list": [["correct", "left", "correct_left"],
+ ["correct", "right", "correct_right"],
+ ["incorrect", "left", "incorrect_left"],
+ ["incorrect", "right", "incorrect_left"],
+ ["n/a", "n/a", "n/a"]],
+ "ignore_missing": true
}
}
```
````
-The results of executing the previous *derive_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *remap_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Adding a *match_side* column using the *remap_columns* command.
+````{admonition} Mapping columns *response_accuracy* and *response_hand* into a *response_type* column.
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | right | female |
-| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
-| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | response_type |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | --- | ------------------- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | correct_right |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | correct_right |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | correct_right |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | n/a |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | correct_left |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | correct_left |
````
+Typically, the *remap_columns* command is used often used to map single codes in the experimental log
+into multiple columns in the final events file.
+
(remove-columns-anchor)=
### Remove columns
diff --git a/docs/source/HedConditionsAndDesignMatrices.md b/docs/source/HedConditionsAndDesignMatrices.md
index 00072e2..2e9bedd 100644
--- a/docs/source/HedConditionsAndDesignMatrices.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -14,114 +14,23 @@ the [**BIDS annotation quickstart**](https://hed-examples.readthedocs.io/en/late
[**HED annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/HedAnnotationQuickstart.html)
tutorials as needed.
+The [**Neuorimaging experimental design**](neuroimaging-experimental-anchor)
+section at the end of this tutorial provides a basic introduction to the ideas
+of factor vectors and experimental design if you are unfamiliar with these topics.
-
-* [**Neuroimaging experimental design**](neuroimaging-experimental-anchor)
- * [**Design matrices and factor variables**](design-matrices-and-factor-variables-anchor)
- * [**Types of condition encoding**](types-of-condition-encoding-anchor)
* [**HED annotations for conditions**](hed-annotations-for-conditions-anchor)
* [**Direct condition variables**](direct-condition-variables-anchor)
* [**Defined condition variables**](defined-condition-variables-anchor)
* [**Column vs row conditions**](column-vs-row-conditions-anchor)
+* [**Review of experimental design concepts**](review-of-experimental-design-concepts-anchor)
+ * [**Design matrices and factor variables**](design-matrices-and-factor-variables-anchor)
+ * [**Types of condition encoding**](types-of-condition-encoding-anchor)
This tutorial introduces tools and strategies for including this information
as part of a dataset without excessive effort on the part of the researcher.
The discussion mainly focuses on categorical variables, but HED
also can encode numerical values as discussed later in the tutorial.
-(neuroimaging-experimental-anchor)=
-## Neuroimaging experimental design
-Traditional neuroimaging experiments are carefully designed to control and
-document the external conditions under which the experiment is conducted.
-Often a few items such as the task or the properties of a stimulus are
-systematically varied as the stimulus is presented and participant responses
-are recorded.
-
-For example, in an experiment to test for differences in
-brain responses to pictures of houses versus pictures of faces,
-the researcher would label time points in the recording corresponding
-to presentations of the respective pictures so that differences in
-brain responses between the two types of pictures could be observed.
-An fMRI analysis might determine which brain regions
-showed a significant response differential between the two types of responses.
-An EEG/MEG analysis might also focus on the differences in time courses
-between the responses to the two types of images.
-
-Thus, the starting point for many analyses is the association of
-labels corresponding to different **experimental conditions** with
-time points in the data recording.
-In BIDS, this association is stored an `events.tsv` file paired
-with the data recording,
-but this information may also be stored as part of the recording
-itself, depending on the technology and the format of the recording.
-
-(design-matrices-and-factor-variables-anchor)=
-### Design matrices and factor variables
-
-The type of information included for the experimental conditions
-and how this information is stored depends very much on the experiment.
-Most analysis tools require a vector (sometimes called a **factor vector**)
-of elements associated with the event markers for each type of experimental condition.
-
-For linear modeling and other types of regression, these factor vectors are assembled
-into **design matrix** to use as input for the analysis.
-Design matrices can also include other types of columns depending on the modeling strategy.
-
-(types-of-condition-encoding-anchor)=
-### Types of condition encoding
-
-Consider the simple example introduced above of an experiment which
-varies the stimuli between pictures of houses and faces to measure
-differences in response.
-The following example shows three possible types of encodings
-(**categorical**, **ordinal**, and **one-hot**) that might be sued
-for this association. The table shows an excerpt from a putative events file,
-with the onset column (required by BIDS) containing the time of the event marker
-relative to the start of the associated data recording.
-The duration column (also required by BIDS) contains the duration of the
-image presentation in seconds.
-
-(different-encodings-of-design-variables-anchor)=
-````{admonition} Example 1: Different encodings of a column with categorical values.
-| onset | duration | categorical | ordinal | one_hot.house | one_hot.face |
-| ----- | -------- |----------- |-------- | ------------- | ------------ |
-| 2.010 | 0.1 | house | 1 | 1 | 0 |
-| 3.210 | 0.1 | house | 1 | 1 | 0 |
-| 4.630 | 0.1 | face | 2 | 0 | 1 |
-| 6.012 | 0.1 | house | 1 | 1 | 0 |
-| 7.440 | 0.1 | face | 2 | 0 | 1 |
-````
-
-The **categorical** encoding assigns laboratory-specific names to the
-different types of stimuli.
-In theory, this categorical column consisting of the strings *house* and *face*
-could be used as a factor vector or as part of a design matrix for regression.
-However, many analysis tools require that these names be assigned numerical
-values.
-
-The **ordinal** encoding assigns an arbitrary sequence of numbers corresponding
-to the unique values.
-If there are only 2 values, the values -1 and 1 are often used.
-Ordinal encodings impose an order based on the values
-chosen, which may have undesirable affects on the results of analyses such
-as regression if the ordering/relative sizes do not reflect the
-properties of the encoded experimental conditions.
-
-In the example above, the experimental conditions houses and faces do not
-have an ordering/size relationship reflected by the encoding (house=1, face=2).
-In addition, neither categorical nor ordinal encoding
-can represent items falling into multiple categories of the same condition at the same time.
-For these reasons, many statistical tools require one-hot encoding.
-
-In **one-hot** encoding, each possible value of the condition is represented
-by its own column with 1's representing the presence of that condition value
-and experimental conditions and 0's otherwise. One-hot encodes all values
-without bias and allows for a given event to be a member of multiple categories.
-This representation is required for many machine-learning models.
-A disadvantage is that it can generate a large number of columns if there
-are many unique categorical values. It can also cause a problem if not all
-files contain the same values, as then different files may have different columns.
-
(hed-annotations-for-conditions-anchor)=
## HED annotations for conditions
@@ -581,4 +490,100 @@ applies to every event in this file, the *number_type_events* is also 552.
On the other hand, the *face-type* condition variable is only applicable in 146 events.
All the condition variables have *number_multiple_events* equal to 0,
-so any of the three possible encodings: categorical, ordinal, or one-hot can be used.
\ No newline at end of file
+so any of the three possible encodings: categorical, ordinal, or one-hot can be used.
+
+
+
+(review-of-experimental-design-concepts-anchor)=
+## Review of experimental design concepts
+
+Traditional neuroimaging experiments are carefully designed to control and
+document the external conditions under which the experiment is conducted.
+Often a few items such as the task or the properties of a stimulus are
+systematically varied as the stimulus is presented and participant responses
+are recorded.
+
+For example, in an experiment to test for differences in
+brain responses to pictures of houses versus pictures of faces,
+the researcher would label time points in the recording corresponding
+to presentations of the respective pictures so that differences in
+brain responses between the two types of pictures could be observed.
+An fMRI analysis might determine which brain regions
+showed a significant response differential between the two types of responses.
+An EEG/MEG analysis might also focus on the differences in time courses
+between the responses to the two types of images.
+
+Thus, the starting point for many analyses is the association of
+labels corresponding to different **experimental conditions** with
+time points in the data recording.
+In BIDS, this association is stored an `events.tsv` file paired
+with the data recording,
+but this information may also be stored as part of the recording
+itself, depending on the technology and the format of the recording.
+
+(design-matrices-and-factor-variables-anchor)=
+### Design matrices and factor variables
+
+The type of information included for the experimental conditions
+and how this information is stored depends very much on the experiment.
+Most analysis tools require a vector (sometimes called a **factor vector**)
+of elements associated with the event markers for each type of experimental condition.
+
+For linear modeling and other types of regression, these factor vectors are assembled
+into **design matrix** to use as input for the analysis.
+Design matrices can also include other types of columns depending on the modeling strategy.
+
+(types-of-condition-encoding-anchor)=
+### Types of condition encoding
+
+Consider the simple example introduced above of an experiment which
+varies the stimuli between pictures of houses and faces to measure
+differences in response.
+The following example shows three possible types of encodings
+(**categorical**, **ordinal**, and **one-hot**) that might be sued
+for this association. The table shows an excerpt from a putative events file,
+with the onset column (required by BIDS) containing the time of the event marker
+relative to the start of the associated data recording.
+The duration column (also required by BIDS) contains the duration of the
+image presentation in seconds.
+
+(different-encodings-of-design-variables-anchor)=
+````{admonition} Example 1: Different encodings of a column with categorical values.
+| onset | duration | categorical | ordinal | one_hot.house | one_hot.face |
+| ----- | -------- |----------- |-------- | ------------- | ------------ |
+| 2.010 | 0.1 | house | 1 | 1 | 0 |
+| 3.210 | 0.1 | house | 1 | 1 | 0 |
+| 4.630 | 0.1 | face | 2 | 0 | 1 |
+| 6.012 | 0.1 | house | 1 | 1 | 0 |
+| 7.440 | 0.1 | face | 2 | 0 | 1 |
+````
+
+The **categorical** encoding assigns laboratory-specific names to the
+different types of stimuli.
+In theory, this categorical column consisting of the strings *house* and *face*
+could be used as a factor vector or as part of a design matrix for regression.
+However, many analysis tools require that these names be assigned numerical
+values.
+
+The **ordinal** encoding assigns an arbitrary sequence of numbers corresponding
+to the unique values.
+If there are only 2 values, the values -1 and 1 are often used.
+Ordinal encodings impose an order based on the values
+chosen, which may have undesirable affects on the results of analyses such
+as regression if the ordering/relative sizes do not reflect the
+properties of the encoded experimental conditions.
+
+In the example above, the experimental conditions houses and faces do not
+have an ordering/size relationship reflected by the encoding (house=1, face=2).
+In addition, neither categorical nor ordinal encoding
+can represent items falling into multiple categories of the same condition at the same time.
+For these reasons, many statistical tools require one-hot encoding.
+
+In **one-hot** encoding, each possible value of the condition is represented
+by its own column with 1's representing the presence of that condition value
+and experimental conditions and 0's otherwise. One-hot encodes all values
+without bias and allows for a given event to be a member of multiple categories.
+This representation is required for many machine-learning models.
+A disadvantage is that it can generate a large number of columns if there
+are many unique categorical values. It can also cause a problem if not all
+files contain the same values, as then different files may have different columns.
From 4611d531a17850d07c2655a0280208ab6d913096 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Thu, 4 Aug 2022 08:50:21 -0500
Subject: [PATCH 012/143] Removed the add trial numbers from split_events
---
docs/source/EventFileRestructuring.md | 34 +++++-----
docs/source/HedConditionsAndDesignMatrices.md | 64 ++++++++++---------
2 files changed, 51 insertions(+), 47 deletions(-)
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index 747346d..d66706c 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -809,7 +809,6 @@ Unlisted columns are filled with n/a.
| ------------ | ---- | ----------- |
| *anchor_event* | str | The name of the column that will be used for split-event codes.|
| *new_events* | dict | Dictionary whose keys are the codes to be inserted as new events
and whose values are dictionaries with
keys *onset_source*, *duration*, and *copy_columns*. |
-| *add_event_numbers* | bool | If true, adds a column called *event_numbers*. |
| *remove_parent_event* | bool | If true, remove parent event. |
```
@@ -829,7 +828,6 @@ since these items have been unfolded into separate events.
"description": "add response events to the trials.",
"parameters": {
"anchor_column": "trial_type",
- "event_numbers_column": "trial_number",
"new_events": {
"response": {
"onset_source": ["response_time"],
@@ -852,22 +850,22 @@ The results of executing this *split_event* command on the [sample events file](
````{admonition} Results of the previous *split_event* command.
-| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | trial_number |
-| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | -------- |
-| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | 1 |
-| 0.6426 | 0 | response | n/a | n/a | correct | right | female | 1 |
-| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | 2 |
-| 5.7774 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a | 2 |
-| 6.0674 | 0 | response | n/a | n/a | correct | right | female | 2 |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 3 |
-| 10.0356 | 0 | response | n/a | n/a | correct | right | female | 3 |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | 4 |
-| 13.7939 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a | 4 |
-| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | 5 |
-| 17.3521 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a | 5 |
-| 17.7351 | 0 | response | n/a | n/a | correct | left | male | 5 |
-| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | 6 |
-| 22.0533 | 0 | response | n/a | n/a | correct | left | male | 6 |
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
+| 0.6426 | 0 | response | n/a | n/a | correct | right | female |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female |
+| 5.7774 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a |
+| 6.0674 | 0 | response | n/a | n/a | correct | right | female |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
+| 10.0356 | 0 | response | n/a | n/a | correct | right | female |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
+| 13.7939 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male |
+| 17.3521 | 0.5 | stop_signal | n/a | n/a | n/a | n/a | n/a |
+| 17.7351 | 0 | response | n/a | n/a | correct | left | male |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
+| 22.0533 | 0 | response | n/a | n/a | correct | left | male |
````
Note that the event numbers are added before the splitting and then
diff --git a/docs/source/HedConditionsAndDesignMatrices.md b/docs/source/HedConditionsAndDesignMatrices.md
index 2e9bedd..d9fd124 100644
--- a/docs/source/HedConditionsAndDesignMatrices.md
+++ b/docs/source/HedConditionsAndDesignMatrices.md
@@ -14,7 +14,7 @@ the [**BIDS annotation quickstart**](https://hed-examples.readthedocs.io/en/late
[**HED annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/HedAnnotationQuickstart.html)
tutorials as needed.
-The [**Neuorimaging experimental design**](neuroimaging-experimental-anchor)
+The [**Neuorimaging experimental design**](review-of-experimental-design-concepts-anchor)
section at the end of this tutorial provides a basic introduction to the ideas
of factor vectors and experimental design if you are unfamiliar with these topics.
@@ -26,17 +26,17 @@ of factor vectors and experimental design if you are unfamiliar with these topic
* [**Design matrices and factor variables**](design-matrices-and-factor-variables-anchor)
* [**Types of condition encoding**](types-of-condition-encoding-anchor)
-This tutorial introduces tools and strategies for including this information
-as part of a dataset without excessive effort on the part of the researcher.
-The discussion mainly focuses on categorical variables, but HED
-also can encode numerical values as discussed later in the tutorial.
+This tutorial introduces tools and strategies for encoding information
+about the experimental design as part of a dataset metadata
+without excessive effort on the part of the researcher.
+The discussion mainly focuses on categorical variables.
(hed-annotations-for-conditions-anchor)=
## HED annotations for conditions
As mentioned above, HED (Hierarchical Event Descriptors) provide several mechanisms for easily
annotating the experimental conditions represented by a BIDS dataset so that
-the information can be automatically extracted, summarized and used by tools.
+the information can be automatically extracted, summarized, and used by tools.
HED has three ways of annotating experimental conditions: condition variables without definitions,
condition variables with definitions but no levels, and condition variables with levels.
@@ -53,7 +53,7 @@ a simplified event file for an experiment to distinguish brain responses
for houses and faces.
(sample-house-face-example-anchor)=
-````{admonition} Example 2. Excerpt from a sample event file from a simplified house-face experiment.
+````{admonition} Example 1. Excerpt from a sample event file from a simplified house-face experiment.
| onset | duration | event_type | stim_file |
| ----- | -------- |----------- | ---------- |
| 2.010 | 0.1 | show_house | ranch1.png |
@@ -66,9 +66,9 @@ for houses and faces.
As explained in [**BIDS annotation quickstart**](https://hed-examples.readthedocs.io/en/latest/BidsAnnotationQuickstart.html),
the most commonly used strategy for annotating events in a BIDS dataset is
to create a single JSON file located in the dataset root containing the annotations
-for the columns. The following shows a minimal example
+for the columns. The following shows a minimal example:
-````{admonition} Example 3: Minimal JSON sidecar with HED annotations for Example 1.
+````{admonition} Example 2: Minimal JSON sidecar with HED annotations for Example 1.
:class: tip
```json
@@ -87,11 +87,13 @@ for the columns. The following shows a minimal example
````
Each row in an `events.tsv` file represents a time marker in the corresponding data recording.
-At analysis time, HED tools look up each column value in the JSON file and concatenate the
+At analysis time, HED tools look up each `events.tsv` column value in the JSON file and concatenate the
corresponding HED annotation into a single string representing the annotation for that row.
Annotations without #'s are used directly, while annotations with # have the corresponding
column values substituted when the annotation is assembled.
+Example 3 shows the Hed annotation for the first row in the `events.tsv` file of Example 1.
+
````{admonition} Example 3: HED annotation for first event in Example 1 using JSON sidecar of Example 2.
:class: tip
@@ -103,11 +105,15 @@ column values substituted when the annotation is assembled.
Notice that *Building/House* is a partial path rather than a single tag.
This is because *House* is currently not part of the base HED vocabulary.
However, users are allowed to extend tags at most nodes in the HED schema,
-but they must use a path that includes a least one ancestor that is in the HED schema.
+but they must use a path that includes a least one ancestor in the HED schema.
HED tools have the capability of automatically detecting *Condition-variable*
-tags in annotated HED datasets and creating factor vectors and summaries automatically.
-Example 4 shows the event file after HED tools have appended one-hot factor vectors.
+tags in annotated HED datasets to create factor vectors and summaries automatically.
+Example 4 shows the event file after HED tools have appended one-hot factor vectors
+for the two condition variables *Condition-variable/House-cond* and
+*Condition-variable/Face-cond*.
+The 1's and 0's *house_cond* and *face-cond* columns indicate presence or absence
+of the corresponding condition variables.
````{admonition} Example 4. Event file from Example 2 after one-hot factor vector extraction.
@@ -157,7 +163,7 @@ Dataset-wide summaries can also be extracted.
}
}
````
-The summary shows that of the total of 5 events in the file 3 events were under
+The summary shows that of the total of 5 events in the file: 3 events were under
the house condition and 2 events were under the face condition.
There were no events in multiple categories of the same condition variables
(which would not be possible since these condition variables were referenced
@@ -174,7 +180,7 @@ treated is though they are unrelated. These direct condition variables
are very easy to annotate--- just make up a name and stick the tags anywhere
you want to create factor variables or summaries.
However, a more common situation is for a condition variable to have multiple levels,
-which direct use condition variables do not support.
+which direct use condition variables does not support.
Another disadvantage of direct condition variables is that there is
no information about what the conditions represent beyond the arbitrarily chosen condition names.
@@ -182,7 +188,7 @@ no information about what the conditions represent beyond the arbitrarily chosen
A third disadvantage is that direct condition variables can not be used to
anchor events with temporal extent.
-The next section introduces the use of defined condition variables,
+The next section introduces defined condition variables,
which address both of these disadvantages.
(defined-condition-variables-anchor)=
@@ -214,17 +220,17 @@ which address both of these disadvantages.
Example 6 defines a condition variable called *Presentation-type* with two levels:
*House-cond* and *Face-cond*.
The definitions of *House-cond* and *Face-cond* both include the same *Presentation-type*
-*Condition-variable* so tools can recognize these as levels of the same variable and
-automatically extract 2-factor experimental design.
+*Condition-variable* so tools recognize these as levels of the same variable and
+automatically extract the 2-factor experimental design.
Notice that the (*Image*, *Building/House*) tags are included both in the definition of
the *House-cond* level of the *Presentation-type* condition variable
-and in the tags for the event_type *show_house*.
+and in the tags for the *event_type* column value *show_house*.
Similarly, the (*Image*, *Face*) tags appear in both the definition of the
*Face-cond* level of the *Presentation-type* condition variable
-and in the tags for the event_type *show_face*.
-We have included them in both places because generally the condition variable definitions
-are removed prior to searching for HED tags because the tags in the definitions
+and in the tags for the *event_type* column value *show_face*.
+We have included these tags in both places because generally the condition variable definitions
+are removed prior to searching for HED tags. The tags in the definitions
define the meaning of the conditions.
````{admonition} Example 7: The summary extracted when the JSON sidecar of Example 6 is used.
@@ -257,16 +263,16 @@ In this section, we look at a more complicated example based on the Wakeman-Hens
This dataset, which is available on [OpenNeuro](https://openneuro.org) under accession number
ds003654, was used in as a case study on HED annotation described in the
[Capturing the nature of events paper](https://www.sciencedirect.com/science/article/pii/S1053811921010387).
-
The experiment is based on a 3 x 3 x 2 experimental design: face type x repetition status x key choice.
-The experimental stimulus is each trial was the visual presentation of one of 3 possible types of images:
+
+The experimental stimulus in each trial was the visual presentation of one of 3 possible types of images:
a well-known face, an unfamiliar face, and a scrambled face image.
The type of face was randomized across trials.
-The repetition status condition variable also had one of three possible values and indicated:
+The repetition status condition variable also had one of three possible values and indicated
whether the stimulus image had not been seen before (first show),
was just seen in the previous trial (immediate repeat),
-or had been seen in a several trials ago (delayed repeat).
+or had been last seen several trials ago (delayed repeat).
The repetition status was randomized across trials.
The final condition variable in the experimental design was the key assignment.
@@ -318,7 +324,7 @@ Example 9 shows the portion of the
[**task-facePerception_events.json**](./_static/data/task-FacePerception_events.json)
that encodes information about the *setup_right_sym* event found as the first event
in the event file excerpt of Example 8.
-This file contains definitions for all the condition variables used in the dataset.
+This excerpt only contains the relevent definition and the relevant annotation.
````{admonition} Example 9: Excerpt of the JSON sidecar relevant to the *setup_right_sym* event.
@@ -548,7 +554,7 @@ The duration column (also required by BIDS) contains the duration of the
image presentation in seconds.
(different-encodings-of-design-variables-anchor)=
-````{admonition} Example 1: Different encodings of a column with categorical values.
+````{admonition} Example 14: Illustration of categorical and one-hot encoding of categorical variables.
| onset | duration | categorical | ordinal | one_hot.house | one_hot.face |
| ----- | -------- |----------- |-------- | ------------- | ------------ |
| 2.010 | 0.1 | house | 1 | 1 | 0 |
@@ -573,7 +579,7 @@ chosen, which may have undesirable affects on the results of analyses such
as regression if the ordering/relative sizes do not reflect the
properties of the encoded experimental conditions.
-In the example above, the experimental conditions houses and faces do not
+In Example 14, the experimental conditions houses and faces do not
have an ordering/size relationship reflected by the encoding (house=1, face=2).
In addition, neither categorical nor ordinal encoding
can represent items falling into multiple categories of the same condition at the same time.
From b05c08f946b1f39dd76de6b99b9594bb18a9dbb9 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Sat, 6 Aug 2022 17:14:35 -0500
Subject: [PATCH 013/143] Updated the introduction for event restructuring
---
docs/source/EventFileRestructuring.md | 435 +++++++++++++-----
...dInJavascript.md => HedJavascriptTools.md} | 2 +-
.../{HedInMatlab.md => HedMatlabTools.md} | 2 +-
.../{HedToolsOnline.md => HedOnlineTools.md} | 0
.../{HedInPython.md => HedPythonTools.md} | 2 +-
...b-0013_task-stopsignal_acq-seq_events.json | 63 ---
...ub-0013_task-stopsignal_acq-seq_events.tsv | 101 ++++
.../data/task-stopsignal_acq-seq_events.json | 24 +
.../_static/images/EventRemappingProcess.png | Bin 0 -> 75048 bytes
docs/source/_static/images/RestructureWeb.png | Bin 0 -> 11675 bytes
docs/source/index.rst | 8 +-
11 files changed, 451 insertions(+), 186 deletions(-)
rename docs/source/{HedInJavascript.md => HedJavascriptTools.md} (96%)
rename docs/source/{HedInMatlab.md => HedMatlabTools.md} (97%)
rename docs/source/{HedToolsOnline.md => HedOnlineTools.md} (100%)
rename docs/source/{HedInPython.md => HedPythonTools.md} (97%)
delete mode 100644 docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json
create mode 100644 docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.tsv
create mode 100644 docs/source/_static/data/task-stopsignal_acq-seq_events.json
create mode 100644 docs/source/_static/images/EventRemappingProcess.png
create mode 100644 docs/source/_static/images/RestructureWeb.png
diff --git a/docs/source/EventFileRestructuring.md b/docs/source/EventFileRestructuring.md
index d66706c..43c9d0c 100644
--- a/docs/source/EventFileRestructuring.md
+++ b/docs/source/EventFileRestructuring.md
@@ -1,21 +1,23 @@
# Event file restructuring
-**UNDER DEVELOPMENT**
-
-This tutorial works through the process of restructuring event files using the HED event remodeling tools. The tools are designed to be run on an entire BIDS dataset.
-
-* [**What is restructuring?**](what-is-event-file-restructuring-anchor) Docs in process
-* [**Installation of remodeling tools**](installation-of-remodeling-tools-anchor) Docs in process
-* [**Running remodeling tools**](running-remodeling-tools-anchor) Docs in process
-* [**Remodeling operations**](remodeling-operations-anchor) Docs in process
+This tutorial works through the process of restructuring event files using the HED event remodeling tools.
+The tools, which are written in Python, are designed to be run on an entire BIDS dataset.
+The tools can be called in Jupyter notebook or run via command-line scripts.
+
+* [**What is restructuring?**](what-is-event-file-restructuring-anchor)
+* [**Installing remodeling tools**](installing-remodeling-tools-anchor)
+* [**Running remodeling scripts**](running-remodeling-scripts-anchor)
+ * [**Backing up the events**](backing-up-the-events-anchor)
+ * [**Remodeling the events**](remodeling-the-events-anchor)
+* [**Remodeling operations**](remodeling-operations-anchor)
* [**Add structure column**](add-structure-column-anchor) Docs in process
* [**Add structure events**](add-structure-events-anchor) Docs in process
* [**Add structure numbers**](add-structure-numbers-anchor) Docs in process
* [**Factor column**](factor-column-anchor)
- * [**Factor HED tags**](factor-hed-tags-anchor) Docs in process
- * [**Factor HED type**](factor-hed-type-anchor) Docs in process
- * [**Merge events**](merge-events-anchor) Docs in process
- * [**Remap columns**](remap-columns-anchor) Docs in process
+ * [**Factor HED tags**](factor-hed-tags-anchor)
+ * [**Factor HED type**](factor-hed-type-anchor)
+ * [**Merge events**](merge-events-anchor)
+ * [**Remap columns**](remap-columns-anchor)
* [**Remove columns**](remove-columns-anchor)
* [**Rename columns**](rename-columns-anchor)
* [**Reorder columns**](reorder-columns-anchor)
@@ -25,40 +27,209 @@ This tutorial works through the process of restructuring event files using the H
(what-is-event-file-restructuring-anchor)=
## What is event file restructuring?
-Event file restructuring generally falls into four categories: cleanup,
-row modifications, column modifications, and structure modifications.
+The event files in an experiment provide a crucial link between what happens in
+the experiment and the experimental data by providing identified time markers
+linked to the timeline of the experiment.
+
+Event files are often initially created using information in the logs files
+generated by the experiment's presentation software or other control software.
+These event files are then used to identify portions of the data
+corresponding to particular points or blocks of data to be analyzed or compared.
+
+Event file restructuring refers to creating, modifying, and
+reorganizing the event markers in tabular files in order to
+disambiguate or clarify the information for distribution and analysis.
+Restructuring can occur at several stages during the acquisition and processing
+of experimental data as shown in this schematic diagram:
+.
+
+In addition to restructuring during initial creation of the tabular event files,
+restructuring may be required when the event files do not conform to the requirements
+of a particular analysis.
+Thus, restructuring is an iterative process,
+which is supported by the HED remodeling tools for datasets with tabular event files.
+
+Table 1 gives a summary of the tools available in the HED remodeling toolbox.
+
+(summary-of-hed-remodeling-tools-anchor)=
+````{table} **Table 1:** Summary of the HED remodeling tools for tabular files.
+| Category | Command | Example use case |
+| -------- | ------- | -----|
+| **clean-up** | | |
+| | *remove_columns* | Remove temporary columns created during restructuring. |
+| | *remove_rows* | Remove rows with n/a values in a specified column. |
+| | *rename_columns* | Make columns names consistent across a dataset. |
+| | *reorder_columns* | Make column order consistent across a dataset. |
+| **factor** | | |
+| | *factor_column* | Extract factor vectors from a column of condition variables. |
+| | *factor_hed_tags* | Extract factor vectors from search queries of HED annotations. |
+| | *factor_hed_types* | Extract design matrices and/or condition variables. |
+| **restructure** | | |
+| | *remap_columns* | Create m columns from values in n columns (for recoding). |
+| | *split_event* | Split trial-encoded rows into multiple events. |
+| | *merge_consecutive* | Replace multiple consecutive events of the same type
with one event of longer duration. |
+| | *add_structure_column* | Add a column with condition names. |
+| | *add_structure_rows* | Add a row representing the start of a block or trial. |
+| | *add_structure_numbers* | Add a column with trial or block numbers. |
+````
+
+The **clean-up** commands are used at various phases of restructuring to assure consistency
+across event files in the dataset.
+
+The **factor** commands produce column vectors of the same length as the events file
+that encode condition variables, design matrices, or satisfaction of other search criteria.
+See the
+[**HED conditions and design matrices**](https://hed-examples.readthedocs.io/en/latest/HedConditionsAndDesignMatrices.html)
+for more information on factoring and analysis.
+
+The **restructure** commands modify the way that events are encoded.
+
+(installing-remodeling-tools-anchor)=
+## Installing remodeling tools
+
+Currently, the remodeling tools are available in the GitHub
+[**hed-curation repository**](https://github.com/hed-standard/hed-curation)
+along with other tools for data cleaning and curation.
+These tools rely on the *hedtools* library which is available on PyPI
+and can be installed via PIP.
+
+Once the HED remodeling tools are available in final form,
+the tools will be moved to the GitHub
+[hed-python repository](https://github.com/hed-standard/hed-python)
+and be available for installation via PyPI.
+At that time, versions for single event files will become available
+as a web-service and through a web-interface
+on the [HED online tools](https://hedtools.ucsd.edu/hed).
+A docker version is also under development.
+
+In the meantime, if you want to run the latest version of the tools,
+you will need to install the development branch of both
+*hed-python* and *hed-curation* using:
+
+```text
+pip install git+https://github.com/hed-standard/hed-python/@develop
+pip install git+https://github.com/hed-standard/hed-curation/@develop
+```
+
+(running-remodeling-scripts-anchor)=
+## Running remodeling scripts
-#### Cleanup operations
+Remodeling consists of applying a list of commands to an events file
+to restructure or modify it in some way.
-Cleanup operations include: *rename_columns*, *reorder_columns*, and *remove_columns*.
+The following diagram shows a schematic of the remodeling process.
-#### Row and columns
+
-*factor_column*, *factor_hed_tags*, and *factor_hed_type*
+Initially, the user creates a backup of the event files.
+Restructuring applies a sequence of remodeling commands given in a JSON transformation file
+to produce a final result.
+The transformation file provides a record of the operations performed on the file.
+If the user detects a mistake in the transformation,
+he/she can correct the transformation file and restore the backup to rerun.
-#### Restructuring
+The remodeling toolbox provides several scripts to apply the transformations
+to the files in a [BIDS-formatted dataset](https://bids.neuroimaging.io/).
+The basic scripts are summarized in Table 2.
-Restructuring operations include: *add_structure_column*, *add_structure_events*,
-*add_structure_numbers*, *merge_events*, *remap_columns*, and *split_event*
+(summary-of-remodeling-scripts-anchor)=
+````{table} **Table 2:** Summary of the remodeling scripts.
+| Script name | Arguments | Purpose |
+| ----------- | -------- | ------- |
+|*run_backup* | *bids_dir*
*-t task_name*
*-b backup-type*
*-e exclude_dirs* | Backup the event files. |
+|*run_remodel* | *bids_dir*
*-t task_name*
*-m model-path*
*-e exclude_dirs* | Remodel the event files. |
+|*run_restore* | *bids_dir*
*-t task_name*
*-b backup-type*
*-e exclude_dirs* | Restore the event files. |
+|*run_remove* | *bids_dir*
*-t task_name*
*-b backup-type*
*-e exclude_dirs* | Remove the backup event files. |
+````
+
+All the scripts have a required parameter which is the full path of the BIDS dataset root.
+The *-t task_name* option specifies which task in the dataset the remodeling should apply to.
+Often, when a dataset includes multiple tasks,
+the event files are structured differently for each task and thus require different transformation files.
+
+The other *-e exclude_dirs* gives a list of directories to ignore in searching for event file.
+In BIDS, typical directories to exclude are `derivatives`, `code`, and `stimulus_files`.
+
+(backing-up-the-events-anchor)=
+### Backing up the events
+Before any remodeling is performed, you should always back up the event files.
+Usually this is just done once, before any remodeling is done.
+There are two strategies for doing the backup: *in-place* and *full-tree*.
+
+The *in-place* strategy makes a copy of each event file in the same directory
+as the event file using the suffix `_eventsorig.tsv` to distinguish
+these backup files from the active event files (which end in `_events.tsv`).
+The *in-place* strategy is simple, but the extra files prevent the dataset from
+validating with the BIDS validator.
+
+The *full-tree* strategy creates a complete tree backup in the
+`code/event_backup` directory of the BIDS dataset.
+This strategy is more expensive, but does not prevent validation
+or interfere with other processing.
+
+(remodel-backup-anchor)=
+````{admonition} Example command to backup the events.
+:class: tip
-(installation-of-remodeling-tools-anchor)=
-## Installation of remodeling tools
+```bash
+python run_backup.py t:\ds002790-data -b full-tree -e derivatives code simulus_files
-**Need information about installation.**
+```
+````
-(running-remodeling-tools-anchor)=
-## Running remodeling tools
+(remodeling-the-events-anchor)=
+### Remodeling the events
-**Need information about how to run**
+The event remodeling process is given by the following example:
+(remodel-run-anchor)=
+````{admonition} Example command to remodel the events.
+:class: tip
+
+```bash
+python run_remodel.py t:\ds002790-data -m derivatives/models/simple_rmdl.json -e derivatives code simulus_files
+
+```
+````
+
+(remodel-backup-example-anchor)=
+````{admonition} Example remodeling file with commands to remove columns and reorder the rest.
+:class: tip
+
+```json
+[
+ {
+ "command": "remove_columns",
+ "description": "Get rid of the sample and the value columns.",
+ "parameters": {
+ "remove_names": ["sample", "value"],
+ "ignore_missing": true
+ }
+ },
+ {
+ "command": "reorder_columns",
+ "description": "Want event_type and task_role columns after onset and duration.",
+ "parameters": {
+ "column_order": ["onset", "duration", "event_type", "task_role"],
+ "ignore_missing": false,
+ "keep_others": true
+ }
+ }
+]
+```
+````
+
(remodeling-operations-anchor)=
## Remodeling operations
-The examples in this chapter use the following excerpt from sub-0013
-stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneuro.org) as ds002790.
+The examples in this tutorial use the following excerpt of the stop-go task from sub-0013
+of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneuro.org) as ds002790.
+The full events file is
+[sub-0013_task-stopsignal_acq-seq_events.tsv](./_static/data/sub-0013_task-stopsignal_acq-seq_events.tsv).
+
(sample-remodeling-events-file-anchor)=
-````{admonition} Excerpt from event file for a stop-go task of AOMIC-PIOP2 (ds002790).
+````{admonition} Table 3: Excerpt from an event file from the stop-go task of AOMIC-PIOP2 (ds002790).
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | n/a | 0.565 | |correct | right | female
@@ -69,6 +240,48 @@ stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneu
| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male |
````
+The *factor_hed_types* and *factor_hed_tags* also require HED annotations of
+the events and require a JSON sidecar that includes HED annotations.
+The tutorial uses the following JSON excerpt to illustrate these operations.
+The full JSON file can be found at:
+[task-stopsiqnal_acq-seq_events.json](./_static/data/task-stopsignal_acq-seq_events.json).
+These HED commands also require the HED schema.
+The tutorials use the latest version that is downloaded from the web.
+
+
+(sample-remodeling-sidecar-file-anchor)=
+````{admonition} Excerpt of JSON sidecar with HED annotations for the stop-go task of AOMIC-PIOP2.
+:class: tip
+
+```json
+{
+ "trial_type": {
+ "HED": {
+ "succesful_stop": "Sensory-presentation, Visual-presentation, Correct-action, Image, Label/succesful_stop",
+ "unsuccesful_stop": "Sensory-presentation, Visual-presentation, Incorrect-action, Image, Label/unsuccesful_stop",
+ "go": "Sensory-presentation, Visual-presentation, Image, Label/go"
+ }
+ },
+ "stop_signal_delay": {
+ "HED": "(Auditory-presentation, Delay/# s)"
+ },
+ "sex": {
+ "HED": {
+ "male": "Def/Male-image-cond",
+ "female": "Def/Female-image-cond"
+ }
+ },
+ "hed_defs": {
+ "HED": {
+ "def_male": "(Definition/Male-image-cond, (Condition-variable/Image-sex, (Male, (Image, Face))))",
+ "def_female": "(Definition/Female-image-cond, (Condition-variable/Image-sex, (Female, (Image, Face))))"
+ }
+ }
+}
+```
+````
+
+
(add-structure-column-anchor)=
### Add structure column
@@ -77,7 +290,7 @@ stop-go task of the AOMIC-PIOP2 dataset available on [OpenNeuro](https://openneu
Add a column of numbers corresponding to a structure elements such as trials or blocks.
(parameters-for-add-structure-column-anchor)=
-```{admonition} Parameters for the *add_structure_column* command.
+```{admonition} Table 4: Parameters for the *add_structure_column* command.
:class: tip
| Parameter | Type | Description |
@@ -105,10 +318,11 @@ The *add_structure_column* command in the following example specifies . . .
```
````
-The results of executing this *add_structure_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *add_structure_column* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of the previous *add_structure_column* command.
+````{admonition} Table 5: Results of the previous *add_structure_column* command.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -128,7 +342,7 @@ The results of executing this *add_structure_column* command on the [sample even
Add events representing the start of a structural element such as a trial or a block.
(parameters-for-add-structure-event-anchor)=
-```{admonition} Parameters for the *add_structure_events* command.
+```{admonition} Table 6: Parameters for the *add_structure_events* command.
:class: tip
| Parameter | Type | Description |
@@ -155,10 +369,11 @@ The *add_structure_events* command in the following example specifies . . .
```
````
-The results of executing this *add_structure_events* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *add_structure_events* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of the previous *add_structure_events* command.
+````{admonition} Table 7: Results of the previous *add_structure_events* command.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -180,7 +395,7 @@ Add a column with numbers corresponding to a structural element.
**TODO** clarify the difference between add_structure_numbers and add_structure_column.
(parameters-for-add-structure-numbers-anchor)=
-```{admonition} Parameters for the *add_structure_numbers* command.
+```{admonition} Table 8: Parameters for the *add_structure_numbers* command.
:class: tip
| Parameter | Type | Description |
@@ -191,7 +406,7 @@ Add a column with numbers corresponding to a structural element.
```
The *add_structure_numbers* command in the following example specifies . . .
-````{admonition} An example .
+````{admonition} An example *add_structure_numbers* command.
:class: tip
```json
@@ -210,10 +425,11 @@ The *add_structure_numbers* command in the following example specifies . . .
```
````
-The results of executing this *add_structure_numbers* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *add_structure_numbers* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of executing the previous *add_structure_numbers* command.
+````{admonition} Table 9: Results of executing the previous *add_structure_numbers* command.
| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -233,7 +449,7 @@ indicating presence or absence of the value.
If no values are specified, all unique values in that column are factored.
(parameters-for-factor-column-anchor)=
-```{admonition} Parameters for the *factor_column* command.
+```{admonition} Table 10: Parameters for the *factor_column* command.
:class: tip
| Parameter | Type | Description |
@@ -273,9 +489,10 @@ form *column_name.factor_value*.
```
````
-The results of executing this *factor_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *factor_column* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of factoring column XXX.
+````{admonition} Table 11: Results of factoring column XXX.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | stopped | stop_failed |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ---------- | ---------- |
@@ -298,7 +515,7 @@ will have 1 for the factors.
If an event fails one of the queries it does not get a factor
(parameters-for-factor-hed-tags-anchor)=
-```{admonition} Parameters for *factor_hed_tags* command.
+```{admonition} Table 12: Parameters for *factor_hed_tags* command.
:class: tip
| Parameter | Type | Description |
@@ -331,13 +548,16 @@ The *factor_hed-tags* command in the following example specifies . . .
```
````
-The results of executing this *factor_hed-tags* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *factor_hed-tags* command on the
+[sample events file](sample-remodeling-events-file-anchor) using the
+[sample sidecar file](sample-remodeling-sidecar-file-anchor) for HED annotations is:
-````{admonition} Results of *factor_hed_tags*.
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female |
+````{admonition} Table 13: Results of *factor_hed_tags*.
+
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
+| ----- | -------- |---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female |
| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female |
@@ -363,7 +583,7 @@ For additional information on how to encode experimental designs using HED pleas
[HED conditions and design matrices](https://hed-examples.readthedocs.io/en/latest/HedConditionsAndDesignMatrices.html).
(parameters-for-factor-hed-type-anchor)=
-```{admonition} Parameters for *factor_hed_type* command.
+```{admonition} Table 14: Parameters for *factor_hed_type* command.
:class: tip
| Parameter | Type | Description |
@@ -395,42 +615,17 @@ To simplifyThe *factor_hed_type* command in the following example specifies . .
In order to use the JSON file. The full file is at:
+The results of executing this *factor_hed-tags* command on the
+[sample events file](sample-remodeling-events-file-anchor) using the
+[sample sidecar file](sample-remodeling-sidecar-file-anchor) for HED annotations are:
-````{admonition} Example *factor_hed_type* command.
-:class: tip
-
-```json
-{
- "trial_type": {
- "HED": {
- "succesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/succesful_stop",
- "unsuccesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/unsuccesful_stop",
- "go": "Sensory-presentation, Visual-presentation, Image, Label/go"
- },
- "sex": {
- "HED": {
- "male": "Def/Male-image-cond",
- "female": "Def/Female-image-cond"
- }
- },
- "hed_defs": {
- "HED": {
- "def_male": "(Definition/Male-image-cond, (Condition-variable/Image-sex, (Male, (Image, Face))))",
- "def_female": "(Definition/Female-image-cond, (Condition-variable/Image-sex, (Female, (Image, Face))))"
- }
- }
-}
-```
-````
-
-The results of executing this *factor_hed_type* command on the [sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of *factor_hed_type*.
+````{admonition} Table 15: Results of *factor_hed_type*.
-| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex | Image-sex.Female-image-cond | Image-sex.Male-image-cond |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ------- | ---------- |
-| 0.0776 | 0.5083 | go |right | n/a | 0.565 | correct | right | female | 1 | 0 |
-| 5.5774 | 0.5083 | unsuccesful_stop | right | 0.2 | 0.49 | correct | right | female | 1 | 0 |
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | Image-sex.Female-image-cond | Image-sex.Male-image-cond |
+| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ------- | ---------- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | 1 | 0 |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | 1 | 0 |
| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | 1 | 0 |
| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | 1 | 0 |
| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | 0 | 1 |
@@ -442,10 +637,12 @@ The results of executing this *factor_hed_type* command on the [sample events fi
**NOT WRITTEN - PLACEHOLDER**
-One long event is represented by multiple repeat events. Merges these same events occurring consecutively into one event with duration of the new event updated as the sum of all merged events.
+One long event is represented by multiple repeat events.
+Merges these same events occurring consecutively into one event with duration
+of the new event updated as the sum of all merged events.
(parameters-for-merge-events-anchor)=
-```{admonition} Parameters for the *merge_events* command.
+```{admonition} Table 16: Parameters for the *merge_events* command.
:class: tip
| Parameter | Type | Description |
@@ -476,9 +673,10 @@ The *merge_events* command in the following example specifies . . .
```
````
-The results of executing the previous *merge_events* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *merge_events* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} The results of the *merge_events* command.
+````{admonition} Table 17: The results of the *merge_events* command.
| onset | duration | trial_type | match_side | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -502,7 +700,7 @@ The mapping should have targets for all combinations of values that appear in th
(parameters-for-remap-columns-anchor)=
-```{admonition} Parameters for the *remap_columns* command.
+```{admonition} Table 18: Parameters for the *remap_columns* command.
:class: tip
| Parameter | Type | Description |
@@ -541,18 +739,19 @@ based on the unique values in the combination of columns *response_accuracy* and
```
````
-The results of executing the previous *remap_column* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *remap_column* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Mapping columns *response_accuracy* and *response_hand* into a *response_type* column.
+````{admonition} Table 19: Mapping columns *response_accuracy* and *response_hand* into a *response_type* column.
-| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | response_type |
-| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | --- | ------------------- |
-| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | correct_right |
-| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | correct_right |
-| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | correct_right |
-| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | n/a |
-| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | correct_left |
-| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | correct_left |
+| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | response_type |
+| ----- | -------- | ---------- | ---------- | ----------------- | ------------- | ----------------- | --- | ------------------- |
+| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female | correct_right |
+| 5.5774 | 0.5083 | unsuccesful_stop | 0.2 | 0.49 | correct | right | female | correct_right |
+| 9.5856 | 0.5084 | go | n/a | 0.45 | correct | right | female | correct_right |
+| 13.5939 | 0.5083 | succesful_stop | 0.2 | n/a | n/a | n/a | female | n/a |
+| 17.1021 | 0.5083 | unsuccesful_stop | 0.25 | 0.633 | correct | left | male | correct_left |
+| 21.6103 | 0.5083 | go | n/a | 0.443 | correct | left | male | correct_left |
````
Typically, the *remap_columns* command is used often used to map single codes in the experimental log
@@ -567,7 +766,7 @@ parameter is *false*, a `KeyError` is raised for missing column.
(parameters-for-remove-columns-anchor)=
-```{admonition} Parameters for the *remove_columns* operation.
+```{admonition} Table 20: Parameters for the *remove_columns* operation.
:class: tip
| Parameter | Type | Description |
@@ -595,13 +794,14 @@ since *ignore_missing* is True.
```
````
-The results of executing this command on the
-[sample events file](sample-remodeling-events-file-anchor) are shown below.
+The results of executing this command on the
+[sample events file](sample-remodeling-events-file-anchor)
+are shown below.
Although *face* is not the name of a column in the dataframe,
it is ignored because *ignore_missing* is true.
If *ignore_missing* had been false, a `KeyError` would have been generated.
-```{admonition} Results of executing the *remove_column*.
+```{admonition} Table 21: Results of executing the *remove_column*.
| onset | duration | trial_type | response_time | response_hand | sex |
| ----- | -------- | ---------- | ------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | 0.565 | right | female |
@@ -618,7 +818,7 @@ If *ignore_missing* had been false, a `KeyError` would have been generated.
Remove rows in which the named column has one of the specified values.
(parameters-for-remove-rows-anchor)=
-```{admonition} Parameters for remove_rows.
+```{admonition} Table 22: Parameters for remove_rows.
:class: tip
| Parameter | Type | Description |
@@ -648,7 +848,7 @@ has either *succesful_stop* or *unsuccesful_stop*.
The results of executing the previous *remove_rows* command on the
[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} The results of executing the previous *remove_rows* command.
+````{admonition} Table 23: The results of executing the previous *remove_rows* command.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
@@ -666,7 +866,7 @@ three *go* trials remain.
Rename columns by providing a dictionary of old names to new names.
(parameters-for-rename-columns-anchor)=
-```{admonition} Parameters for *rename_columns*.
+```{admonition} Table 24: Parameters for *rename_columns*.
:class: tip
| Parameter | Type | Description |
@@ -702,9 +902,10 @@ the mapping does not correspond to a column name in the dataframe.
```
````
-The results of executing the previous *rename_columns* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *rename_columns* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} After the *rename_columns* command is executed, the sample events file is:
+````{admonition} Table 25: After the *rename_columns* command is executed, the sample events file is:
| onset | duration | trial_type | stop_delay | response_time | response_accuracy | hand_used | image_sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
| 0.0776 | 0.5083 | go | n/a | 0.565 | correct | right | female |
@@ -728,13 +929,13 @@ do not appear in the reorder list are dropped (*keep_others* is false) or
put at the end of the dataframe in the order they appear (*keep_others* is true).
(parameters-for-reorder-columns-anchor)=
-```{admonition} Parameters for *reorder_columns*.
+```{admonition} Table 26: Parameters for *reorder_columns*.
:class: tip
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
| *column_order* | list | A list of columns in the order they should appear in the data.|
-| *ignore_missing* | bool | If true and a column in *column_order* does not appear in the dataframe
a *ValueError* is raised, otherwise these columns are ignored. |
+| *ignore_missing* | bool | If true and a column in *column_order* does not appear in the dataframe
a *ValueError* is raised, otherwise these columns are ignored. |
| *keep_others* | bool | If true, existing columns that aren't in *column_order*
are moved to the end in the same relative
order that they originally appeared in the data,
otherwise these columns are dropped.|
```
@@ -760,9 +961,10 @@ Since *ignore_missing* is true, these will be the only columns retained.
````
-The results of executing the previous *reorder_columns* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing the previous *reorder_columns* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of *reorder_columns*.
+````{admonition} Table 27: Results of *reorder_columns*.
| onset | duration | response_time | trial_type |
| ----- | -------- | ---------- | ------------- |
@@ -802,14 +1004,14 @@ Unlisted columns are filled with n/a.
(parameters-for-split-event-anchor)=
-```{admonition} Parameters for split_event.
+```{admonition} Table 28: Parameters for *split_event*.
:class: tip
| Parameter | Type | Description |
| ------------ | ---- | ----------- |
-| *anchor_event* | str | The name of the column that will be used for split-event codes.|
+| *anchor_event* | str | The name of the column that will be used for split-event codes.|
| *new_events* | dict | Dictionary whose keys are the codes to be inserted as new events
and whose values are dictionaries with
keys *onset_source*, *duration*, and *copy_columns*. |
-| *remove_parent_event* | bool | If true, remove parent event. |
+| *remove_parent_event* | bool | If true, remove parent event. |
```
@@ -846,9 +1048,10 @@ since these items have been unfolded into separate events.
```
````
-The results of executing this *split_event* command on the [sample events file](sample-remodeling-events-file-anchor) are:
+The results of executing this *split_event* command on the
+[sample events file](sample-remodeling-events-file-anchor) are:
-````{admonition} Results of the previous *split_event* command.
+````{admonition} Table 29: Results of the previous *split_event* command.
| onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex |
| ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- |
diff --git a/docs/source/HedInJavascript.md b/docs/source/HedJavascriptTools.md
similarity index 96%
rename from docs/source/HedInJavascript.md
rename to docs/source/HedJavascriptTools.md
index c67aa84..5881b1c 100644
--- a/docs/source/HedInJavascript.md
+++ b/docs/source/HedJavascriptTools.md
@@ -1,4 +1,4 @@
-# HED in JavaScript
+# HED JavaScript tools
The JavaScript code for HED validation is in the validation directory of the
`hed-javascript` repository located at [https://github.com/hed-standard/hed-javascript](https://github.com/hed-standard/hed-javascript).
diff --git a/docs/source/HedInMatlab.md b/docs/source/HedMatlabTools.md
similarity index 97%
rename from docs/source/HedInMatlab.md
rename to docs/source/HedMatlabTools.md
index 42a9a2a..fed9c47 100644
--- a/docs/source/HedInMatlab.md
+++ b/docs/source/HedMatlabTools.md
@@ -1,4 +1,4 @@
-# HED in MATLAB
+# HED MATLAB tools
There are currently three types of support available for HED (Hierarchical Event Descriptors) supports in MATLAB:
diff --git a/docs/source/HedToolsOnline.md b/docs/source/HedOnlineTools.md
similarity index 100%
rename from docs/source/HedToolsOnline.md
rename to docs/source/HedOnlineTools.md
diff --git a/docs/source/HedInPython.md b/docs/source/HedPythonTools.md
similarity index 97%
rename from docs/source/HedInPython.md
rename to docs/source/HedPythonTools.md
index f798ad4..6fe9f62 100644
--- a/docs/source/HedInPython.md
+++ b/docs/source/HedPythonTools.md
@@ -1,4 +1,4 @@
-# HED in Python
+# HED Python tools
The HED (Hierarchical Event Descriptor) scripts and notebooks assume
that the Python HedTools have been installed.
diff --git a/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json b/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json
deleted file mode 100644
index 205666d..0000000
--- a/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.json
+++ /dev/null
@@ -1,63 +0,0 @@
-{
- "trial_type": {
- "Description": "Description for trial_type",
- "HED": {
- "succesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/succesful_stop",
- "unsuccesful_stop": "Sensory-presentation, Visual-presentation, Image, Label/unsuccesful_stop",
- "go": "Sensory-presentation, Visual-presentation, Image, Label/go"
- },
- "Levels": {
- "succesful_stop": "Presentation of a face image in a trial with a stop signal in which participant inhibited response.",
- "unsuccesful_stop": "Presentation of a face image in a trial with a stop signal in which participant did not inhibit response.",
- "go": "Presentation of a face image in a trial with no stop signal"
- }
- },
- "stop_signal_delay": {
- "Description": "Stop-signal cue delay from onset.",
- "HED": "((Cue, Think/Inhibit), Delay/# s)"
- },
- "response_time": {
- "Description": "Response time delay from onset.",
- "HED": "(Participant-response, Delay/# s)"
- },
- "response_accuracy": {
- "Description": "Indicates whether a response correctly indicated",
- "HED": {
- "incorrect": "(Incorrect-action, (Identify, (Image, Sex)))",
- "correct": "(Correct-action, (Identify, (Image, Sex)))"
- },
- "Levels": {
- "incorrect": "Used the wrong hand to indicate the sex of the face image.",
- "correct": "Used the correct hand to indicate the sex of the face image."
- }
- },
- "response_hand": {
- "Description": "Description for response_hand",
- "HED": {
- "left": "(Hand, (Left-side-of, Body))",
- "right": "(Hand, (Right-side-of, Body))"
- },
- "Levels": {
- "left": "A response using the left hand.",
- "right": "A response using the right hand."
- }
- },
- "sex": {
- "Description": "The sex of the image",
- "HED": {
- "male": "Def/Male-image-cond",
- "female": "Def/Female-image-cond"
- },
- "Levels": {
- "male": "The image was the face of a male person.",
- "female": "The image was the face of a female person."
- }
- },
- "hed_defs": {
- "Description": "HED user-defined terms for the dataset.",
- "HED": {
- "def_male": "(Definition/Male-image-cond, (Condition-variable/Image-sex, (Male, (Image, Face))))",
- "def_female": "(Definition/Female-image-cond, (Condition-variable/Image-sex, (Female, (Image, Face))))"
- }
- }
-}
\ No newline at end of file
diff --git a/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.tsv b/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.tsv
new file mode 100644
index 0000000..05bffac
--- /dev/null
+++ b/docs/source/_static/data/sub-0013_task-stopsignal_acq-seq_events.tsv
@@ -0,0 +1,101 @@
+onset duration trial_type stop_signal_delay response_time response_accuracy response_hand sex
+0.0776 0.5083 go n/a 0.565 correct right female
+5.5774 0.5083 unsuccesful_stop 0.2 0.49 correct right female
+9.5856 0.5084 go n/a 0.45 correct right female
+13.5939 0.5083 succesful_stop 0.2 n/a n/a right female
+17.1021 0.5083 unsuccesful_stop 0.25 0.633 correct left male
+21.6103 0.5083 go n/a 0.443 correct left male
+24.6186 0.5083 go n/a 0.439 correct left male
+28.6268 0.5083 go n/a 0.667 correct left male
+32.1434 0.5083 go n/a 0.55 correct right female
+36.1516 0.5083 succesful_stop 0.25 n/a n/a right female
+41.6514 0.5084 go n/a 0.59 correct right female
+44.6597 0.5083 unsuccesful_stop 0.3 0.511 correct right female
+49.6679 0.5083 go n/a 0.604 correct right female
+52.1845 0.5083 go n/a 0.743 correct left male
+56.1927 0.5084 succesful_stop 0.3 n/a n/a right female
+60.6926 0.5083 unsuccesful_stop 0.35 0.555 correct left male
+65.7008 0.5083 go n/a 0.584 correct right female
+73.7173 0.5083 succesful_stop 0.35 n/a n/a right female
+76.7255 0.5083 succesful_stop 0.4 n/a n/a right male
+81.2337 0.5084 go n/a 0.615 correct left male
+84.742 0.5083 go n/a 0.754 correct left male
+89.2502 0.5083 go n/a 0.777 correct right female
+92.2668 0.5083 go n/a 0.644 correct right female
+97.2666 0.5084 unsuccesful_stop 0.45 0.629 correct right female
+100.2832 0.5083 go n/a 0.714 correct right female
+104.7831 0.5083 go n/a 0.627 correct left male
+108.2997 0.5083 go n/a 0.668 correct left male
+113.2995 0.5084 go n/a 0.558 correct left male
+117.3078 0.5083 go n/a 1.038 incorrect left female
+120.816 0.5083 go n/a 0.764 correct left male
+125.8242 0.5083 go n/a 0.782 correct right female
+129.3325 0.5083 unsuccesful_stop 0.5 0.722 correct left male
+132.8407 0.5083 go n/a 0.716 correct right female
+137.8489 0.5083 go n/a 0.741 correct right female
+141.3571 0.5084 succesful_stop 0.5 n/a n/a right male
+145.8653 0.5084 go n/a 1.027 correct right female
+149.3736 0.5083 go n/a 0.881 correct left male
+153.3818 0.5083 go n/a 0.801 correct right female
+157.89 0.5084 go n/a 0.803 correct left male
+160.8983 0.5083 go n/a 0.771 correct right female
+164.4149 0.5083 succesful_stop 0.55 n/a n/a right female
+169.4147 0.5083 go n/a 0.899 correct left male
+172.923 0.5083 unsuccesful_stop 0.6 0.754 correct left male
+176.9312 0.5083 go n/a 1.11 correct left male
+180.4478 0.5083 succesful_stop 0.65 n/a n/a right male
+188.9559 0.5083 unsuccesful_stop 0.7 0.867 correct right female
+193.4641 0.5083 unsuccesful_stop 0.75 0.814 correct left male
+197.4723 0.5083 go n/a 1.21 correct right female
+201.4805 0.5084 go n/a 0.859 correct left male
+204.9888 0.5083 unsuccesful_stop 0.75 0.973 correct right female
+212.5136 0.5083 go n/a 1.02 correct left male
+221.5217 0.5083 go n/a 0.817 correct left male
+225.5299 0.5083 go n/a 1.038 correct right female
+228.5465 0.5083 go n/a 1.049 correct right female
+234.0463 0.5084 go n/a 0.92 correct left male
+237.0546 0.5083 succesful_stop 0.7 n/a n/a right female
+241.0628 0.5083 go n/a 1.266 correct right female
+245.071 0.5084 unsuccesful_stop 0.7 0.854 correct right female
+248.5876 0.5083 go n/a 0.985 correct left male
+254.0875 0.5083 go n/a 0.789 correct right female
+260.6123 0.5083 go n/a 0.928 correct right female
+266.1122 0.5083 go n/a 0.807 correct left male
+269.6204 0.5083 go n/a 0.735 correct left male
+273.6286 0.5083 succesful_stop 0.65 n/a n/a right male
+277.6368 0.5084 go n/a 0.896 correct right female
+281.6451 0.5083 succesful_stop 0.65 n/a n/a right female
+289.6615 0.5083 unsuccesful_stop 0.7 0.831 correct right female
+293.1698 0.5083 go n/a 0.876 correct left male
+296.6863 0.5084 go n/a 1.021 correct right female
+302.1862 0.5083 unsuccesful_stop 0.7 1.085 correct left male
+306.1944 0.5083 succesful_stop 0.65 n/a n/a right female
+309.2027 0.5083 go n/a 0.814 correct right female
+313.2109 0.5083 go n/a 1.053 correct left male
+318.2191 0.5083 go n/a 1.002 correct left male
+322.2273 0.5083 go n/a 1.057 correct right female
+326.2355 0.5084 succesful_stop 0.65 n/a n/a right male
+330.2438 0.5083 succesful_stop 0.7 n/a n/a right male
+334.252 0.5083 go n/a 0.962 correct left male
+341.2685 0.5083 go n/a 0.817 correct right female
+346.2767 0.5083 unsuccesful_stop 0.75 0.822 correct left male
+350.2849 0.5083 go n/a 0.889 correct left male
+353.2932 0.5083 go n/a 0.946 correct right female
+358.3014 0.5083 go n/a 0.911 correct right female
+360.818 0.5083 unsuccesful_stop 0.8 1.054 correct left male
+364.8262 0.5083 go n/a 0.966 correct right female
+368.8344 0.5083 unsuccesful_stop 0.8 0.99 correct right female
+373.8343 0.5083 go n/a 1.004 correct right female
+377.8425 0.5083 unsuccesful_stop 0.75 0.909 correct left male
+381.8507 0.5084 go n/a 0.859 correct left male
+385.859 0.5083 go n/a 1.186 correct right female
+389.3672 0.5083 go n/a 1.288 correct right female
+393.3754 0.5083 go n/a 0.979 correct left male
+398.3836 0.5084 go n/a 1.067 correct left male
+400.9002 0.5083 succesful_stop 0.7 n/a n/a right male
+409.4083 0.5084 go n/a 0.901 correct left male
+414.4165 0.5084 unsuccesful_stop 0.65 0.879 correct left male
+418.4248 0.5083 go n/a 1.003 correct left male
+422.433 0.5083 succesful_stop 0.6 n/a n/a right female
+429.9495 0.5083 succesful_stop 0.55 n/a n/a right female
+437.9659 0.5083 go n/a 0.866 correct left male
diff --git a/docs/source/_static/data/task-stopsignal_acq-seq_events.json b/docs/source/_static/data/task-stopsignal_acq-seq_events.json
new file mode 100644
index 0000000..d9d1a79
--- /dev/null
+++ b/docs/source/_static/data/task-stopsignal_acq-seq_events.json
@@ -0,0 +1,24 @@
+{
+ "trial_type": {
+ "HED": {
+ "succesful_stop": "Sensory-presentation, Visual-presentation, Correct-action, Image, Label/succesful_stop",
+ "unsuccesful_stop": "Sensory-presentation, Visual-presentation, Incorrect-action, Image, Label/unsuccesful_stop",
+ "go": "Sensory-presentation, Visual-presentation, Image, Label/go"
+ }
+ },
+ "stop_signal_delay": {
+ "HED": "(Auditory-presentation, Delay/# s)"
+ },
+ "sex": {
+ "HED": {
+ "male": "Def/Male-image-cond",
+ "female": "Def/Female-image-cond"
+ }
+ },
+ "hed_defs": {
+ "HED": {
+ "def_male": "(Definition/Male-image-cond, (Condition-variable/Image-sex, (Male, (Image, Face))))",
+ "def_female": "(Definition/Female-image-cond, (Condition-variable/Image-sex, (Female, (Image, Face))))"
+ }
+ }
+}
\ No newline at end of file
diff --git a/docs/source/_static/images/EventRemappingProcess.png b/docs/source/_static/images/EventRemappingProcess.png
new file mode 100644
index 0000000000000000000000000000000000000000..ad233c03cabd62844cb34289f3093158119bdc6b
GIT binary patch
literal 75048
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
z
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