[ADD] describing fields in event.json file (#1255)

* [ADD] describing fields in `event.json` file for the REQUIRED onset and duration columns

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* fix line length <88

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* remove column position from description

* only provide description and onset for the json

* refine description of sample

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* satisfy contributing guidelines

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* move author to correct position in CITATION.cff

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>

CITATION.cff

@@ -175,6 +175,10 @@ authors:
       family-names: Wolter
       orcid: 'https://orcid.org/0000-0002-6785-9886'
       affiliation: 'Centre for Integrative Neuroscience, Tübingen, Germany'
+    - given-names: Julius
+      family-names: Welzel
+      affiliation: 'Department of Neurology, Kiel University, Germany'
+      orcid: 'https://orcid.org/0000-0003-4782-5360'
     - given-names: Alexandre
       family-names: Gramfort
       affiliation: 'Université Paris-Saclay, Inria, CEA, Palaiseau, France'

doc/authors.rst

@@ -45,3 +45,4 @@
 .. _Ford McDonald: https://github.com/fordmcdonald
 .. _Pierre Guetschel: https://github.com/PierreGtch
 .. _Mara Wolter: https://github.com/marakw
+.. _Julius Welzel: https://github.com/JuliusWelzel

doc/whats_new.rst

@@ -19,6 +19,7 @@ The following authors contributed for the first time. Thank you so much! 🤩
 
 * `Daniel McCloy`_
 * `Mara Wolter`_
+* `Julius Welzel`_
 
 The following authors had contributed before. Thank you for sticking around! 🤘
 
@@ -34,7 +35,7 @@ Detailed list of changes
 🚀 Enhancements
 ^^^^^^^^^^^^^^^
 
-- nothing yet
+- Including a description for ``onset`` and  ``duration`` in the ``events.json`` file, by `Julius Welzel`_ (:gh:`1255`)
 
 🧐 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

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) "