DOC: document onset, duration, description, and ch_names attributes of mne.Annotations by Famous077 · Pull Request #13680 · mne-tools/mne-python

Famous077 · 2026-02-24T14:10:52Z

What does this implement/fix?

--> I have Converted onset, duration, description, and ch_names from plain
instance attributes to documented properties in mne/annotations.py,
so they appear in the API reference with proper NumPy-style docstrings.

Additional information

--> Even experienced MNE users were unaware these attributes existed because
they did not appear in the generated API documentation. A changelog entry
has been added in doc/changes/dev/12379.other.rst.

…ions

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

scott-huberty · 2026-02-24T15:54:58Z

@Famous077 can you please sign in to CircleCI via the sign in with Github option? After you do this and push a commit to this branch, the build docs job should run.

mne/annotations.py

…github.com/Famous077/mne-python into doc/annotations-onset-duration-description

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

Famous077 · 2026-03-06T20:00:16Z

Hi @larsoner @drammock , Changes have been done as per the suggestions. Can you review it whenever you get time. Waiting for your feedback. Hope changes will be helpful for the org.

mne/annotations.py

drammock

on main users are free to mutate my_annots.duration pretty freely.. At least compared to the set_annotations route that contains some checks [...] I'm not sure if that was just an oversight. Do we want to be more strict about correctness in these setters, similar to what's done in _check_o_d_s_c_e?

After a real-time chat with @scott-huberty, I think it makes sense to leverage our code in _check_o_d_s_c_e to validate the input to the setters. May require a slight refactor of _check_o_d_s_c_e to avoid duplicating code (so that, e.g., checking descriptions can be done independently of checking onsets, durations, etc)

drammock · 2026-03-11T16:16:01Z

doc/changes/names.inc

 .. _Ezequiel Mikulan: https://github.com/ezemikulan
 .. _Fahimeh Mamashli: https://github.com/fmamashli
-.. _Famous Raj Bhat: https://github.com/Famous077
+.. _Famous077: https://github.com/Famous077


this will break the xref in previously-merged changelog entries, please use the same name for all your PRs.

mne/annotations.py

drammock · 2026-03-11T16:28:36Z

also, please add closes #12379 to the PR description, so that when this is merged, the motiviating issue will auto-close

Famous077 · 2026-03-11T18:51:54Z

also, please add closes #12379 to the PR description, so that when this is merged, the motiviating issue will auto-close

@drammock , Sorry for the delay, due to exams . Mistakely I mentioned issue number inside the default description template . Now, I have updated accordingly.

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

Famous077 · 2026-03-19T10:50:52Z

@drammock Can you review this PR whenever you get time. Let me know if anything needs to be changed.

I see no changes since my last review, other than merges of main. Please address my past review's feedback first.

Hi @drammock, I have addressed all the feedbacks. Can you review it whenever you feel free. Let me know if anything I missed to implement. Waiting for you feedback.

scott-huberty · 2026-03-19T14:26:24Z

Hi @drammock, I have addressed all the feedbacks. Can you review it whenever you feel free. Let me know if anything I missed to implement. Waiting for you feedback.

@Famous077 you missed a comment here and probably here

Here is a small snippet to help give you an idea of the hard edges we are trying to help users avoid. This is why Dan suggested looking into what checks we are doing in _check_o_d_s_c_e(sic) (which gets called when you do .set_annotaitons), and replicate the relevant checks in our setters, ideally without duplicating code.

fpath = mne.datasets.sample.data_path() / "MEG" / "sample" / "sample_audvis_raw.fif"
raw = mne.io.read_raw_fif(fpath)

annots = mne.Annotations(onset=[1,3,2,4], duration=0, description="foo")
raw.set_annotations(annots)
raw.annotations.description = raw.annotations.description[:2] # 🚨 Now this has a different length than onset, duration etc

…tters

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

Famous077 · 2026-03-19T16:59:31Z

Hi @scott-huberty , Changes have been implemented as per the suggestion. Can you verify it is working correctly or not?

…etter validation error

mne/annotations.py

drammock · 2026-03-20T21:12:08Z

@scott-huberty LMK when you're satisfied and I'll take another look

…private attribute usage in append

Famous077 · 2026-03-20T21:24:42Z

Hi @scott-huberty , I have addressed your suggestion, All 170 tests pass. Please review when you get a chance if anything else need to be implemented.

scott-huberty · 2026-03-20T23:02:27Z

mne/annotations.py

+        Annotations.duration : Duration of each annotation.
+        Annotations.description : Description of each annotation.


Suggested change

Annotations.duration : Duration of each annotation.

Annotations.description : Description of each annotation.

:attr:`~mne.Annotations.duration`

:attr:`~mne.Annotations.description`

I think this should work..

…properties

Famous077 · 2026-03-21T10:28:03Z

Hi @scott-huberty , Updated all See Also sections to use :attr: cross-references as suggested. All tests still pass. Let me know if anything else needs changing.

