Deprecations

README.md

@@ -104,11 +104,6 @@ with a random string, `matplotlib` will tell you the available choices.
     a second pair with the roles of the two models reversed. This method
     allows for efficient comparison of two metrics, highlighting the
     aspects in which their sensitivities differ.
--   [Geodesics](examples/05_Geodesics.ipynb): given a model and two
-    images, synthesize a sequence of images that lie on the shortest
-    ("geodesic") path in the model's representation space. This
-    method investigates how a model represents motion and what changes
-    to an image it consider reasonable.
 
 ### Models, Metrics, and Model Components
 

docs/citation.rst

@@ -31,7 +31,6 @@ component you use:
 -  :class:`plenoptic.synthesize.metamer.Metamer`: or :class:`plenoptic.synthesize.metamer.MetamerCTF`: [Portilla2000]_.
 - :class:`plenoptic.synthesize.mad_competition.MADCompetition`: [Wang2008]_.
 - :class:`plenoptic.synthesize.eigendistortion.Eigendistortion`: [Berardino2017]_.
-- :class:`plenoptic.synthesize.geodesic.Geodesic`: [Henaff2016]_.
 - :class:`plenoptic.simulate.canonical_computations.steerable_pyramid_freq.SteerablePyramidFreq`: [Simoncelli1995]_ ([Simoncelli1992]_ contains a longer discussion about the motivation and the logic, while [Simoncelli1995]_ describes the implementation that is used here).
 - :class:`plenoptic.simulate.models.portilla_simoncelli.PortillaSimoncelli`: [Portilla2000]_.
 - :class:`plenoptic.simulate.models.frontend` (any model): [Berardino2017]_.

docs/conceptual_intro.rst

@@ -214,8 +214,6 @@ a model's representational space:
 - `Maximal differentiation (MAD) competition
   <tutorials/intro/07_MAD_Competition.nblink>`_ enables efficient comparison of two
   metrics, highlighting the aspects in which their sensitivities differ.
-- `Geodesics <tutorials/intro/05_Geodesics.nblink>`_ investigates how a model represents
-  motion and what changes to an image it considers reasonable.
 
 The goal of this package is to facilitate model exploration and understanding.
 We hope that providing these tools helps tighten the model-experiment loop: when

docs/index.rst

@@ -117,13 +117,6 @@ Synthesis methods
   their sensitivities most differ.
 
   - Example papers: [Wang2008]_
-- `Geodesics <tutorials/intro/05_Geodesics.nblink>`_: given a model and two images,
-  synthesize a sequence of images that lie on the shortest ("geodesic") path in
-  the model's representation space. This method allows examination of the larger-scale geometric
-  properties of model representation (as opposed to the local properties captured by 
-  the eigendistortions).
-
-  - Example papers: [Henaff2016]_, [Henaff2020]_
 
 Models, Metrics, and Model Components
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -256,13 +249,6 @@ cite us! See the :ref:`citation` for more details.
    perceptual discriminability. Journal of Vision, 8(12), 1–13.
    https://ece.uwaterloo.ca/~z70wang/research/mad/
    https://www.cns.nyu.edu/pub/lcv/wang08-preprint.pdf
-.. [Henaff2016] H\'enaff, O.~J., & Simoncelli, E.~P. (2016). Geodesics of
-   learned representations. ICLR.
-   https://www.cns.nyu.edu/pub/lcv/henaff16b-reprint.pdf
-.. [Henaff2020] O Hénaff, Y Bai, J Charlton, I Nauhaus, E P Simoncelli and R L T
-   Goris. Primary visual cortex straightens natural video trajectories Nature
-   Communications, vol.12(5982), Oct 2021.
-   https://www.cns.nyu.edu/pub/lcv/henaff20-reprint.pdf
 .. [Simoncelli1992] Simoncelli, E. P., Freeman, W. T., Adelson, E. H., &
    Heeger, D. J. (1992). Shiftable Multi-Scale Transforms. IEEE Trans.
    Information Theory, 38(2), 587–607. https://dx.doi.org/10.1109/18.119725

docs/synthesis.rst

@@ -78,10 +78,10 @@ Furthermore:
   start with ``_``).
 * consider using the ``@property`` decorator to make important attributes
   write-only or differentiate between the public and private views. For example,
