Plenoptic 2.0 Migration Guide

Plenoptic version 2.0 introduces a substantial change to the package API: every class and function has been moved, in an attempt to flatten the hierarchy. The names, signature, and usage of individual classes and functions, with few exceptions, have not changed (see Plotting function changes for the exceptions). Therefore, it should be possible to update your plenoptic 1.0 code to work with 2.0 with only some replacements.

A Migration script is provided below which should hopefully simplify this migration. We also recommend reading through the Plotting function changes to see if any of the changes to plotting functions are applicable for your usage. Finally, a Table of API Changes can be found on this page which summarizes all changes.

If you have any problems with this process, please open a discussion, and we’ll help with this process!

Plotting function changes

All plotting functions in plenoptic are now present within the plot module. This includes those that operates on tensors (e.g., plenoptic.plot.imshow, previously plenoptic.imshow) and synthesis objects (e.g., plenoptic.plot.synthesis_loss, previously plenoptic.synthesize.metamer.plot_loss). Therefore, to avoid name collisions and redundancies (e.g., plenoptic.plot.plot_loss) and to clarify which functions operate on which synthesis objects, some of the function names have been changed. See Table of API Changes and search for plot. for a list.

Additionally, many of the synthesis object plotting functions have been consolidated. For example, plenoptic.synthesize.metamer.plot_loss and plenoptic.synthesize.mad_competition.plot_loss, which would accept a Metamer or MADCompetition object and plot the synthesis loss, have been consolidated into a single function: plenoptic.plot.synthesis_loss, which accepts both object types.

The argument names and acceptable argument values of these consolidated functions have changed slightly to reflect this consolidation. Consult their docstrings for details. (These updates cannot be handled automatically by the following Migration script and so need to be changed manually.)

Migration script

The developers wrote a little tool to update the plenoptic codebase, documentation, and tests during the migration to plenoptic 2.0. You are welcome to use it on your own code, though we make no guarantees.

The recommended way to use the tool is via uvx or pipx, both of which will create a temporary isolated virtual environment for the tool:

pipx

$ pipx run plenoptic-migrate --help

uvx

$ uvx plenoptic-migrate --help

View the tool’s help or README for details on how to use.

Table of API Changes

The table below shows functions as they were called in plenoptic’s 1.x releases in the first column, and as they are called in plenoptic>=2.0.0 in the second. Note that for many functions and classes, there were multiple ways of calling them in plenoptic 1.x (e.g., plenoptic.synthesize.Metamer and plenoptic.synthesize.metamer.Metamer). This redundancy has been removed in plenoptic>=2.0.0.

