holopy.core package

Loading, saving, and basic processing of data.

Subpackages

• holopy.core.io package
  • Submodules
• holopy.core.process package
  • Submodules

Submodules

Error classes used in holopy

exception BadImage

Bases: Exception

exception CoordSysError

Bases: Exception

exception DependencyMissing(dependency, message='')

Bases: Exception

exception DeprecationError

Bases: Exception

exception LoadError(filename, message)

Bases: Exception

exception NoMetadata

Bases: Exception

exception PerformanceWarning

Bases: UserWarning

raise_fitting_api_error(correct, obselete)

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: holopy.core.holopy_object.Serializable

Ancestor 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: yaml.YAMLObject

Base 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: yaml.YAMLObjectMetaclass

class Mapper

Bases: holopy.core.holopy_object.HoloPyObject

Creates “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)

cartesian_distance(p1, p2=[0, 0, 0])

Return the Cartesian distance between points p1 and p2.

Parameters:p2 (p1,) – Coordinates of point 1 and point 2 in N-dimensions Returns:dist – Cartesian distance between points p1 and p2 Return type:float64

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:

float

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
• phi, psi (theta,) – 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:

• beta, gamma (alpha,) – Euler rotation angles in z, y, z convention
• radians (boolean) – Default True; treats input angles in radians

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:

float

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)

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)) –

Returns:

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.

Returns: 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.
• y (x,) – 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

class BoundedGaussian(mu, sd, lower_bound=-inf, upper_bound=inf, name=None)

Bases: holopy.core.prior.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: holopy.core.prior.TransformedPrior

A complex free parameter

ComplexPrior has a real and imaginary part which can (potentially) vary separately.

Parameters:

• imag (real,) – 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 them
• name (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.

imag

lnprob(p)

map_keys

prob(p)

real

class Gaussian(mu, sd, name=None)

Bases: holopy.core.prior.Prior

guess

lnprob(p)

prob(p)

sample(size=None)

variance

class Prior

Bases: holopy.core.holopy_object.HoloPyObject

Base 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: holopy.core.prior.Prior

guess

lnprob(p)

map_keys

prob(p)

sample(size=None)

class Uniform(lower_bound, upper_bound, guess=None, name=None)

Bases: holopy.core.prior.Prior

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

Misc utility functions to make coding more convenient

class LnpostWrapper(model, data, new_pixels=None, minus=False)

Bases: holopy.core.holopy_object.HoloPyObject

We 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)

class NonePool

Bases: object

close()

map(function, arguments)

class SuppressOutput(suppress_output=True)

Bases: object

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')

updated(d, update={}, filter_none=True, **kwargs)

Return a dictionary updated with keys from update

Analgous to sorted, this is an equivalent of d.update as a non-modifying free function

Parameters:

• d (dict) – The dict to update
• update (dict) – The dict to take updates from