-  the optimized attribute of the :class:`plenoptic.synthesize.geodesic.Geodesic`
-  class is named ``_geodesic``, but the ``geodesic`` attribute returns this
-  tensor concatenated with two (unchanging) endpoints, as this is what the user
-  will most often want to interact with.
+  :class:`plenoptic.synthesize.mad_competition.MADCompetition` tracks the loss
+  of the reference metric in a list, ``_reference_metric_loss``, but the
+  ``reference_metric_loss`` attribute converts this list to a tensor before
+  returning it, as that's how the user will most often want to interact with it.
 
 The above are the only requirements that all synthesis methods must meet.
 
@@ -190,8 +190,7 @@ follow these guidelines:
   helper methods that aren't scientifically interesting (e.g.,
   ``_initialize_optimizer()``, ``_store()``).
 * Next, any other content-related methods, such as helper methods that perform
-  useful computations that are not called by ``__init__()`` or ``synthesize()``
-  (e.g., :class:`plenoptic.synthesize.geodesic.Geodesic.calculate_jerkiness`).
+  useful computations that are not called by ``__init__()`` or ``synthesize()``.
 * Next, the helper functions we ignored from earlier, such as
   ``_initialize_optimizer()`` and ``_store()``.
 * Next, ``save()``, ``load()``, ``to()``.

docs/tips.rst

@@ -45,9 +45,6 @@ methods.
   visualize these values. You will likely need to spend time trying out
   different values for the ``metric_tradeoff_lambda`` argument set during
   initialization to achieve this.
-- For geodesics, check that your geodesic's path energy is small enough and that
-  the deviation from a straight line in representational space is minimal (use
-  :func:`plenoptic.synthesize.geodesic.plot_deviation_from_line`)
 
 For all of the above, if synthesis has not found a good solution, you may need
 to run synthesis longer, use a learning-rate scheduler, change the learning

pyproject.toml

@@ -26,6 +26,7 @@ dependencies = [
     "scikit-image>=0.15.0",
     "einops>=0.3.0",
     "importlib-resources>=6.0",
+    "Deprecated",
 ]
 
 [build-system]

src/plenoptic/simulate/canonical_computations/filters.py

@@ -2,7 +2,6 @@
 
 import torch
 from torch import Tensor
-from warnings import warn
 
 __all__ = ["gaussian1d", "circular_gaussian2d"]
 

src/plenoptic/simulate/models/portilla_simoncelli.py

@@ -994,7 +994,6 @@ def plot_representation(
             fig = plt.figure(figsize=figsize)
             gs = mpl.gridspec.GridSpec(n_rows, n_cols, fig)
         else:
-            # warnings.warn("ax is not None, so we're ignoring figsize...")
             # want to make sure the axis we're taking over is basically invisible.
             ax = clean_up_axes(
                 ax, False, ["top", "right", "bottom", "left"], ["x", "y"]

src/plenoptic/synthesize/eigendistortion.py

@@ -537,11 +537,11 @@ def load(self, file_path: str,
 
         Examples
         --------
-        >>> geo = po.synth.Geodesic(img_a, img_b, model)
-        >>> geo.synthesize(max_iter=10, store_progress=True)
-        >>> geo.save('geo.pt')
-        >>> geo_copy = po.synth.Geodesic(img_a, img_b, model)
-        >>> geo_copy.load('geo.pt')
+        >>> eig = po.synth.Eigendistortion(img, model)
+        >>> eig.synthesize(max_iter=10)
+        >>> eig.save('eig.pt')
+        >>> eig_copy = po.synth.Eigendistortion(img, model)
+        >>> eig_copy.load('eig.pt')
 
         Note that you must create a new instance of the Synthesis object and
         *then* load.

src/plenoptic/synthesize/geodesic.py

@@ -8,6 +8,7 @@
 from tqdm.auto import tqdm
 from typing import Union, Tuple, Optional
 from typing_extensions import Literal
+from deprecated.sphinx import deprecated
 
 from .synthesis import OptimizedSynthesis
 from ..tools.data import to_numpy
@@ -17,7 +18,7 @@
 from ..tools.straightness import (deviation_from_line, make_straight_line,
                                   sample_brownian_bridge)
 
-
+@deprecated("Geodesic is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 class Geodesic(OptimizedSynthesis):
     r"""Synthesize an approximate geodesic between two images according to a model.
 
@@ -535,6 +536,7 @@ def dev_from_line(self):
         return torch.stack(self._dev_from_line)
 
 
+@deprecated("Geodesic is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 def plot_loss(geodesic: Geodesic,
               ax: Union[mpl.axes.Axes, None] = None,
               **kwargs) -> mpl.axes.Axes:
@@ -555,6 +557,9 @@ def plot_loss(geodesic: Geodesic,
     ax :
         Axes containing the plot.
 
+    Notes
+    -----
+
     """
     if ax is None:
         ax = plt.gca()
@@ -563,6 +568,8 @@ def plot_loss(geodesic: Geodesic,
            ylabel='Loss')
     return ax
 
+
+@deprecated("Geodesic is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 def plot_deviation_from_line(geodesic: Geodesic,
                              natural_video: Union[Tensor, None] = None,
                              ax: Union[mpl.axes.Axes, None] = None

src/plenoptic/synthesize/simple_metamer.py

@@ -6,8 +6,10 @@
 from ..tools.validate import validate_input, validate_model
 from ..tools import optim
 from typing import Union
+from deprecated.sphinx import deprecated
 
 
+@deprecated("Use :py:class:`plenoptic.synthesize.metamer.Metamer` instead", version="1.1.0")
 class SimpleMetamer(Synthesis):
     r"""Simple version of metamer synthesis.
 
@@ -26,6 +28,9 @@ class SimpleMetamer(Synthesis):
     model
         The visual model whose representation we wish to match.
 
+    Notes
+    -----
+
     """
 
     def __init__(self, image: torch.Tensor, model: torch.nn.Module):

src/plenoptic/tools/data.py

@@ -11,8 +11,7 @@
 from torch import Tensor
 
 from .signal import rescale
-
-DATA_PATH = op.join(op.dirname(op.realpath(__file__)), "..", "..", "data/256")
+from deprecated.sphinx import deprecated
 
 NUMPY_TO_TORCH_TYPES = {
     bool: torch.bool,  # np.bool deprecated in fav of built-in
@@ -163,6 +162,7 @@ def load_images(paths: Union[str, List[str]], as_gray: bool = True) -> Tensor:
     return images
 
 
+@deprecated("Load images using :py:func:`load_images` instead", "1.1.0")
 def convert_float_to_int(im: np.ndarray, dtype=np.uint8) -> np.ndarray:
     r"""Convert image from float to 8 or 16 bit image
 
@@ -186,6 +186,10 @@ def convert_float_to_int(im: np.ndarray, dtype=np.uint8) -> np.ndarray:
     -------
     im
         The converted image, now with dtype=dtype
+
+    Notes
+    -----
+
     """
     if im.max() > 1:
         raise Exception(
@@ -194,6 +198,7 @@ def convert_float_to_int(im: np.ndarray, dtype=np.uint8) -> np.ndarray:
     return (im * np.iinfo(dtype).max).astype(dtype)
 
 
+@deprecated("Use :py:func:`pyrtools.synthetic_images` instead", "1.1.0")
 def make_synthetic_stimuli(size: int = 256, requires_grad: bool = True) -> Tensor:
     r"""Make a set of basic stimuli, useful for developping and debugging models
 
@@ -210,6 +215,10 @@ def make_synthetic_stimuli(size: int = 256, requires_grad: bool = True) -> Tenso
         Tensor of shape [11, 1, size, size]. The set of basic stiuli:
         [impulse, step_edge, ramp, bar, curv_edge, sine_grating, square_grating,
         polar_angle, angular_sine, zone_plate, fractal]
+
+    Notes
+    -----
+
     """
 
     impulse = np.zeros((size, size))

src/plenoptic/tools/display.py

@@ -6,10 +6,6 @@
 import pyrtools as pt
 import matplotlib.pyplot as plt
 from .data import to_numpy
-try:
-    from IPython.display import HTML
-except ImportError:
-    warnings.warn("Unable to import IPython.display.HTML")
 
 
 def imshow(image, vrange='indep1', zoom=None, title='', col_wrap=None, ax=None,

src/plenoptic/tools/signal.py

@@ -6,7 +6,10 @@
 import torch.fft as fft
 from pyrtools.pyramids.steer import steer_to_harmonics_mtx
 
+from deprecated.sphinx import deprecated
 
+
+@deprecated("Use :py:func:`einops.reduce` instead: https://einops.rocks/1-einops-basics/#meet-einopsreduce", version="1.1.0")
 def minimum(
     x: Tensor, dim: Optional[List[int]] = None, keepdim: bool = False
 ) -> Tensor:
@@ -25,6 +28,10 @@ def minimum(
     -------
     min_x 
         Minimum value of x.
+
+    Notes
+    -----
+
     """
     if dim is None:
         dim = tuple(range(x.ndim))
@@ -35,6 +42,7 @@ def minimum(
     return min_x
 
 
+@deprecated("Use :py:func:`einops.reduce` instead: https://einops.rocks/1-einops-basics/#meet-einopsreduce", version="1.1.0")
 def maximum(
     x: Tensor, dim: Optional[List[int]] = None, keepdim: bool = False
 ) -> Tensor:
@@ -53,6 +61,10 @@ def maximum(
     -------
     max_x
         Maximum value of x.
+
+    Notes
+    -----
+
     """
     if dim is None:
         dim = tuple(range(x.ndim))

src/plenoptic/tools/straightness.py

@@ -2,8 +2,10 @@
 from torch import Tensor
 from typing import Tuple
 from .validate import validate_input
+from deprecated.sphinx import deprecated
 
 
+@deprecated("Deprecated along with Geodesic, which is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 def make_straight_line(start: Tensor, stop: Tensor, n_steps: int) -> Tensor:
     """make a straight line between `start` and `stop` with `n_steps` transitions.
 
@@ -22,6 +24,9 @@ def make_straight_line(start: Tensor, stop: Tensor, n_steps: int) -> Tensor:
     straight
         Tensor of shape (n_steps+1, channel, height, width)
 
+    Notes
+    -----
+
     """
     validate_input(start, no_batch=True)
     validate_input(stop, no_batch=True)
@@ -41,6 +46,7 @@ def make_straight_line(start: Tensor, stop: Tensor, n_steps: int) -> Tensor:
     return straight.reshape((n_steps+1, *shape))
 
 
+@deprecated("Deprecated along with Geodesic, which is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 def sample_brownian_bridge(start: Tensor, stop: Tensor,
                            n_steps: int, max_norm: float = 1) -> Tensor:
     """Sample a brownian bridge between `start` and `stop` made up of `n_steps`
@@ -66,6 +72,9 @@ def sample_brownian_bridge(start: Tensor, stop: Tensor,
         sequence of shape (n_steps+1, channel, height, width) a brownian bridge
         across the two pylons
 
+    Notes
+    -----
+
     """
     validate_input(start, no_batch=True)
     validate_input(stop, no_batch=True)
@@ -94,6 +103,7 @@ def sample_brownian_bridge(start: Tensor, stop: Tensor,
     return bridge.reshape((n_steps+1, *shape))
 
 
+@deprecated("Deprecated along with Geodesic, which is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 def deviation_from_line(sequence: Tensor,
                         normalize: bool = True) -> Tuple[Tensor, Tensor]:
     """Compute the deviation of `sequence` to the straight line between its endpoints.
@@ -119,6 +129,9 @@ def deviation_from_line(sequence: Tensor,
     dist_from_line
         sequence of T euclidian distances to the line
 
+    Notes
+    -----
+
     """
     validate_input(sequence)
     y = sequence.reshape(sequence.shape[0], -1)
@@ -142,6 +155,7 @@ def deviation_from_line(sequence: Tensor,
     return dist_along_line, dist_from_line
 
 
+@deprecated("Deprecated along with Geodesic, which is not robust enough yet, see https://github.com/plenoptic-org/geodesics for ongoing development", "1.1.0")
 def translation_sequence(image: Tensor, n_steps: int = 10) -> Tensor:
     """make a horizontal translation sequence on `image`
 
@@ -158,6 +172,9 @@ def translation_sequence(image: Tensor, n_steps: int = 10) -> Tensor:
     sequence
         translation sequence of shape (n_steps+1, channel, height, width)
 
+    Notes
+    -----
+
     """
     validate_input(image, no_batch=True)
     if n_steps <= 0:

tests/conftest.py

@@ -1,13 +1,8 @@
 import pytest
 import plenoptic as po
-import os.path as op
-import pathlib
 import torch
 
-import plenoptic.simulate.canonical_computations.filters as filters
-
 DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
-DTYPE = torch.float32
 IMG_DIR = po.data.fetch_data('test_images.tar.gz')
 
 torch.set_num_threads(1)  # torch uses all avail threads which will slow tests