Merge branch 'main' into r/0.40

.readthedocs.yml

@@ -13,3 +13,6 @@ build:
 
 conda:
   environment: "env-readthedocs.yml"
+
+sphinx:
+  configuration: doc/conf.py

doc/experiment.rst

@@ -279,8 +279,8 @@ ICA
 ---
 
 If preprocessing includes ICA, select which ICA components should be removed.
-To open the ICA selection GUI, The experiment ``raw`` state needs to be set to
-the ICA stage of the pipeline::
+To open the ICA selection GUI, The experiment :ref:`state-raw` state needs to be
+set to the ICA stage of the pipeline::
 
     >>> e.set(raw='ica')
     >>> e.make_ica_selection()

doc/installing.rst

@@ -71,13 +71,23 @@ Eelbrain can then be used from this environment, for example through `Jupyter La
     (eelbrain) $ jupyter lab
 
 
+.. SEEALSO::
+    Mamba is an extension of `Conda <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html>`_. The Conda documentation provides more information on `environments <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_.
+
+
+Updating
+^^^^^^^^
+
 In an existing environment, Eelbrain can generally be updated with the following command (assuming the target environment is currently active):
 
 .. code-block:: bash
 
     (eelbrain) $ mamba update eelbrain
 
 
+However, in complex environments this can lead to package conflicts (mamba will display an error message).
+In such cases it may be easier to just cerate a new environment.
+
 The currently installed version can be displayed with the ``mamba list`` command:
 
 .. code-block:: bash
@@ -90,9 +100,6 @@ The currently installed version can be displayed with the ``mamba list`` command
 
 Sometimes Mamba may run into difficulties while updating and it may be easier to create a new environment instead.
 
-.. SEEALSO::
-    Mamba is an extension of `Conda <https://conda.io/projects/conda/en/latest/user-guide/getting-started.html>`_. The Conda documentation provides more information on `environments <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_.
-
 
 Making your analysis future-proof
 ---------------------------------

eelbrain/_io/pickle.py

@@ -45,7 +45,7 @@ def find_class(self, module, name):
 
 
 def pickle(obj: Any, dest: PathArg = None, protocol: int = HIGHEST_PROTOCOL):
-    """Pickle a Python object.
+    """Pickle a Python object (see :mod:`pickle`).
 
     Parameters
     ----------
@@ -66,7 +66,7 @@ def pickle(obj: Any, dest: PathArg = None, protocol: int = HIGHEST_PROTOCOL):
 
     See Also
     --------
-    save.pickle
+    eelbrain.load.unpickle
     """
     if dest is None:
         filetypes = [("Pickled Python Objects (*.pickle)", '*.pickle')]
@@ -103,20 +103,21 @@ def unpickle(path: PathArg = None):
 
     Notes
     -----
+    This function is similar to Python's builtin :mod:`pickle`
+    ``pickle.load(open(path))``, but also loads object saved
+    with older versions of Eelbrain, and allows using a system file dialog to
+    select a file.
+
     If you see ``ValueError: unsupported pickle protocol``, the pickle file
     was saved with a higher version of Python; in order to make pickles
     backwards-compatible, use :func:`~eelbrain.save.pickle` with a lower
     ``protocol=2``.
     To batch-convert multiple pickle files, use :func:`~eelbrain.load.convert_pickle_protocol`
 
-    This function is similar to ``pickle.load(open(path))``, but also loads object saved
-    with older versions of Eelbrain, and allows using a system file dialog to
-    select a file.
-
     See Also
     --------
-    load.unpickle
-    load.convert_pickle_protocol
+    eelbrain.save.pickle
+    eelbrain.load.convert_pickle_protocol
     """
     if path is None:
         filetypes = [("Pickles (*.pickle)", '*.pickle'), ("All files", '.*')]

eelbrain/plot/_brain_object.py

@@ -158,6 +158,23 @@ class Brain(TimeSlicer, surfer.Brain):
     The documentation lists only the methods that Eelbrain adds to or overrides
     from the PySurfer :class:`~surfer.Brain` super-class. For complete PySurfer
     functionality see te PySurfer documentation.
+
+    Initializing a :class:`Brain` object is expensive. When plotting multiple
+    overlays on the same brain, it is more economical to initialize only one
+    :class:`Brain` object and adding/removing the data layers in a loop.
+    Pseudo-code for an example adding images to a table::
+
+        table = fmtxt.Table('ll')
+        b = brain(source_space, hemi=hemi, …)
+        for data_layer in data_layers:
+            table.cell(data_layer.name)
+            b.add_ndvar(data_layer, ...)
+            im = b.image()
+            table.cell(im)
+            b.remove_data()
+            b.remove_labels()
+
+    For another example see the implementation of :class:`SequencePlotter`.
     """
     _display_time_in_frame_title = True
 

env-readthedocs.yml

@@ -12,7 +12,7 @@ dependencies:
 - mne-base >=1.0
 - nibabel >2.3.0  # read_annot bug
 - nilearn >=0.10.4
-- numpy >=1.11
+- numpy >=1.11, <2
 - pillow
 - pip
 - pooch  # for mne dataset downloading