Repository: mne-tools/mne-bids

Issue:
Add descriptions for onset and duration in `event.json` file
### Describe the problem

As currently implemented, the `events.json` file being written does not contain information about the two required columns "onset" and "duration" in the `.json` file.

As those columns are REQURIED, I would propose adding some background information to the `.json` file every time events are written for people who are not familiar with the structure of the `events.tsv` files in.REQUIRED

### Describe your solution

Addiing this to the _events_json_ function

```
  "onset": {
        "Requirement Level": "REQUIRED",
        "Data type": "number",
        "Description": (
            "Onset (in seconds) of the event from the beginning of the first data point. "
            "Negative onsets account for events before the first stored data point. "
            "This column must appear first in the file."
        )
    },
    "duration": {
        "Data type": "number or 'n/a'",
        "Description": (
            "Duration of the event in seconds from onset. Must be zero, positive, or 'n/a' if unavailable. "
            "A zero value indicates an impulse event.\n"
            "This column must appear second in the file."
        )
    }

```

Adding

### Describe possible alternatives

As the documentation about this is specific on the BIDS website, it does not has to be implemented.

### Additional context

_No response_


Discussion:
no objection

On Sun, May 26, 2024 at 11:44 AM jwelzel ***@***.***> wrote:

> Describe the problem
>
> As currently implemented, the events.json file being written does not
> contain information about the two required columns "onset" and "duration"
> in the .json file.
>
> As those columns are REQURIED, I would propose adding some background
> information to the .json file every time events are written for people
> who are not familiar with the structure of the events.tsv files
> in.REQUIRED
> Describe your solution
>
> Addiing this to the *events_json* function
>
>   "onset": {
>         "Requirement Level": "REQUIRED",
>         "Data type": "number",
>         "Description": (
>             "Onset (in seconds) of the event from the beginning of the first data point. "
>             "Negative onsets account for events before the first stored data point. "
>             "This column must appear first in the file."
>         )
>     },
>     "duration": {
>         "Data type": "number or 'n/a'",
>         "Description": (
>             "Duration of the event in seconds from onset. Must be zero, positive, or 'n/a' if unavailable. "
>             "A zero value indicates an impulse event.\n"
>             "This column must appear second in the file."
>         )
>     }
>
>
> Adding
> Describe possible alternatives
>
> As the documentation about this is specific on the BIDS website, it does
> not has to be implemented.
> Additional context
>
> *No response*
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/mne-tools/mne-bids/issues/1254>, or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AABHKHBCV43AQB2QY57DTDLZEGVHBAVCNFSM6AAAAABIJU2PQSVHI2DSMVQWIX3LMV43ASLTON2WKOZSGMYTONRRGA4DONQ>
> .
> You are receiving this because you are subscribed to this thread.Message
> ID: ***@***.***>
>


Resolving patch:
diff --git a/mne_bids/write.py b/mne_bids/write.py
--- a/mne_bids/write.py
+++ b/mne_bids/write.py
@@ -338,7 +338,28 @@ def _events_json(fname, overwrite=False):
         Whether to overwrite the output file if it exists.
     """
     new_data = {
-        "sample": {"Description": "The event onset time in number of sampling points."},
+        "onset": {
+            "Description": (
+                "Onset (in seconds) of the event from the beginning of the first data"
+                "point. Negative onsets account for events before the first stored "
+                "data point."
+            ),
+            "Units": "s",
+        },
+        "duration": {
+            "Description": (
+                "Duration of the event in seconds from onset. "
+                "Must be zero, positive, or 'n/a' if unavailable. "
+                "A zero value indicates an impulse event. "
+            ),
+            "Units": "s",
+        },
+        "sample": {
+            "Description": (
+                "The event onset time in number of sampling points."
+                "First sample is 0."
+            ),
+        },
         "value": {
             "Description": (
                 "The event code (also known as trigger code or event ID) "


Test patch: