Merge branch 'main' into add_options_mixed

stes · web-flow · commit 52271079b4f1 · 2023-11-10T18:41:35.000+01:00
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -59,7 +59,13 @@ jobs:
       - name: Install package
         run: |
           python -m pip install --upgrade pip setuptools wheel
-          sudo apt-get install -y pandoc
+          # NOTE(stes) Pandoc version must be at least (2.14.2) but less than (4.0.0).
+          # as of 29/10/23. Ubuntu 22.04 which is used for ubuntu-latest only has an 
+          # old pandoc version (2.9.). We will hence install the latest version manually.
+          # previou: sudo apt-get install -y pandoc
+          wget https://github.com/jgm/pandoc/releases/download/3.1.9/pandoc-3.1.9-1-amd64.deb 
+          sudo dpkg -i pandoc-3.1.9-1-amd64.deb 
+          rm pandoc-3.1.9-1-amd64.deb 
           pip install torch --extra-index-url https://download.pytorch.org/whl/cpu
           pip install '.[docs]'
 
diff --git a/Dockerfile b/Dockerfile
@@ -42,7 +42,7 @@ RUN make dist
 FROM cebra-base
 
 # install the cebra wheel
-ENV WHEEL=cebra-0.3.0-py2.py3-none-any.whl
+ENV WHEEL=cebra-0.3.1rc1-py2.py3-none-any.whl
 WORKDIR /build
 COPY --from=wheel /build/dist/${WHEEL} .
 RUN pip install --no-cache-dir ${WHEEL}'[dev,integrations,datasets]'
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-CEBRA_VERSION=$(shell python3 -c "import cebra; print(cebra.__version__)")
+CEBRA_VERSION := 0.3.1rc1
 
 dist:
 	python3 -m pip install virtualenv
@@ -10,7 +10,7 @@ build: dist
 archlinux:
 	mkdir -p dist/arch
 	cp PKGBUILD dist/arch
-	cp dist/cebra-0.3.0.tar.gz dist/arch
+	cp dist/cebra-${CEBRA_VERSION}.tar.gz dist/arch
 	(cd dist/arch; makepkg --skipchecksums -f)
 
 # NOTE(stes): Ensure that no old tempfiles are present. Ideally, move this into
diff --git a/PKGBUILD b/PKGBUILD
@@ -1,7 +1,7 @@
 # Maintainer: Steffen Schneider <stes@hey.com>
 pkgname=python-cebra
 _pkgname=cebra
-pkgver=0.3.0
+pkgver=0.3.1rc1
 pkgrel=1
 pkgdesc="Consistent Embeddings of high-dimensional Recordings using Auxiliary variables"
 url="https://cebra.ai"
