From 0822c48f2da8cdbbb21ba884e8aea0cc078ac978 Mon Sep 17 00:00:00 2001 From: Christian Brodbeck Date: Thu, 28 Nov 2024 10:33:57 -0500 Subject: [PATCH 1/2] DOC --- doc/experiment.rst | 4 ++-- doc/installing.rst | 13 ++++++++++--- eelbrain/_io/pickle.py | 17 +++++++++-------- eelbrain/plot/_brain_object.py | 17 +++++++++++++++++ 4 files changed, 38 insertions(+), 13 deletions(-) diff --git a/doc/experiment.rst b/doc/experiment.rst index 39a0508cc..d5bff3ff6 100644 --- a/doc/experiment.rst +++ b/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() diff --git a/doc/installing.rst b/doc/installing.rst index cb7e191da..cdc5ff2f8 100755 --- a/doc/installing.rst +++ b/doc/installing.rst @@ -71,6 +71,13 @@ Eelbrain can then be used from this environment, for example through `Jupyter La (eelbrain) $ jupyter lab +.. SEEALSO:: + Mamba is an extension of `Conda `_. The Conda documentation provides more information on `environments `_. + + +Updating +^^^^^^^^ + In an existing environment, Eelbrain can generally be updated with the following command (assuming the target environment is currently active): .. code-block:: bash @@ -78,6 +85,9 @@ In an existing environment, Eelbrain can generally be updated with the following (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 `_. The Conda documentation provides more information on `environments `_. - Making your analysis future-proof --------------------------------- diff --git a/eelbrain/_io/pickle.py b/eelbrain/_io/pickle.py index 2ba453a5b..c76fdc1e7 100644 --- a/eelbrain/_io/pickle.py +++ b/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", '.*')] diff --git a/eelbrain/plot/_brain_object.py b/eelbrain/plot/_brain_object.py index 6600ca92c..d5aeab062 100644 --- a/eelbrain/plot/_brain_object.py +++ b/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 From c0ae69faad53ca63b2cd15371d05b77e00286d40 Mon Sep 17 00:00:00 2001 From: Christian Brodbeck Date: Tue, 7 Jan 2025 16:08:16 -0500 Subject: [PATCH 2/2] readthedocs: configuration & pin numpy < 2 --- .readthedocs.yml | 3 +++ env-readthedocs.yml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 24c179989..94205ed65 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -13,3 +13,6 @@ build: conda: environment: "env-readthedocs.yml" + +sphinx: + configuration: doc/conf.py diff --git a/env-readthedocs.yml b/env-readthedocs.yml index 49d88ba83..09f519da1 100644 --- a/env-readthedocs.yml +++ b/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