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.

…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.

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

 .. _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.

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.

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

+        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



-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

+
+    @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

+        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

+
+    @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

+        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

+        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

+
+    @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

+        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

+        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

+        # 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

Famous077 · 2026-05-04T22:01:16Z

Hi @larsoner , This PR has been in pending state since last month, Can you review whenever you get time.

larsoner · 2026-05-05T15:09:48Z

I'd rather let @scott-huberty or @drammock look since they've already been thinking about this!

cbrnr

Hello @Famous077! I've added some commits to get this PR merged (please check if these are OK for you, there was one critical missing length check for ch_names). IMO this is now ready for merge as all comments have been addressed. @scott-huberty and @drammock OK for you?

cbrnr · 2026-05-27T11:17:26Z

Not sure what the problem with the CircleCI docs preview is though...

tsbinns · 2026-05-27T12:05:46Z

@cbrnr Looks like the same thing that was happening here, where it thinks it's trying to build stable docs so just exits: #13846 (comment)

@drammock @larsoner Was there any headway on figuring out how to sort this?

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

Comment thread mne/annotations.py

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

Comment thread mne/annotations.py

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

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

Comment thread mne/annotations.py

Famous077 requested review from scott-huberty May 4, 2026 21:51

larsoner mentioned this pull request May 26, 2026

Convert np.str_ to regular str in Annotations? #13922

Closed

cbrnr added 5 commits May 27, 2026 07:14

Validate ch_names length

bae3b81

Use np.atleast_1d() for consistency

0900064

Fix error message

324831c

Remove redundant check

9aea4c6

Add ch_names check

7f920a8

cbrnr approved these changes May 27, 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!

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!

Uh oh!

Famous077 commented May 4, 2026

Uh oh!

larsoner commented May 5, 2026

Uh oh!

cbrnr left a comment • 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!

cbrnr commented May 27, 2026

Uh oh!

tsbinns commented May 27, 2026

Uh oh!

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

cbrnr left a comment •

edited

Loading