From 3efb3c30f89d4ddaf3d9309ad22ffa84a2f597eb Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Thu, 4 Jul 2024 11:41:03 +0200 Subject: [PATCH 1/9] DOC: match_channel_orders works on Epochs and Evoked, too --- mne/io/base.py | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/mne/io/base.py b/mne/io/base.py index d419bcb548f..d1b525ed288 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -3083,25 +3083,27 @@ def concatenate_raws( @fill_doc -def match_channel_orders(raws, copy=True): - """Ensure consistent channel order across raws. +def match_channel_orders(insts, copy=True): + """Ensure consistent channel order across instances (Raw, Epochs, or Evoked). Parameters ---------- - raws : list - List of :class:`~mne.io.Raw` instances to order. + insts : list + List of :class:`~mne.io.Raw`, :class:`~mne.io.Epochs`, + or :class:`~mne.io.Evoked` instances to order. %(copy_df)s Returns ------- - list of Raw - List of Raws with matched channel orders. + list of inst + List of instances (Raw, Epochs, or Evoked) with matched + channel orders. """ - raws = deepcopy(raws) if copy else raws - ch_order = raws[0].ch_names - for raw in raws[1:]: - raw.reorder_channels(ch_order) - return raws + insts = deepcopy(insts) if copy else insts + ch_order = insts[0].ch_names + for inst in insts[1:]: + inst.reorder_channels(ch_order) + return insts def _check_maxshield(allow_maxshield): From cb9cf2740f73c610df0a4208768a9d53212a33dc Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Fri, 5 Jul 2024 17:30:34 +0200 Subject: [PATCH 2/9] fix references --- mne/io/base.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mne/io/base.py b/mne/io/base.py index d1b525ed288..2f7d4f89cbc 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -3089,13 +3089,13 @@ def match_channel_orders(insts, copy=True): Parameters ---------- insts : list - List of :class:`~mne.io.Raw`, :class:`~mne.io.Epochs`, - or :class:`~mne.io.Evoked` instances to order. + List of :class:`~mne.io.Raw`, :class:`~mne.Epochs`, + or :class:`~mne.Evoked` instances to order. %(copy_df)s Returns ------- - list of inst + list of Raw | list of Epochs | list of Evoked List of instances (Raw, Epochs, or Evoked) with matched channel orders. """ From e37de9f6e014ff2e71d8d5da3b3031a11235903f Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Fri, 12 Jul 2024 10:31:05 +0200 Subject: [PATCH 3/9] add deprecation --- mne/io/base.py | 16 +++++++++++++--- mne/io/fiff/tests/test_raw_fiff.py | 8 ++++++-- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/mne/io/base.py b/mne/io/base.py index 2f7d4f89cbc..49db9c73160 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -3083,7 +3083,7 @@ def concatenate_raws( @fill_doc -def match_channel_orders(insts, copy=True): +def match_channel_orders(insts, copy=True, *, raws=None): """Ensure consistent channel order across instances (Raw, Epochs, or Evoked). Parameters @@ -3092,13 +3092,23 @@ def match_channel_orders(insts, copy=True): List of :class:`~mne.io.Raw`, :class:`~mne.Epochs`, or :class:`~mne.Evoked` instances to order. %(copy_df)s + raws : list + This parameter is deprecated and will be removed in mne version 1.9. + Please use `insts` instead. Returns ------- list of Raw | list of Epochs | list of Evoked - List of instances (Raw, Epochs, or Evoked) with matched - channel orders. + List of instances (Raw, Epochs, or Evoked) with channel orders matched + according to the order they had in the first item in the `insts` list. """ + if raws is not None: + warn( + "The ``raws`` parameter is deprecated and will be removed in version " + "1.9. Use the ``insts`` parameter to suppress this warning.", + DeprecationWarning, + ) + insts = raws insts = deepcopy(insts) if copy else insts ch_order = insts[0].ch_names for inst in insts[1:]: diff --git a/mne/io/fiff/tests/test_raw_fiff.py b/mne/io/fiff/tests/test_raw_fiff.py index b6abb73b926..accd4fb2eac 100644 --- a/mne/io/fiff/tests/test_raw_fiff.py +++ b/mne/io/fiff/tests/test_raw_fiff.py @@ -475,11 +475,15 @@ def test_concatenate_raws_order(): with pytest.raises(ValueError, match="Channel order must match."): # still fails, because raws is copied and not changed in place - match_channel_orders(raws, copy=True) + match_channel_orders(insts=raws, copy=True) raw_concat = concatenate_raws(raws) + # XXX: remove in version 1.9 + with pytest.raises(DeprecationWarning, match="``raws`` parameter is deprecated"): + match_channel_orders(raws=raws) + # Now passes because all raws have the same order - match_channel_orders(raws, copy=False) + match_channel_orders(insts=raws, copy=False) raw_concat = concatenate_raws(raws) ch0 = raw_concat.get_data(picks=["0"]) assert np.all(ch0 == 0) From 3f0996e881343d5a760341d17169766c3be2826e Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Fri, 12 Jul 2024 10:38:08 +0200 Subject: [PATCH 4/9] add changelog entry --- doc/changes/devel/12699.api.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 doc/changes/devel/12699.api.rst diff --git a/doc/changes/devel/12699.api.rst b/doc/changes/devel/12699.api.rst new file mode 100644 index 00000000000..18d91a54e5a --- /dev/null +++ b/doc/changes/devel/12699.api.rst @@ -0,0 +1 @@ +Documented that :func:`~mne.match_channel_orders` can also work on Epochs, and Evoked objects. Reflecting this, deprecated the ``raws`` parameter in favor of an ``insts``parameter, by `Stefan Appelhoff`_. From f79c77860732481471d148d7a78f40eaf25e2660 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Fri, 12 Jul 2024 10:39:15 +0200 Subject: [PATCH 5/9] fix typo --- doc/changes/devel/12699.api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/changes/devel/12699.api.rst b/doc/changes/devel/12699.api.rst index 18d91a54e5a..37f489afeb6 100644 --- a/doc/changes/devel/12699.api.rst +++ b/doc/changes/devel/12699.api.rst @@ -1 +1 @@ -Documented that :func:`~mne.match_channel_orders` can also work on Epochs, and Evoked objects. Reflecting this, deprecated the ``raws`` parameter in favor of an ``insts``parameter, by `Stefan Appelhoff`_. +Documented that :func:`~mne.match_channel_orders` can also work on Epochs, and Evoked objects. Reflecting this, deprecated the ``raws`` parameter in favor of an ``insts`` parameter, by `Stefan Appelhoff`_. From 038aac769863ba352c0473b303c63d35315f77b2 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Fri, 12 Jul 2024 12:07:25 +0200 Subject: [PATCH 6/9] fix func and tests --- doc/changes/devel/{12699.api.rst => 12699.apichange.rst} | 0 mne/io/base.py | 9 ++++++++- mne/io/fiff/tests/test_raw_fiff.py | 4 ++++ 3 files changed, 12 insertions(+), 1 deletion(-) rename doc/changes/devel/{12699.api.rst => 12699.apichange.rst} (100%) diff --git a/doc/changes/devel/12699.api.rst b/doc/changes/devel/12699.apichange.rst similarity index 100% rename from doc/changes/devel/12699.api.rst rename to doc/changes/devel/12699.apichange.rst diff --git a/mne/io/base.py b/mne/io/base.py index 49db9c73160..3b938d93851 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -3083,7 +3083,7 @@ def concatenate_raws( @fill_doc -def match_channel_orders(insts, copy=True, *, raws=None): +def match_channel_orders(insts=None, copy=True, *, raws=None): """Ensure consistent channel order across instances (Raw, Epochs, or Evoked). Parameters @@ -3102,6 +3102,8 @@ def match_channel_orders(insts, copy=True, *, raws=None): List of instances (Raw, Epochs, or Evoked) with channel orders matched according to the order they had in the first item in the `insts` list. """ + # XXX: remove "raws" parameter and logic below with MNE version 1.9 + # and remove default parameter value of insts if raws is not None: warn( "The ``raws`` parameter is deprecated and will be removed in version " @@ -3109,6 +3111,11 @@ def match_channel_orders(insts, copy=True, *, raws=None): DeprecationWarning, ) insts = raws + elif insts is None: + # both insts and raws is None + raise ValueError( + "You need to pass a list of Raw, Epochs, or Evoked to ``insts``." + ) insts = deepcopy(insts) if copy else insts ch_order = insts[0].ch_names for inst in insts[1:]: diff --git a/mne/io/fiff/tests/test_raw_fiff.py b/mne/io/fiff/tests/test_raw_fiff.py index accd4fb2eac..a115fbda9a4 100644 --- a/mne/io/fiff/tests/test_raw_fiff.py +++ b/mne/io/fiff/tests/test_raw_fiff.py @@ -482,6 +482,10 @@ def test_concatenate_raws_order(): with pytest.raises(DeprecationWarning, match="``raws`` parameter is deprecated"): match_channel_orders(raws=raws) + # XXX: remove in version 1.9 + with pytest.raises(ValueError, match="need to pass a list"): + match_channel_orders() + # Now passes because all raws have the same order match_channel_orders(insts=raws, copy=False) raw_concat = concatenate_raws(raws) From e0899baaa0b49a44fb47c3cfb29f931b8502970a Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 12 Jul 2024 10:50:41 -0400 Subject: [PATCH 7/9] Update mne/io/fiff/tests/test_raw_fiff.py --- mne/io/fiff/tests/test_raw_fiff.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/io/fiff/tests/test_raw_fiff.py b/mne/io/fiff/tests/test_raw_fiff.py index a115fbda9a4..3b5949539dd 100644 --- a/mne/io/fiff/tests/test_raw_fiff.py +++ b/mne/io/fiff/tests/test_raw_fiff.py @@ -479,7 +479,7 @@ def test_concatenate_raws_order(): raw_concat = concatenate_raws(raws) # XXX: remove in version 1.9 - with pytest.raises(DeprecationWarning, match="``raws`` parameter is deprecated"): + with pytest.warns(DeprecationWarning, match="``raws`` parameter is deprecated"): match_channel_orders(raws=raws) # XXX: remove in version 1.9 From d800e75c146d2ad1963779a24698d2d90a0c9df4 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 12 Jul 2024 11:08:52 -0400 Subject: [PATCH 8/9] Update mne/io/base.py --- mne/io/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/io/base.py b/mne/io/base.py index 3b938d93851..d78729e2419 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -3094,7 +3094,7 @@ def match_channel_orders(insts=None, copy=True, *, raws=None): %(copy_df)s raws : list This parameter is deprecated and will be removed in mne version 1.9. - Please use `insts` instead. + Please use ``insts`` instead. Returns ------- From 361fbe0062e8ff89efbe2c73e798c77cedb22c80 Mon Sep 17 00:00:00 2001 From: Eric Larson Date: Fri, 12 Jul 2024 11:25:30 -0400 Subject: [PATCH 9/9] Update base.py --- mne/io/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mne/io/base.py b/mne/io/base.py index d78729e2419..a1485e6caf6 100644 --- a/mne/io/base.py +++ b/mne/io/base.py @@ -3100,7 +3100,7 @@ def match_channel_orders(insts=None, copy=True, *, raws=None): ------- list of Raw | list of Epochs | list of Evoked List of instances (Raw, Epochs, or Evoked) with channel orders matched - according to the order they had in the first item in the `insts` list. + according to the order they had in the first item in the ``insts`` list. """ # XXX: remove "raws" parameter and logic below with MNE version 1.9 # and remove default parameter value of insts