plenoptic 1.x	plenoptic 2.0
plenoptic.synthesize.metamer.Metamer	plenoptic.Metamer
plenoptic.synthesize.Metamer	plenoptic.Metamer
plenoptic.synthesize.metamer.MetamerCTF	plenoptic.MetamerCTF
plenoptic.synthesize.MetamerCTF	plenoptic.MetamerCTF
plenoptic.synthesize.eigendistortion.Eigendistortion	plenoptic.Eigendistortion
plenoptic.synthesize.Eigendistortion	plenoptic.Eigendistortion
plenoptic.synthesize.mad_competition.MADCompetition	plenoptic.MADCompetition
plenoptic.synthesize.MADCompetition	plenoptic.MADCompetition
plenoptic.simulate.models.portilla_simoncelli.PortillaSimoncelli	plenoptic.models.PortillaSimoncelli
plenoptic.simulate.PortillaSimoncelli	plenoptic.models.PortillaSimoncelli
plenoptic.simulate.models.frontend.LinearNonlinear	plenoptic.models.LinearNonlinear
plenoptic.simulate.LinearNonlinear	plenoptic.models.LinearNonlinear
plenoptic.simulate.models.frontend.LuminanceGainControl	plenoptic.models.LuminanceGainControl
plenoptic.simulate.LuminanceGainControl	plenoptic.models.LuminanceGainControl
plenoptic.simulate.models.frontend.LuminanceContrastGainControl	plenoptic.models.LuminanceContrastGainControl
plenoptic.simulate.LuminanceContrastGainControl	plenoptic.models.LuminanceContrastGainControl
plenoptic.simulate.models.frontend.OnOff	plenoptic.models.OnOff
plenoptic.simulate.OnOff	plenoptic.models.OnOff
plenoptic.simulate.models.naive.Identity	plenoptic.models.Identity
plenoptic.simulate.Identity	plenoptic.models.Identity
plenoptic.simulate.models.naive.Linear	plenoptic.models.Linear
plenoptic.simulate.Linear	plenoptic.models.Linear
plenoptic.simulate.models.naive.Gaussian	plenoptic.models.Gaussian
plenoptic.simulate.Gaussian	plenoptic.models.Gaussian
plenoptic.simulate.models.naive.CenterSurround	plenoptic.models.CenterSurround
plenoptic.simulate.CenterSurround	plenoptic.models.CenterSurround
plenoptic.metric.naive.mse	plenoptic.metric.mse
plenoptic.metric.model_metric.model_metric_factory	plenoptic.metric.model_metric_factory
plenoptic.metric.perceptual_distance.ssim	plenoptic.metric.ssim
plenoptic.metric.perceptual_distance.ms_ssim	plenoptic.metric.ms_ssim
plenoptic.metric.perceptual_distance.nlpd	plenoptic.metric.nlpd
plenoptic.metric.perceptual_distance.ssim_map	plenoptic.process.ssim_map
plenoptic.metric.ssim_map	plenoptic.process.ssim_map
plenoptic.metric.perceptual_distance.normalized_laplacian_pyramid	plenoptic.process.normalized_laplacian_pyramid
plenoptic.metric.normalized_laplacian_pyramid	plenoptic.process.normalized_laplacian_pyramid
plenoptic.simulate.canonical_computations.laplacian_pyramid.LaplacianPyramid	plenoptic.process.LaplacianPyramid
plenoptic.simulate.LaplacianPyramid	plenoptic.process.LaplacianPyramid
plenoptic.simulate.canonical_computations.steerable_pyramid_freq.SteerablePyramidFreq	plenoptic.process.SteerablePyramidFreq
plenoptic.simulate.SteerablePyramidFreq	plenoptic.process.SteerablePyramidFreq
plenoptic.simulate.canonical_computations.filters.circular_gaussian2d	plenoptic.process.circular_gaussian2d
plenoptic.simulate.circular_gaussian2d	plenoptic.process.circular_gaussian2d
plenoptic.tools.signal.rectangular_to_polar	plenoptic.process.rectangular_to_polar
plenoptic.tools.rectangular_to_polar	plenoptic.process.rectangular_to_polar
plenoptic.tools.signal.polar_to_rectangular	plenoptic.process.polar_to_rectangular
plenoptic.tools.polar_to_rectangular	plenoptic.process.polar_to_rectangular
plenoptic.simulate.canonical_computations.non_linearities.local_gain_control	plenoptic.process.local_gain_control
plenoptic.simulate.non_linearities.local_gain_control	plenoptic.process.local_gain_control
plenoptic.simulate.canonical_computations.non_linearities.local_gain_release	plenoptic.process.local_gain_release
plenoptic.simulate.non_linearities.local_gain_release	plenoptic.process.local_gain_release
plenoptic.simulate.canonical_computations.non_linearities.rectangular_to_polar_dict	plenoptic.process.rectangular_to_polar_dict
plenoptic.simulate.non_linearities.rectangular_to_polar_dict	plenoptic.process.rectangular_to_polar_dict
plenoptic.simulate.canonical_computations.non_linearities.polar_to_rectangular_dict	plenoptic.process.polar_to_rectangular_dict
plenoptic.simulate.non_linearities.polar_to_rectangular_dict	plenoptic.process.polar_to_rectangular_dict
plenoptic.simulate.canonical_computations.non_linearities.local_gain_control_dict	plenoptic.process.local_gain_control_dict
plenoptic.simulate.non_linearities.local_gain_control_dict	plenoptic.process.local_gain_control_dict
plenoptic.simulate.canonical_computations.non_linearities.local_gain_release_dict	plenoptic.process.local_gain_release_dict
plenoptic.simulate.non_linearities.local_gain_release_dict	plenoptic.process.local_gain_release_dict
plenoptic.tools.conv.correlate_downsample	plenoptic.process.correlate_downsample
plenoptic.tools.correlate_downsample	plenoptic.process.correlate_downsample
plenoptic.tools.conv.blur_downsample	plenoptic.process.blur_downsample
plenoptic.tools.blur_downsample	plenoptic.process.blur_downsample
plenoptic.tools.conv.upsample_convolve	plenoptic.process.upsample_convolve
plenoptic.tools.upsample_convolve	plenoptic.process.upsample_convolve
plenoptic.tools.conv.upsample_blur	plenoptic.process.upsample_blur
plenoptic.tools.upsample_blur	plenoptic.process.upsample_blur
plenoptic.tools.conv.same_padding	plenoptic.process.same_padding
plenoptic.tools.same_padding	plenoptic.process.same_padding
plenoptic.tools.signal.shrink	plenoptic.process.shrink
plenoptic.tools.shrink	plenoptic.process.shrink
plenoptic.tools.signal.expand	plenoptic.process.expand
plenoptic.tools.expand	plenoptic.process.expand
plenoptic.tools.signal.rescale	plenoptic.process.rescale
plenoptic.tools.rescale	plenoptic.process.rescale
plenoptic.tools.signal.add_noise	plenoptic.process.add_noise
plenoptic.tools.add_noise	plenoptic.process.add_noise
plenoptic.tools.signal.center_crop	plenoptic.process.center_crop
plenoptic.tools.center_crop	plenoptic.process.center_crop
plenoptic.tools.signal.modulate_phase	plenoptic.process.modulate_phase
plenoptic.tools.modulate_phase	plenoptic.process.modulate_phase
plenoptic.tools.signal.autocorrelation	plenoptic.process.autocorrelation
plenoptic.tools.autocorrelation	plenoptic.process.autocorrelation
plenoptic.tools.stats.variance	plenoptic.process.variance
plenoptic.tools.variance	plenoptic.process.variance
plenoptic.tools.stats.skew	plenoptic.process.skew
plenoptic.tools.skew	plenoptic.process.skew
plenoptic.tools.stats.kurtosis	plenoptic.process.kurtosis
plenoptic.tools.kurtosis	plenoptic.process.kurtosis
plenoptic.tools.data.to_numpy	plenoptic.to_numpy
plenoptic.tools.to_numpy	plenoptic.to_numpy
plenoptic.tools.data.convert_float_to_int	plenoptic.convert_float_to_int
plenoptic.tools.convert_float_to_int	plenoptic.convert_float_to_int
plenoptic.data.fetch.fetch_data	plenoptic.data.fetch_data
plenoptic.data.fetch.DOWNLOADABLE_FILES	plenoptic.data.DOWNLOADABLE_FILES
plenoptic.tools.data.make_disk	plenoptic.data.disk
plenoptic.tools.make_disk	plenoptic.data.disk
plenoptic.tools.data.polar_radius	plenoptic.data.polar_radius
plenoptic.tools.polar_radius	plenoptic.data.polar_radius
plenoptic.tools.data.polar_angle	plenoptic.data.polar_angle
plenoptic.tools.polar_angle	plenoptic.data.polar_angle
plenoptic.tools.data.load_images	plenoptic.load_images
plenoptic.tools.load_images	plenoptic.load_images
plenoptic.tools.validate.remove_grad	plenoptic.remove_grad
plenoptic.tools.remove_grad	plenoptic.remove_grad
plenoptic.tools.validate.validate_model	plenoptic.validate.validate_model
plenoptic.tools.validate_model	plenoptic.validate.validate_model
plenoptic.tools.validate.validate_input	plenoptic.validate.validate_input
plenoptic.tools.validate_input	plenoptic.validate.validate_input
plenoptic.tools.validate.validate_metric	plenoptic.validate.validate_metric
plenoptic.tools.validate_metric	plenoptic.validate.validate_metric
plenoptic.tools.validate.validate_coarse_to_fine	plenoptic.validate.validate_coarse_to_fine
plenoptic.tools.validate_coarse_to_fine	plenoptic.validate.validate_coarse_to_fine
plenoptic.tools.validate.validate_convert_tensor_dict	plenoptic.validate.validate_convert_tensor_dict
plenoptic.tools.validate_convert_tensor_dict	plenoptic.validate.validate_convert_tensor_dict
plenoptic.tools.optim.set_seed	plenoptic.set_seed
plenoptic.tools.set_seed	plenoptic.set_seed
plenoptic.tools.optim.mse	plenoptic.loss.mse
plenoptic.tools.mse	plenoptic.loss.mse
plenoptic.tools.optim.l2_norm	plenoptic.loss.l2_norm
plenoptic.tools.l2_norm	plenoptic.loss.l2_norm
plenoptic.tools.optim.relative_sse	plenoptic.loss.relative_sse
plenoptic.tools.relative_sse	plenoptic.loss.relative_sse
plenoptic.tools.optim.portilla_simoncelli_loss_factory	plenoptic.loss.portilla_simoncelli_loss_factory
plenoptic.tools.portilla_simoncelli_loss_factory	plenoptic.loss.portilla_simoncelli_loss_factory
plenoptic.tools.optim.groupwise_relative_l2_norm_factory	plenoptic.loss.groupwise_relative_l2_norm_factory
plenoptic.tools.groupwise_relative_l2_norm_factory	plenoptic.loss.groupwise_relative_l2_norm_factory
plenoptic.tools.optim.penalize_range	plenoptic.regularize.penalize_range
plenoptic.tools.regularization.penalize_range	plenoptic.regularize.penalize_range
plenoptic.tools.penalize_range	plenoptic.regularize.penalize_range
plenoptic.tools.io.examine_saved_synthesis	plenoptic.io.examine_saved_synthesis
plenoptic.tools.examine_saved_synthesis	plenoptic.io.examine_saved_synthesis
plenoptic.tools.external.plot_MAD_results	plenoptic.external.plot_MAD_results
plenoptic.tools.plot_MAD_results	plenoptic.external.plot_MAD_results
plenoptic.synthesize.metamer.plot_loss	plenoptic.plot.synthesis_loss
plenoptic.synthesize.metamer.display_metamer	plenoptic.plot.synthesis_imshow
plenoptic.synthesize.metamer.plot_pixel_values	plenoptic.plot.synthesis_histogram
plenoptic.synthesize.metamer.plot_representation_error	plenoptic.plot.metamer_representation_error
plenoptic.synthesize.metamer.plot_synthesis_status	plenoptic.plot.synthesis_status
plenoptic.synthesize.metamer.animate	plenoptic.plot.synthesis_animate
plenoptic.synthesize.mad_competition.display_mad_image	plenoptic.plot.synthesis_imshow
plenoptic.synthesize.mad_competition.display_mad_image_all	plenoptic.plot.mad_imshow_all
plenoptic.synthesize.mad_competition.plot_loss	plenoptic.plot.synthesis_loss
plenoptic.synthesize.mad_competition.plot_loss_all	plenoptic.plot.mad_loss_all
plenoptic.synthesize.mad_competition.plot_pixel_values	plenoptic.plot.synthesis_histogram
plenoptic.synthesize.mad_competition.plot_synthesis_status	plenoptic.plot.synthesis_status
plenoptic.synthesize.mad_competition.animate	plenoptic.plot.synthesis_animate
plenoptic.synthesize.eigendistortion.display_eigendistortion	plenoptic.plot.synthesis_imshow
plenoptic.synthesize.eigendistortion.display_eigendistortion_all	plenoptic.plot.eigendistortion_imshow_all
plenoptic.tools.display.imshow	plenoptic.plot.imshow
plenoptic.tools.imshow	plenoptic.plot.imshow
plenoptic.imshow	plenoptic.plot.imshow
plenoptic.tools.display.animshow	plenoptic.plot.animshow
plenoptic.tools.animshow	plenoptic.plot.animshow
plenoptic.animshow	plenoptic.plot.animshow
plenoptic.tools.display.pyrshow	plenoptic.plot.pyrshow
plenoptic.tools.pyrshow	plenoptic.plot.pyrshow
plenoptic.pyrshow	plenoptic.plot.pyrshow
plenoptic.tools.display.plot_representation	plenoptic.plot.plot_representation
plenoptic.tools.plot_representation	plenoptic.plot.plot_representation
plenoptic.tools.display.clean_stem_plot	plenoptic.plot.stem_plot
plenoptic.tools.clean_stem_plot	plenoptic.plot.stem_plot
plenoptic.tools.display.update_plot	plenoptic.plot.update_plot
plenoptic.tools.update_plot	plenoptic.plot.update_plot

The following functions are completely new:

Table 1 New functions

plenoptic.plot.histogram

plenoptic.io.LoadWarning

The following functions are deprecated and no longer accessible:

Table 2 Deprecated functions

plenoptic.tools.display.clean_up_axes

plenoptic.tools.clean_up_axes

plenoptic.tools.display.rescale_ylim

plenoptic.tools.rescale_ylim

plenoptic.tools.display.update_stem

plenoptic.tools.update_stem