scott-huberty

@drammock ready for you to take a final review.

Famous077 · 2026-03-30T20:33:15Z

Hi @drammock , I have addressed all the suggestions given. Can you review it whenever you get time. Waiting for your feedback.

drammock

jointly reviewed with @scott-huberty

drammock · 2026-04-01T16:47:54Z

mne/annotations.py



-def _check_o_d_s_c_e(onset, duration, description, ch_names, extras):
+def _check_onset(onset):


this should take an n parameter too, like _check_duration does

drammock · 2026-04-01T16:48:33Z

mne/annotations.py

+
+    @onset.setter
+    def onset(self, onset):
+        onset = _check_onset(onset)


Suggested change

onset = _check_onset(onset)

onset = _check_onset(onset, n=len(self._onset))

drammock · 2026-04-01T16:49:03Z

mne/annotations.py

+        if len(onset) != len(self._duration):
+            raise ValueError(
+                f"Length of onset ({len(onset)}) must match the length of "
+                f"existing duration ({len(self._duration)})."
+            )


with other suggested changes, I think this could then go away.

drammock · 2026-04-01T16:49:43Z

mne/annotations.py

+
+    @duration.setter
+    def duration(self, duration):
+        n = len(self._onset)


Suggested change

n = len(self._onset)

n = len(self._duration)

this shouldn't make a difference... but as written it looks like a typo to be checking onset length in the duration setter. More maintainable this way.

drammock · 2026-04-01T16:51:50Z

mne/annotations.py

+        if len(duration) != n:
+            raise ValueError(
+                f"Length of duration ({len(duration)}) must match the length of "
+                f"existing onset ({n})."
+            )


shouldn't this be guaranteed by _check_duration succeeding?

drammock · 2026-04-01T16:52:34Z

mne/annotations.py

+        if len(description) != n:
+            raise ValueError(
+                f"Length of description ({len(description)}) must match the "
+                f"length of existing onset ({n})."
+            )


should be guaranteed by success of _check_description

drammock · 2026-04-01T16:55:42Z

mne/annotations.py

+
+    @ch_names.setter
+    def ch_names(self, ch_names):
+        n = len(self._onset)


Suggested change

n = len(self._onset)

n = len(self._ch_names)

drammock · 2026-04-01T16:56:14Z

mne/annotations.py

+        if len(ch_names) != n:
+            raise ValueError(
+                f"Length of ch_names ({len(ch_names)}) must match the length of "
+                f"existing onset ({n})."
+            )
+        self._ch_names = ch_names


should be guaranteed by successful _check_ch_names right?

drammock · 2026-04-01T16:58:00Z

mne/annotations.py

+        self._onset = state["onset"]
+        self._duration = state["duration"]
+        self._description = state["description"]
+        self._ch_names = state["ch_names"]
+        self._extras = state.get("_extras", [None] * len(self._onset))


use the new _check_* functions (or check_odsce) here before setting the private attributes.

drammock · 2026-04-01T17:00:30Z

mne/annotations.py

+        # Write directly to private attributes to avoid triggering the public
+        # setter validation, which would raise an error due to temporary length
+        # mismatches while fields are being extended one at a time.
+        # The data is already validated by _check_o_d_s_c_e above.


this comment is in the wrong place??

…ove comment to correct location

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

…in HEDAnnotations.__setstate__

Famous077 · 2026-04-05T05:16:19Z

Hi @drammock , Hi, I've implemented the required changes as per the suggestions. Could you please review the PR when you get a chance and let me know if anything needs to be updated or improved. Thank you

scott-huberty · 2026-04-07T00:35:09Z

mne/annotations.py

+def _check_onset(onset, n=None):
+    """Convert and validate onset to a 1D float array."""
    onset = np.atleast_1d(np.array(onset, dtype=float))
    if onset.ndim != 1:
        raise ValueError(
            f"Onset must be a one dimensional array, got {onset.ndim} (shape "
            f"{onset.shape})."
        )
+    if n is not None and len(onset) != n:


I don't see any instances in which we pass _check_onset(..., n=None). Do we really need to make it optional?

Hi @scott-huberty , The n=None default is needed because _check_onset is called in two places - once inside _check_o_d_s_c_e without n, since length validation is handled there separately, and once in the onset setter with n=len(self._onset) to validate against existing duration. So making it optional lets us reuse the same function in both contexts without duplicating code. Happy to refactor if you prefer a different approach.

DOC: document onset, duration, description, ch_names attrs of Annotat…

0f70809

…ions

Famous077 requested review from agramfort, drammock and larsoner as code owners February 24, 2026 14:10

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

31c138e

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

scott-huberty reviewed Feb 24, 2026

View reviewed changes

mne/annotations.py Show resolved Hide resolved

Famous077 added 8 commits February 24, 2026 23:43

DOC: trigger CircleCI build

