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