Merge branch 'main' into aistats2025

Author: MMathisLab

.github/workflows/docs.yml

@@ -9,6 +9,12 @@ on:
       - main
       - public
       - dev
+    paths:
+      - '**.py'
+      - '**.ipynb'
+      - '**.js'
+      - '**.rst'
+      - '**.md'
 
 jobs:
   build:
@@ -69,6 +75,7 @@ jobs:
           pip install torch --extra-index-url https://download.pytorch.org/whl/cpu
           pip install '.[docs]'
 
+
       - name: Build docs
         run: |
           ls docs/source/cebra-figures

AUTHORS.md

@@ -0,0 +1,28 @@
+<img src="https://github.com/user-attachments/assets/1f327e57-8ee1-4a2f-afd3-2bbce885c2f8" width="200"/>
+
+
+
+CEBRA was initially developed by **Mackenzie Mathis** and **Steffen Schneider** (2021+), who are co-inventors on the patent application [WO2023143843](https://infoscience.epfl.ch/entities/patent/0d9debed-4d22-47b7-bad1-f211e7010323). 
+**Jin Hwa Lee** contributed significantly to our first paper:  
+
+> **Schneider, S., Lee, J.H., & Mathis, M.W.**  
+> [*Learnable latent embeddings for joint behavioural and neural analysis.*](https://doi.org/10.1038/s41586-023-06031-6) 
+> Nature 617, 360–368 (2023)
+
+CEBRA is actively developed by [**Mackenzie Mathis**](https://www.mackenziemathislab.org/) and [**Steffen Schneider**](https://dynamical-inference.ai/) and their labs.  
+
+It is a publicly available tool that has benefited from contributions and suggestions from many individuals: [CEBRA/graphs/contributors](https://github.com/AdaptiveMotorControlLab/CEBRA/graphs/contributors).  
+
+## CEBRA Extensions 
+
+### 2023  
+- **Steffen Schneider, Rodrigo González Laiz, Markus Frey, Mackenzie W. Mathis**  
+  [*Identifiable attribution maps using regularized contrastive learning.*](https://sslneurips23.github.io/paper_pdfs/paper_80.pdf) 
+  NeurIPS 4th Workshop on Self-Supervised Learning: Theory and Practice (2023)
+
+### 2025  
+- **Steffen Schneider, Rodrigo González Laiz, Anastasiia Filippova, Markus Frey, Mackenzie W. Mathis**  
+  [*Time-series attribution maps with regularized contrastive learning.*](https://openreview.net/forum?id=aGrCXoTB4P)  
+  AISTATS (2025)
+
+

cebra/integrations/plotly.py

@@ -28,6 +28,7 @@
 import numpy.typing as npt
 import plotly.graph_objects
 import torch
+import plotly.graph_objects as go
 
 from cebra.integrations.matplotlib import _EmbeddingPlot
 
@@ -154,7 +155,7 @@ def _plot_3d(self, **kwargs) -> plotly.graph_objects.Figure:
 def plot_embedding_interactive(
     embedding: Union[npt.NDArray, torch.Tensor],
     embedding_labels: Optional[Union[npt.NDArray, torch.Tensor, str]] = "grey",
-    axis: Optional[plotly.graph_objects.Figure] = None,
+    axis: Optional["go.Figure"] = None,
     markersize: float = 1,
     idx_order: Optional[Tuple[int]] = None,
     alpha: float = 0.4,
@@ -163,7 +164,7 @@ def plot_embedding_interactive(
     figsize: Tuple[int] = (5, 5),
     dpi: int = 100,
     **kwargs,
-) -> plotly.graph_objects.Figure:
+) -> "go.Figure":
     """Plot embedding in a 3D dimensional space.
 
     This is supposing that the dimensions provided to ``idx_order`` are in the range of the number of

docs/Makefile

@@ -18,6 +18,11 @@ help:
 html:
 	PYTHONPATH=.. $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# Build multiple versions
+html_versions:
+	for v in latest v0.2.0 v0.3.0 v0.4.0; do \
+		PYTHONPATH=.. $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/$$v"; \
+	done
 # Remove the current temp folder and page build
 clean:
 	rm -rf build

docs/source/_static/css/custom.js

@@ -0,0 +1,6 @@
+requirejs.config({
+    paths: {
+        base: '/static/base',
+        plotly: 'https://cdn.plot.ly/plotly-2.12.1.min.js?noext',
+    },
+});

docs/source/_templates/layout.html

@@ -1,11 +1,15 @@
 {% extends "pydata_sphinx_theme/layout.html" %}
 
-{% block fonts %}
+{% block extrahead %}
+    <!-- Load require.js locally from _static -->
+    <script src="{{ pathto('_static/css/custom.js', 1) }}"></script>
+
+{% endblock %}
 
+{% block fonts %}
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300&display=swap" rel="stylesheet">
-
 {% endblock %}
 
 {% block docs_sidebar %}

docs/source/conf.py

@@ -47,8 +47,8 @@ def get_years(start_year=2021):
 
 # -- Project information -----------------------------------------------------
 project = "cebra"
-copyright = f"""{get_years(2021)}, Steffen Schneider, Jin H Lee, Mackenzie Mathis"""
-author = "Steffen Schneider, Jin H Lee, Mackenzie Mathis"
+copyright = f"""{get_years(2021)}"""
+author = "See AUTHORS.md"
 # The full version, including alpha/beta/rc tags
 release = cebra.__version__
 
@@ -57,6 +57,13 @@ def get_years(start_year=2021):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+
+#https://github.com/spatialaudio/nbsphinx/issues/128#issuecomment-1158712159
+html_js_files = [
+    "require.min.js",  # Add to your _static
+    "custom.js",
+]
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
@@ -68,13 +75,13 @@ def get_years(start_year=2021):
     "sphinx_tabs.tabs",
     "sphinx.ext.mathjax",
     "IPython.sphinxext.ipython_console_highlighting",
-    # "sphinx_panels", # Note: package to avoid: no longer maintained.
     "sphinx_design",
     "sphinx_togglebutton",
     "sphinx.ext.doctest",
     "sphinx_gallery.load_style",
 ]
 
+
 coverage_show_missing_items = True
 panels_add_bootstrap_css = False
 
@@ -137,6 +144,21 @@ def get_years(start_year=2021):
 # a list of builtin themes.
 html_theme = "pydata_sphinx_theme"
 
+html_context = {
+    "default_mode": "light",
+    "switcher": {
+        "version_match": "latest",  # Adjust this dynamically per version
+        "versions": [
+            ("latest", "/latest/"),
+            ("v0.2.0", "/v0.2.0/"),
+            ("v0.3.0", "/v0.3.0/"),
+            ("v0.4.0", "/v0.4.0/"),
+            ("v0.5.0rc1", "/v0.5.0rc1/"),
+        ],
+    },
+    "navbar_start": ["version-switcher", "navbar-logo"],  # Place the dropdown above the logo
+}
+
 # More info on theme options:
 # https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/configuring.html
 html_theme_options = {
@@ -197,6 +219,8 @@ def get_years(start_year=2021):
 ]
 
 nbsphinx_thumbnails = {
+    "demo_notebooks/CEBRA_best_practices":
+    "_static/thumbnails/cebra-best.png",
     "demo_notebooks/Demo_primate_reaching":
         "_static/thumbnails/ForelimbS1.png",
     "demo_notebooks/Demo_hippocampus":

docs/source/figures.rst

@@ -1,7 +1,7 @@
 Figures
 =======
 
-CEBRA was introduced in `Schneider, Lee and Mathis (2022)`_ and applied to various datasets across
+CEBRA was introduced in `Schneider, Lee and Mathis (2023)`_ and applied to various datasets across
 animals and recording modalities.
 
 In this section, we provide reference code for reproducing the figures and experiments. Since especially
@@ -56,4 +56,4 @@ differ in minor typographic details.
 
 
 
-.. _Schneider, Lee and Mathis (2022): https://arxiv.org/abs/2204.00673
+.. _Schneider, Lee and Mathis (2023): https://www.nature.com/articles/s41586-023-06031-6

docs/source/index.rst

@@ -34,27 +34,18 @@ Please support the development of CEBRA by starring and/or watching the project
 Installation and Setup
 ----------------------
 
-Please see the dedicated :doc:`Installation Guide </installation>` for information on installation options using ``conda``, ``pip`` and ``docker``.
-
-Have fun! 😁
+Please see the dedicated :doc:`Installation Guide </installation>` for information on installation options using ``conda``, ``pip`` and ``docker``. Have fun! 😁
 
 Usage
 -----
 
 Please head over to the :doc:`Usage </usage>` tab to find step-by-step instructions to use CEBRA on your data. For example use cases, see the :doc:`Demos </demos>` tab.
 
-Integrations
-------------
-
-CEBRA can be directly integrated with existing libraries commonly used in data analysis. The ``cebra.integrations`` module
-is getting actively extended. Right now, we offer integrations for ``scikit-learn``-like usage of CEBRA, a package making use of ``matplotlib`` to plot the CEBRA model results, as well as the
-possibility to compute CEBRA embeddings on DeepLabCut_ outputs directly.
-
 
 Licensing
 ---------
-
-Since version 0.4.0, CEBRA is open source software under an Apache 2.0 license.
+The ideas presented in our package are currently patent pending (Patent No. WO2023143843).
+Since version 0.4.0, CEBRA's source is licenced under an Apache 2.0 license.
 Prior versions 0.1.0 to 0.3.1 were released for academic use only.
 
 Please see the full license file on Github_ for further information.
@@ -65,13 +56,19 @@ Contributing
 
 Please refer to the :doc:`Contributing </contributing>` tab to find our guidelines on contributions.
 
-Code contributors
+Code Contributors
 -----------------
 
-The CEBRA code was originally developed by Steffen Schneider, Jin H. Lee, and Mackenzie Mathis (up to internal version 0.0.2). As of March 2023, it is being actively extended and maintained by `Steffen Schneider`_, `Célia Benquet`_, and `Mackenzie Mathis`_.
+The CEBRA code was originally developed by Steffen Schneider, Jin H. Lee, and Mackenzie Mathis (up to internal version 0.0.2). Please see our AUTHORS file for more information.
 
-References
-----------
+Integrations
+------------
+
+CEBRA can be directly integrated with existing libraries commonly used in data analysis. Namely, we provide a ``scikit-learn`` style interface to use CEBRA. Additionally, we offer integrations with our ``scikit-learn``-style of using CEBRA, a package making use of ``matplotlib`` and ``plotly`` to plot the CEBRA model results, as well as the possibility to compute CEBRA embeddings on DeepLabCut_ outputs directly. If you have another suggestion, please head over to Discussions_ on GitHub_!
+
+
+Key References
+--------------
 .. code::
 
   @article{schneider2023cebra,
@@ -82,14 +79,22 @@ References
     year = {2023},
   }
 
+  @article{xCEBRA2025,
+    author={Steffen Schneider and Rodrigo Gonz{\'a}lez Laiz and Anastasiia Filippova and Markus Frey and Mackenzie W Mathis},
+    title = {Time-series attribution maps with regularized contrastive learning},
+    journal = {AISTATS},
+    url = {https://openreview.net/forum?id=aGrCXoTB4P},
+    year = {2025},
+  }
+
 This documentation is based on the `PyData Theme`_.
 
 
 .. _`Twitter`: https://twitter.com/cebraAI
 .. _`PyData Theme`: https://github.com/pydata/pydata-sphinx-theme
 .. _`DeepLabCut`: https://deeplabcut.org
+.. _`Discussions`: https://github.com/AdaptiveMotorControlLab/CEBRA/discussions
 .. _`Github`: https://github.com/AdaptiveMotorControlLab/cebra
 .. _`email`: mailto:[email protected]
 .. _`Steffen Schneider`: https://github.com/stes
-.. _`Célia Benquet`: https://github.com/CeliaBenquet
 .. _`Mackenzie Mathis`: https://github.com/MMathisLab

docs/source/installation.rst

@@ -4,7 +4,7 @@ Installation Guide
 System Requirements
 -------------------
 
-CEBRA is written in Python (3.8+) and PyTorch. CEBRA is most effective when used with a GPU, but CPU-only support is provided. We provide instructions to run CEBRA on your system directly.  The instructions below were tested on different compute setups with Ubuntu 18.04 or 20.04, using Nvidia GTX 2080, A4000, and V100 cards. Other setups are possible (including Windows), as long as CUDA 10.2+ support is guaranteed.
+CEBRA is written in Python (3.9+) and PyTorch. CEBRA is most effective when used with a GPU, but CPU-only support is provided. We provide instructions to run CEBRA on your system directly.  The instructions below were tested on different compute setups with Ubuntu 18.04 or 20.04, using Nvidia GTX 2080, A4000, and V100 cards. Other setups are possible (including Windows), as long as CUDA 10.2+ support is guaranteed.
 
 - Software dependencies and operating systems:
     - Linux or MacOS
@@ -93,11 +93,11 @@ we outline different options below.
 
         * 🚀 For more advanced users, CEBRA has different extra install options that you can select based on your usecase:
 
-            * ``[integrations]``: This will install (experimental) support for our streamlit and jupyter integrations.
+            * ``[integrations]``: This will install (experimental) support for integrations, such as plotly.
             * ``[docs]``: This will install additional dependencies for building the package documentation.
             * ``[dev]``: This will install additional dependencies for development, unit and integration testing,
               code formatting, etc. Install this extension if you want to work on a pull request.
-            * ``[demos]``: This will install additional dependencies for running our demo notebooks.
+            * ``[demos]``: This will install additional dependencies for running our demo notebooks in Jupyter.
             * ``[datasets]``: This extension will install additional dependencies to use the pre-installed datasets
               in ``cebra.datasets``.