holopy.core package
Loading, saving, and basic processing of data.
Subpackages
Submodules
holopy.core.errors module
Error classes used in holopy
- exception PerformanceWarning
Bases:
UserWarning
- raise_fitting_api_error(correct, obselete)
holopy.core.holopy_object module
Root class for all of holopy. This class provides serialization to and from yaml text file for all holopy objects.
yaml files are structured text files designed to be easy for humans to read and write but also easy for computers to read. HoloPy uses them to store information about experimental conditions and to describe analysis procedures.
- class HoloPyObject
Bases:
SerializableAncestor class for all HoloPy classes.
HoloPy object’s purpose is to provide the machinery for saving to and loading from HoloPy yaml files
- classmethod from_yaml(loader, node)
Convert a representation node to a Python object.
- classmethod to_yaml(dumper, data)
Convert a Python object to a representation node.
- class Serializable
Bases:
YAMLObjectBase class for any object that wants a nice clean yaml output
- classmethod to_yaml(dumper, data)
Convert a Python object to a representation node.
- class SerializableMetaclass(name, bases, kwds)
Bases:
YAMLObjectMetaclass
holopy.core.mapping module
- class Mapper
Bases:
HoloPyObjectCreates “maps” from objects containing priors that retain their hierarchical structure (including ties) but are easily serializable. The main entry point is through convert_to_map, which returns a map of the object and also updates the Mapper parameter and parameter_names attributes so they can be extracted for later use.
- add_parameter(parameter, name)
- check_for_ties(parameter)
- convert_to_map(parameter, name='')
- get_parameter_index(parameter, name)
- iterate_mapping(prefix, pairs)
- map_dictionary(parameter, name)
- map_transformed_prior(parameter, name)
- map_xarray(parameter, name)
- edit_map_indices(map_entry, indices)
Adjusts a map to account for ties between parameters
- Parameters:
map_entry – map or subset of map created by model methods
indices (listlike) – indices of parameters to be tied
- make_xarray(dim_name, keys, values)
Packs values into xarray with new dim and coords (keys)
- read_map(map_entry, parameter_values)
Reads a map to create an object
- Parameters:
map_entry – map or subset of map created by model methods
parameter_values (listlike) – values to replace map placeholders in final object
- transformed_prior(transformation, base_priors)
holopy.core.math module
- cartesian_distance(p1, p2=[0, 0, 0])
Return the Cartesian distance between points p1 and p2.
- chisq(fit, data)
Calculate per-point value of chi-squared comparing a best-fit model and data.
- Parameters:
fit (array_like) – Values of best-fit model to be compared to data
data (array_like) – Data values to be compared to model
- Returns:
chisq – Chi-squared per point
- Return type:
Notes
chi-squared is defined as
\[\chi^2 = \frac{1}{N}\sum_{\textrm{points}} (\textrm{fit} - \textrm{data})^2\]where \(N\) is the number of data points.
- find_transformation_function(initial_coordinates, desired_coordinates)
- keep_in_same_coordinates(coords)
- rotate_points(points, theta, phi, psi)
Rotate an array of points about Euler angles in a z, y, z convention.
- Parameters:
points (array-like (n,3)) – Set of points to be rotated
theta (float) – Euler rotation angles in z, y, z convention. These are not the same as angles in spherical coordinates.
phi (float) – Euler rotation angles in z, y, z convention. These are not the same as angles in spherical coordinates.
psi (float) – Euler rotation angles in z, y, z convention. These are not the same as angles in spherical coordinates.
- Returns:
rotated_points – Points rotated by Euler angles
- Return type:
array(n,3)
- rotation_matrix(alpha, beta, gamma, radians=True)
Return a 3D rotation matrix
- Parameters:
- Returns:
rot – Rotation matrix. To rotate a column vector x, use np.dot(rot, x.)
- Return type:
array(3,3)
Notes
The Euler angles rotate a vector (in the active picture) by alpha clockwise about the fixed lab z axis, beta clockwise about the lab y axis, and by gamma about the lab z axis. Clockwise is defined as viewed from the origin, looking in the positive direction along an axis.
This breaks compatability with previous conventions, which were adopted for compatability with the passive picture used by SCSMFO.
- rsq(fit, data)
Calculate correlation coeffiction R-squared comparing a best-fit model and data.
- Parameters:
fit (array_like) – Values of best-fit model to be compared to data
data (array_like) – Data values to be compared to model
- Returns:
rsq – Correlation coefficient R-squared.
- Return type:
Notes
R-squared is defined as
\[R^2 = 1 - \frac{\sum_{\textrm{points}} (\textrm{data} - \textrm{fit})^2}{\sum_{\textrm{points}} (\textrm{data} - \bar{\textrm{data}})^2}\]where \(\bar{\textrm{data}}\) is the mean value of the data. If the model perfectly describes the data, \(R^2 = 1\).
- to_cartesian(r, theta, phi)
- transform_cartesian_to_cylindrical(x_y_z)
- transform_cartesian_to_spherical(x_y_z)
- transform_cylindrical_to_cartesian(rho_phi_z)
- transform_cylindrical_to_spherical(rho_phi_z)
- transform_spherical_to_cartesian(r_theta_phi)
- transform_spherical_to_cylindrical(r_theta_phi)
holopy.core.metadata module
Classes for defining metadata about experimental or calculated results.
- clean_concat(arrays, dim)
Concatenate a list of xr.DataArray objects along a specified dimension, keeping the metadata of the first array.
- Parameters:
arrays (list of
xr.xarray)dim (valid dimension (string))
- Return type:
xarray
- copy_metadata(old, data, do_coords=True)
Create a new xarray with data from one input and metadata from another.
- Parameters:
old (xr.DataArray) – The xarray to copy the metadata from.
data (xr.DataArray) – The xarray to copy the data from.
do_coords (bool, optional) – Whether or not to copy the coordinates. Default is True
Returns
xr.DataArray
- data_grid(arr, spacing=None, medium_index=None, illum_wavelen=None, illum_polarization=None, noise_sd=None, name=None, extra_dims=None, z=0)
Create a set of detector points along with other experimental metadata.
- Return type:
DataArray object
Notes
Use the higher-level detector_grid() and detector_points() functions. This should be viewed as a factory method.
- detector_grid(shape, spacing, name=None, extra_dims=None)
Create a rectangular grid of pixels to represent a detector on which scattering calculations are to be performed.
- Parameters:
shape (int or list-like (2)) – If int, detector is a square grid of shape x shape points. If array_like, detector has shape[0] rows and shape[1] columns.
spacing (int or list-like (2)) – If int, distance between square detector pixels. If array_like, spacing[0] between adjacent rows and spacing[1] between adjacent columns.
name (string, optional)
extra_dims (dict, optional) – extra dimension(s) to add to the empty detector grid as {dimname: [coords]}.
- Returns:
grid – DataArray of zeros with coordinates calculated according to shape and spacing
- Return type:
DataArray object
Notes
Typically used to define a set of points to represent the pixels of a digital camera in scattering calculations.
- detector_points(coords={}, x=None, y=None, z=None, r=None, theta=None, phi=None, name=None)
Returns a one-dimensional set of detector coordinates at which scattering calculations are to be done.
- Parameters:
coords (dict, optional) – Dictionary of detector coordinates. Default: empty dictionary. Typical usage should not pass this argument, giving other parameters (Cartesian x, y, and z or polar r, theta, and phi coordinates) instead.
x (int or array_like, optional) – Cartesian x and y coordinates of detectors.
y (int or array_like, optional) – Cartesian x and y coordinates of detectors.
z (int or array_like, optional) – Cartesian z coordinates of detectors. If not specified, assume z = 0.
r (int or array_like, optional) – Spherical polar radial coordinates of detectors. If not specified, assume r = infinity (far-field).
theta (int or array_like, optional) – Spherical polar coordinates (polar angle from z axis) of detectors.
phi (int or array_like, optional) – Spherical polar azimuthal coodinates of detectors.
name (string)
- Returns:
grid – DataArray of zeros with calculated coordinates.
- Return type:
DataArray object
Notes
Specify either the Cartesian or the polar coordinates of your detector. This may be helpful for modeling static light scattering calculations. Use detector_grid() to specify coordinates of a grid of pixels (e.g., a digital camera.)
- dict_to_array(schema, inval)
- flat(a)
- from_flat(a)
- get_extents(detector_grid)
Find the x, y, z extent of a
`detector_grid`, as a dict.
- get_spacing(detector_grid)
Find the (x, y) spacing for a
`detector_grid`.
- get_values(a)
- make_coords(shape, spacing, z=0)
- make_subset_data(data, pixels=None, return_selection=False, seed=None)
Sub-sample a data for faster inference.
- Parameters:
data (xr.DataArray) – The data to subsample
pixels (int, optional) – The number of pixels to subsample. Defaults to the entire image.
return_selection (bool, optional) – Whether to return the pixel indices which were sampled. Default is False
seed (int or None, optional) – If not None, the seed to seed the random number generator with.
- Returns:
subset (xr.DataArray)
[selection (np.ndarray, dtype int])
- to_vector(c)
- update_metadata(a, medium_index=None, illum_wavelen=None, illum_polarization=None, noise_sd=None)
Returns a copy of an image with updated metadata in its ‘attrs’ field.
- Parameters:
a (xarray.DataArray) – image to update.
medium_index (float) – Updated refractive index of the medium in the image.
illum_wavelen (float) – Updated wavelength of illumination in the image.
illum_polarization (list-like) – Updated polarization of illumination in the image.
noise_sd (float) – standard deviation of Gaussian noise in the image.
- Returns:
b – copy of input image with updated metadata.
- Return type:
xarray.DataArray
holopy.core.prior module
- class BoundedGaussian(mu, sd, lower_bound=-inf, upper_bound=inf, name=None)
Bases:
Gaussian- lnprob(p)
Note that this does not return the actual log-probability, but a value proportional to it.
- prob(p)
Note that this does not return the actual probability, but a value proportional to it.
- sample(size=None)
- class ComplexPrior(real, imag, name=None)
Bases:
TransformedPriorA complex free parameter
ComplexPrior has a real and imaginary part which can (potentially) vary separately.
- Parameters:
real (float or
Prior) – The real and imaginary parts of this parameter. Assign floats to fix that portion or parameters to allow it to vary. The parameters must be purely real. You should omit names for the parameters; ComplexPrior will name themimag (float or
Prior) – The real and imaginary parts of this parameter. Assign floats to fix that portion or parameters to allow it to vary. The parameters must be purely real. You should omit names for the parameters; ComplexPrior will name themname (string) – Short descriptive name of the ComplexPrior. Do not provide this if using a ParameterizedScatterer, a name will be assigned based its position within the scatterer.
- property imag
- lnprob(p)
- property map_keys
- prob(p)
- property real
- class Gaussian(mu, sd, name=None)
Bases:
Prior- property guess
- lnprob(p)
- prob(p)
- sample(size=None)
- property variance
- class Prior
Bases:
HoloPyObjectBase class for Bayesian priors in holopy.
Prior subclasses should define at least the following methods: - guess - sample - prob - lnprob
- renamed(name)
- scale(physical)
- unscale(scaled)
- class TransformedPrior(transformation, base_prior, name=None)
Bases:
Prior- property guess
- lnprob(p)
- property map_keys
- prob(p)
- sample(size=None)
- class Uniform(lower_bound, upper_bound, guess=None, name=None)
Bases:
Prior- property interval
- lnprob(p)
- prob(p)
- sample(size=None)
- generate_guess(parameters, nguess=1, scaling=1, seed=None)
- make_center_priors(im, z_range_extents=5, xy_uncertainty_pixels=1, z_range_units=None)
Make sensible default priors for the center of a sphere in a hologram
- Parameters:
im (xarray) – The image you wish to make priors for
z_range_extents (float (optional)) – What range to extend a uniform prior for z over, measured in multiples of the total extent of the image. The default is 5 times the extent of the image, a large range, but since tempering is quite good at refining this, it is safer to just choose a large range to be sure to include the correct value.
xy_uncertainty_pixels (float (optional)) – The number of pixels of uncertainty to assume for the centerfinder. The default is 1 pixel, and this is probably correct for most images.
z_range_units (float) – Specify the range of the z prior in your data units. If provided, z_range_extents is ignored.
- updated(prior, v, extra_uncertainty=0)
Update a prior from a posterior
- Parameters:
v (UncertainValue) – The new value, usually from an mcmc result
extra_uncertainty (float) – provide a floor for uncertainty (sd) of the new parameter
holopy.core.utils module
Misc utility functions to make coding more convenient
- class LnpostWrapper(model, data, new_pixels=None, minus=False)
Bases:
HoloPyObjectWe want to be able to define a specific model.lnposterior calculation that only takes parameter values as an argument for passing into optimizers. However, individual functions can’t be pickled to distribute hologram calculations with python multiprocessing. This class solves both issues.
- evaluate(par_vals)
- choose_pool(parallel)
This is a remake of schwimmbad.choose_pool with a single argument.
- dict_without(d, keys)
Exclude a list of keys from a dictionary.
Silently ignores any key in keys that is not in the dict (this is intended to be used to make sure a dict does not contain specific keys) :param d: The dictionary to operate on :type d: dict :param keys: The keys to exclude :type keys: list(string) :param returns: A copy of dict without any of the specified keys :type returns: d2
- ensure_array(x)
if x is None, returns None. Otherwise, gives x in a form so that each of: len(x), x[0], x+2 will not fail.
- ensure_listlike(x)
- ensure_scalar(x)
- mkdir_p(path)
Equivalent to mkdir -p at the shell, this function makes a directory and its parents as needed, silently doing nothing if it exists.
- repeat_sing_dims(indict, keys='all')