diff --git a/README.md b/README.md
@@ -45,5 +45,6 @@ It can jointly use behavioral and neural data in a hypothesis- or discovery-driv
   [Learnable latent embeddings for joint behavioral and neural analysis.](https://arxiv.org/abs/2204.00673)
   Steffen Schneider*, Jin Hwa Lee* and Mackenzie Weygandt Mathis
 
- # License
+# License
+
 -  CEBRA is released for academic use only (please read the license file). If this license is not appropriate for your application, please contact Prof. Mackenzie W. Mathis (mackenzie@post.harvard.edu) for a commercial use license.
diff --git a/cebra/__init__.py b/cebra/__init__.py
@@ -36,6 +36,15 @@
     # silently fail for now
     pass
 
+is_plotly_available = False
+try:
+    from cebra.integrations.plotly import *
+
+    is_plotly_available = True
+except ImportError as e:
+    # silently fail for now
+    pass
+
 from cebra.data.load import load as load_data
 
 is_load_deeplabcut_available = False
@@ -47,7 +56,7 @@
 
 import cebra.integrations.sklearn as sklearn
 
-__version__ = "0.3.0"
+__version__ = "0.3.1rc1"
 __all__ = ["CEBRA"]
 __allow_lazy_imports = False
 __lazy_imports = {}
diff --git a/cebra/data/load.py b/cebra/data/load.py
@@ -9,7 +9,22 @@
 # Please see LICENSE.md for the full license document:
 # https://github.com/AdaptiveMotorControlLab/CEBRA/LICENSE.md
 #
-"""A simple API for loading various data formats used with CEBRA."""
+"""A simple API for loading various data formats used with CEBRA.
+
+Availability of different data formats depends on the installed
+dependencies. If a dependency is not installed, an attempt to load
+a file of that format will throw an error with further installation
+instructions.
+
+Currently available formats:
+
+- HDF5 via ``h5py``
+- Pickle files via ``pickle``
+- Joblib files via ``joblib``
+- Various dataframe formats via ``pandas``.
+- Matlab files via ``scipy.io.loadmat``
+- DeepLabCut (single animal) files via ``deeplabcut``
+"""
 
 import abc
 import pathlib
diff --git a/cebra/integrations/__init__.py b/cebra/integrations/__init__.py
@@ -9,17 +9,15 @@
 # Please see LICENSE.md for the full license document:
 # https://github.com/AdaptiveMotorControlLab/CEBRA/LICENSE.md
 #
-"""Integration of CEBRA into common machine learning libraries.
+"""Integration of CEBRA with common machine learning and visualization libraries.
 
 This package contains a growing collection of interfaces to other Python packages.
 There is no clear limit (yet) of what can go into it. The current examples include
 interfaces (implemented or planned) to `scikit-learn <https://scikit-learn.org/stable/>`_,
 `streamlit <https://streamlit.io/>`_, `deeplabcut <http://www.mackenziemathislab.org/deeplabcut>`_,
-`matplotlib <https://matplotlib.org/>`_ and `threejs <https://threejs.org/>`_.
+`matplotlib <https://matplotlib.org/>`_ and `threejs <https://threejs.org/>`_ and `plotly <https://plotly.com/>`_.
 
 Integrations can be used for data visualization, for providing easier interfaces to using CEBRA
 for a particular userbase, or any other helpful function that requires a dependency to a larger
 third-party package.
-
-See our CEBRA `live demo <https://stes.io/c>`_.
 """
diff --git a/cebra/integrations/plotly.py b/cebra/integrations/plotly.py
@@ -135,7 +135,7 @@ def plot_embedding_interactive(
     This is supposing that the dimensions provided to ``idx_order`` are in the range of the number of
     dimensions of the embedding (i.e., between 0 and :py:attr:`cebra.CEBRA.output_dimension` -1).
 
-    The function makes use of :py:func:`plotly.graph_objs._scatter.Scatter` and parameters from that function can be provided
+    The function makes use of :py:class:`plotly.graph_objects.Scatter` and parameters from that function can be provided
     as part of ``kwargs``.
 
 
@@ -156,7 +156,7 @@ def plot_embedding_interactive(
         title: The title on top of the embedding.
         figsize: Figure width and height in inches.
         dpi: Figure resolution.
-        kwargs: Optional arguments to customize the plots. See :py:func:`plotly.graph_objs._scatter.Scatter` documentation for more
+        kwargs: Optional arguments to customize the plots. See :py:class:`plotly.graph_objects.Scatter` documentation for more
             details on which arguments to use.
 
     Returns:
@@ -174,7 +174,7 @@ def plot_embedding_interactive(
         CEBRA(max_iterations=10)
         >>> embedding = cebra_model.transform(X)
         >>> cebra_time = np.arange(X.shape[0])
-        >>> fig = cebra.integrations.plotly.plot_embedding_interactive(embedding, embedding_labels=cebra_time)
+        >>> fig = cebra.plot_embedding_interactive(embedding, embedding_labels=cebra_time)
 
     """
     return _EmbeddingInteractivePlot(
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -37,8 +37,16 @@ these components in other contexts and research code bases.
    api/pytorch/datasets
    api/pytorch/distributions
    api/pytorch/models
-   api/pytorch/integrations
    api/pytorch/helpers
 
+.. toctree::
+   :hidden:
+   :caption: Integrations
+
+   api/integrations/data
+   api/integrations/matplotlib
+   api/integrations/plotly
+   api/integrations/deeplabcut
+
 
 .. _Scikit-learn estimators: https://scikit-learn.org/stable/developers/develop.html
diff --git a/docs/source/api/integrations/data.rst b/docs/source/api/integrations/data.rst
@@ -0,0 +1,6 @@
+Data Loading
+------------
+
+.. automodule:: cebra.data.load
+   :show-inheritance:
+   :members:
diff --git a/docs/source/api/integrations/deeplabcut.rst b/docs/source/api/integrations/deeplabcut.rst
@@ -0,0 +1,8 @@
+DeepLabCut
+----------
+
+.. automodule:: cebra.integrations.deeplabcut
+   :show-inheritance:
+   :members:
+
+
diff --git a/docs/source/api/integrations/matplotlib.rst b/docs/source/api/integrations/matplotlib.rst
@@ -0,0 +1,7 @@
+Plotting with ``matplotlib``
+----------------------------
+
+.. automodule:: cebra.integrations.matplotlib
+   :show-inheritance:
+   :members:
+
diff --git a/docs/source/api/integrations/plotly.rst b/docs/source/api/integrations/plotly.rst
@@ -0,0 +1,7 @@
+Plotting with ``plotly``
+----------------------------
+
+.. automodule:: cebra.integrations.plotly
+   :show-inheritance:
+   :members:
+
diff --git a/docs/source/api/pytorch/helpers.rst b/docs/source/api/pytorch/helpers.rst
@@ -21,14 +21,6 @@ Registry
    :show-inheritance:
 
 
-Plots
------
-
-.. automodule:: cebra.integrations.matplotlib
-   :show-inheritance:
-   :members:
-
-
 Grid-Search
 -----------
 
diff --git a/docs/source/api/pytorch/integrations.rst b/docs/source/api/pytorch/integrations.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -101,6 +101,7 @@ def get_years(start_year=2021):
     "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None),
     "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
     "joblib": ("https://joblib.readthedocs.io/en/latest/", None),
+    "plotly": ("https://plotly.com/python-api-reference/", None)
 }
 
 # Config is documented here: https://sphinx-copybutton.readthedocs.io/en/latest/
@@ -116,6 +117,7 @@ def get_years(start_year=2021):
     "h5py",
     "pandas",
     "matplotlib",
+    "plotly"
 ]
 # autodoc_typehints = "none"
 
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -1252,10 +1252,11 @@ Putting all previous snippet examples together, we obtain the following pipeline
 Quick Start: Torch API example
 ------------------------------
 
