Conventions

Here, we will outline some of the conventions used by prysm. These will be useful to understand if extending the library, or performing custom analysis.

prysm uses a large number of classes which carry data and metadata about the signals with their namesakes. They can be divided loosely into two caregories,

  • phases

  • images

Both have common properties of x and y, which are one dimensional arrays giving the gridded coordinates in x and y.

[1]:
# an example of a phase-type object and an image-type object
from prysm import Pupil, Slit

pu = Pupil()
sl = Slit(1, sample_spacing=0.075, samples=64)

pu.x[:3], sl.y[:3]  # only first three elements for brevity
[1]:
(array([-0.5       , -0.49212598, -0.48425197]),
 array([-2.4  , -2.325, -2.25 ]))

Each has an array that holds the numerical representation of the signal itself, for phaes-type objects this is phase and for image-type objects this is data. The convention is y,x indices, consistent with numpy. This is the opposite convention used by matlab.

[2]:
pu.phase[:3,:3], sl.data[:3,:3]
[2]:
(array([[nan, nan, nan],
        [nan, nan, nan],
        [nan, nan, nan]]),
 array([[0., 0., 0.],
        [0., 0., 0.],
        [0., 0., 0.]]))

both inherit from RichData (in fact, just about every class in prysm does) which imbues them with a brevy of properties:

[3]:
from prysm._richdata import RichData
help(RichData)
Help on class RichData in module prysm._richdata:

class RichData(builtins.object)
 |  RichData(x, y, data, labels, xy_unit=None, z_unit=None, wavelength=None)
 |
 |  Abstract base class holding some data properties.
 |
 |  Methods defined here:
 |
 |  __init__(self, x, y, data, labels, xy_unit=None, z_unit=None, wavelength=None)
 |      Initialize a new BasicData instance.
 |
 |      Parameters
 |      ----------
 |      x : `numpy.ndarray`
 |          x unit axis
 |      y : `numpy.ndarray`
 |          y unit axis
 |      data : `numpy.ndarray`
 |          data
 |      labels : `Labels`
 |          labels instance, can be shared
 |      xyunit : `astropy.unit` or `str`, optional
 |          astropy unit or string which satisfies hasattr(astropy.units, xyunit)
 |      zunit : `astropy.unit` or `str`, optional
 |           astropy unit or string which satisfies hasattr(astropy.units, xyunit)
 |      wavelength : `astropy.unit` or `float`
 |          astropy unit or quantity or float with implicit units of microns
 |
 |      Returns
 |      -------
 |      RichData
 |          the instance
 |
 |  astype(self, other_type)
 |      Change this instance of one type into another.
 |
 |      Useful to access methods of the other class.
 |
 |      Parameters
 |      ----------
 |      other_type : `object`
 |          the name of the other type to "cast" to, e.g. Interferogram.  Not a string.
 |
 |      Returns
 |      -------
 |      `self`
 |          type-converted to the other type.
 |
 |  change_xy_unit(self, to, inplace=True)
 |      Change the x/y unit to a new one, scaling the data in the process.
 |
 |      Parameters
 |      ----------
 |      to : `astropy.unit` or `str`
 |          if not an astropy unit, a string that is a valid attribute of astropy.units.
 |      inplace : `bool`, optional
 |          if True, returns self.  Otherwise returns the modified data.
 |
 |      Returns
 |      -------
 |      `RichData`
 |          self, if inplace=True
 |      `numpy.ndarray`, `numpy.ndarray`
 |          x, y from self, if inplace=False
 |
 |  change_z_unit(self, to, inplace=True)
 |      Change the z unit to a new one, scaling the data in the process.
 |
 |      Parameters
 |      ----------
 |      to : `astropy.unit` or `str`
 |          if not an astropy unit, a string that is a valid attribute of astropy.units.
 |      inplace : `bool`, optional
 |          if True, returns self.  Otherwise returns the modified data.
 |
 |      Returns
 |      -------
 |      `RichData`
 |          self, if inplace=True
 |      `numpy.ndarray`
 |          data from self, if inplace=False
 |
 |  copy(self)
 |      Return a (deep) copy of this instance.
 |
 |  exact_polar(self, rho, phi=None)
 |      Retrieve data at the specified radial coordinates pairs.
 |
 |      Parameters
 |      ----------
 |      r : iterable
 |          radial coordinate(s) to sample
 |      phi : iterable
 |          azimuthal coordinate(s) to sample
 |
 |      Returns
 |      -------
 |      `numpy.ndarray`
 |          data at the given points
 |
 |  exact_x(self, x)
 |      Return data at an exact x coordinate along the y=0 axis.
 |
 |      Parameters
 |      ----------
 |      x : `number` or `numpy.ndarray`
 |          x coordinate(s) to return
 |
 |      Returns
 |      -------
 |      `numpy.ndarray`
 |          ndarray of values
 |
 |  exact_xy(self, x, y=None)
 |      Retrieve data at the specified X-Y frequency pairs.
 |
 |      Parameters
 |      ----------
 |      x : iterable
 |          X coordinate(s) to retrieve
 |      y : iterable
 |          Y coordinate(s) to retrieve
 |
 |      Returns
 |      -------
 |      `numpy.ndarray`
 |          data at the given points
 |
 |  exact_y(self, y)
 |      Return data at an exact y coordinate along the x=0 axis.
 |
 |      Parameters
 |      ----------
 |      y : `number` or `numpy.ndarray`
 |          y coordinate(s) to return
 |
 |      Returns
 |      -------
 |      `numpy.ndarray`
 |          ndarray of values
 |
 |  plot2d(self, xlim=None, ylim=None, clim=None, cmap=None, log=False, power=1, interpolation=None, show_colorbar=True, show_axlabels=True, fig=None, ax=None)
 |      Plot the data in 2D.
 |
 |      Parameters
 |      ----------
 |      xlim : `float` or iterable, optional
 |          x axis limits.  If not iterable, symmetric version of the single value
 |      ylim : `float` or iterable, optional
 |          y axis limits.  If None and xlim is not None, copied from xlim.
 |          If not iterable, symmetric version of the single value.
 |      clim : iterable, optional
 |          clim passed directly to matplotlib.
 |          If None, looked up on self._default_clim.
 |      cmap : `str`, optional
 |          colormap to use, passed directly to matplotlib if not None.
 |          If None, looks up the default cmap for self._data_type on config
 |      log : `bool`, optional
 |          if True, plot on a log color scale
 |      power : `float`, optional
 |          if not 1, plot on a power stretched color scale
 |      interpolation : `str`, optional
 |          interpolation method to use, passed directly to matplotlib
 |      show_colorbar : `bool`, optional
 |          if True, draws the colorbar
 |      show_axlabels : `bool`, optional
 |          if True, draws the axis labels
 |      fig : `matplotlib.figure.Figure`
 |          Figure containing the plot
 |      ax : `matplotlib.axes.Axis`
 |          Axis containing the plot
 |
 |      Returns
 |      -------
 |      fig : `matplotlib.figure.Figure`
 |          Figure containing the plot
 |      ax : `matplotlib.axes.Axis`
 |          Axis containing the plot
 |
 |  slices(self, twosided=None)
 |      Create a `Slices` instance from this instance.
 |
 |      Parameters
 |      ----------
 |      twosided : `bool`, optional
 |          if None, copied from self._default_twosided
 |
 |      Returns
 |      -------
 |      `Slices`
 |          a Slices object
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)
 |
 |  center_x
 |      Center "pixel" in x.
 |
 |  center_y
 |      Center "pixel" in y.
 |
 |  sample_spacing
 |      center-to-center sample spacing.
 |
 |  samples_x
 |      Number of samples in the x dimension.
 |
 |  samples_y
 |      Number of samples in the y dimension.
 |
 |  shape
 |      Proxy to phase or data shape.
 |
 |  size
 |      Proxy to phase or data size.

prysm is a metadata-heavy library, with many functions and procedures taking a several arguments, most of which populated with sane default values. A number of these defaults can be controlled through prysm’s config object,

[4]:
from prysm import config
from pprint import pprint
[5]:
controlled_properties = [i for i in dir(config) if not i.startswith('_') and not i == 'initialized']
pprint(controlled_properties, width=1)
['Q',
 'alpha',
 'chbackend_observers',
 'convolvable_labels',
 'image_cmap',
 'image_xy_unit',
 'image_z_unit',
 'interferogram_labels',
 'interpolation',
 'lw',
 'mtf_labels',
 'mtf_xy_unit',
 'mtf_z_unit',
 'phase_cmap',
 'phase_xy_unit',
 'phase_z_unit',
 'precision',
 'precision_complex',
 'psd_labels',
 'ptf_labels',
 'ptf_xy_unit',
 'ptf_z_unit',
 'pupil_labels',
 'show_units',
 'unit_format',
 'wavelength',
 'zorder']

To change the value used by prysm, simply assign to the property,

[6]:
# use 32-bit floats instead of 64-bit, ~50% speedup to all operations in exchange for accuracy
config.precision = 32