6cef5a6

Merge branch 'doc/annotations-onset-duration-description' of https://…

aa3c052

…github.com/Famous077/mne-python into doc/annotations-onset-duration-description

DOC: add validation to onset, duration, description setters

0de9d78

Merge branch 'main' into doc/annotations-onset-duration-description

9dab228

DOC: remove length validation from setters to avoid internal conflicts

bd5e6ab

Merge branch 'doc/annotations-onset-duration-description' of https://…

161838f

…github.com/Famous077/mne-python into doc/annotations-onset-duration-description

DOC: fix contributor name format in changelog

1edf047

Merge branch 'main' into doc/annotations-onset-duration-description

34c420f

Famous077 requested a review from scott-huberty February 27, 2026 20:45

Famous077 and others added 6 commits March 5, 2026 19:34

Merge branch 'main' into doc/annotations-onset-duration-description

2396495

Merge branch 'main' into doc/annotations-onset-duration-description

5732911

DOC: fix changelog filename and add Famous077 to names.inc

5b59b56

DOC: remove duplicate Famous Raj Bhat entry from names.inc

430e408

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

74f44f6

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

Merge branch 'main' into doc/annotations-onset-duration-description

519c401

Merge branch 'main' into doc/annotations-onset-duration-description

43adc6c

scott-huberty reviewed Mar 11, 2026

View reviewed changes

mne/annotations.py Show resolved Hide resolved

drammock requested changes Mar 11, 2026

View reviewed changes

Merge branch 'main' into doc/annotations-onset-duration-description

dd449ac

Famous077 requested a review from scott-huberty March 11, 2026 18:53

Famous077 and others added 3 commits March 19, 2026 14:09

DOC: revert contributor name to Famous077 for consistency

a014f91

Merge branch 'main' into doc/annotations-onset-duration-description

05ae8c3

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

b20ab9f

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

scott-huberty marked this pull request as draft March 19, 2026 14:26

Famous077 and others added 2 commits March 19, 2026 22:17

ENH: validate array lengths in onset/duration/description/ch_names se…

58816a0

…tters

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

a5aa6a0

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

Famous077 marked this pull request as ready for review March 19, 2026 16:51

FIX: use private attributes in HEDAnnotations __setstate__ to avoid s…

40ab2d2

…etter validation error

scott-huberty reviewed Mar 19, 2026

View reviewed changes

mne/annotations.py Outdated Show resolved Hide resolved

scott-huberty reviewed Mar 20, 2026

View reviewed changes

mne/annotations.py Show resolved Hide resolved

DOC: add cross-reference hyperlinks in See Also sections and clarify …

9157d6d

…private attribute usage in append

scott-huberty reviewed Mar 20, 2026

View reviewed changes

DOC: use :attr: cross-references in See Also sections of Annotations …

5db54f2

…properties

Famous077 requested a review from scott-huberty March 21, 2026 10:29

scott-huberty approved these changes Mar 25, 2026

View reviewed changes

Famous077 requested a review from scott-huberty March 30, 2026 20:33

drammock requested changes Apr 1, 2026

View reviewed changes

Famous077 and others added 3 commits April 4, 2026 12:50

ENH: add length validation to _check_onset, fix description setter, m…

eb45f5b

…ove comment to correct location

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

dc2516d

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

FIX: add length validation to _check_duration and restore hed_string …

8b5a5dc

…in HEDAnnotations.__setstate__

Famous077 requested a review from drammock April 5, 2026 05:03

scott-huberty reviewed Apr 7, 2026

View reviewed changes

		Annotations.duration : Duration of each annotation.
		Annotations.description : Description of each annotation.



		def _check_o_d_s_c_e(onset, duration, description, ch_names, extras):
		def _check_onset(onset):

	onset = _check_onset(onset)
	onset = _check_onset(onset, n=len(self._onset))

Uh oh!

Conversation

Famous077 commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this implement/fix?

Additional information

Uh oh!

scott-huberty commented Feb 24, 2026

Uh oh!

Uh oh!

Famous077 commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

drammock left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

drammock commented Mar 11, 2026

Uh oh!

Famous077 commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Famous077 commented Mar 19, 2026

Uh oh!

scott-huberty commented Mar 19, 2026

Uh oh!

Famous077 commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

drammock commented Mar 20, 2026

Uh oh!

Famous077 commented Mar 20, 2026

Uh oh!

scott-huberty Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Famous077 commented Mar 21, 2026

Uh oh!

scott-huberty left a comment

Choose a reason for hiding this comment

Uh oh!

Famous077 commented Mar 30, 2026

Uh oh!

drammock left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Famous077 commented Apr 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Famous077 commented Feb 24, 2026 •

edited

Loading

Famous077 commented Mar 6, 2026 •

edited

Loading

Famous077 commented Mar 11, 2026 •

edited

Loading

scott-huberty Mar 20, 2026 •

edited

Loading