-🚀 You have special custom data analysis needs? We invite you to use the ``torch``-API interface.
+🚀 You have special custom data analysis needs or want more features? We invite you to use the ``torch``-API interface.
 
-Refer to the ``examples/`` folder for a set of demo scripts.
-Single- and multi-session training can be launched using the following ``bash`` command.
+Refer to the ``Demos`` tab for a demo notebook using the ``torch``-API: https://cebra.ai/docs/demo_notebooks/Demo_Allen.html.
+
+Single- and multi-session training could be launched using the following ``bash`` command.
 
 .. code:: bash
 
diff --git a/reinstall.sh b/reinstall.sh
@@ -15,7 +15,7 @@ pip uninstall -y cebra
 # Get version info after uninstalling --- this will automatically get the
 # most recent version based on the source code in the current directory.
 # $(tools/get_cebra_version.sh)
-VERSION=0.3.0
+VERSION=0.3.1rc1
 echo "Upgrading to CEBRA v${VERSION}"
 
 # Upgrade the build system (PEP517/518 compatible)
diff --git a/tools/bump_version.sh b/tools/bump_version.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# Bump the CEBRA version to the specified value.
+# Edits all relevant files at once.
+# 
+# Usage:
+# tools/bump_version.sh 0.3.1rc1
+
+version=$1
+if [ -z ${version} ]; then
+    >&1 echo "Specify a version number."
+    >&1 echo "Usage:"
+    >&1 echo "tools/bump_version.sh <semantic version>"
+fi
+
+# python cebra version
+sed -i "s/__version__ = .*/__version__ = \"${version}\"/" \
+    cebra/__init__.py
+
+# reinstall script in root
+sed -i "s/VERSION=.*/VERSION=${version}/" \
+    reinstall.sh
+
+# Makefile
+sed -i "s/CEBRA_VERSION := .*/CEBRA_VERSION := ${version}/" \
+    Makefile
+
+# Arch linux PKGBUILD 
+sed -i "s/pkgver=.*/pkgver=${version}/" \
+    PKGBUILD 
+
+# Dockerfile
+sed -i "s/ENV WHEEL=cebra-.*\.whl/ENV WHEEL=cebra-${version}-py2.py3-none-any.whl/" \
+    Dockerfile 
