holopy.fitting package

Module contents

Fit models of scattering to data

Make precision measurements of a scattering system by fitting a model of it to data

The fitting module is used to:

  1. Define Scattering Model -> Model object
  2. Fit model to data -> FitResult object
  3. Fit model to timeseries -> list of FitResult objects

holopy.fitting.fit module

Routines for fitting a hologram to an exact solution

class FitResult(parameters, scatterer, chisq, rsq, converged, time, model, minimizer, minimization_details)

Bases: holopy.core.holopy_object.HoloPyObject

The results of a fit.

You should not make objects of this class directly, they will be given to you by fit()

Parameters:
  • parameters (array(float)) – The fitted values for each parameter
  • scatterer (Scatterer) – The best fit scatterer
  • chisq (float) – The \(\chi^2\) goodness of fit
  • rsq (float) – The \(R^2\) goodness of fit
  • converged (bool) – Did the minimizer converge
  • time (float) – Time in seconds the fit took
  • minimizer (Minimizer) – Them minimizer used in the fit
  • minimization_details (object) – Additional information returned by the minimizer about the minimization
alpha
fitted_holo(schema)
classmethod from_summary(summary, scatterer_cls)

Build a FitResult from a summary.

The returned FitResult will be incomplete because summaries do not contain all of the minimizer information that full results do

Parameters:summary (dict) – A dict as from cls.summary containing information about a fit.
next_model()

Construct a model to fit the next frame in a time series

niter()
summary()

Put just the essential components of a fit result in a dictionary

summary_misc = ['rsq', 'chisq', 'time', 'converged', 'niter']
fit(model, data, minimizer=<class 'holopy.fitting.minimizer.Nmpfit'>, random_subset=None)

fit a model to some data

Parameters:
  • model (Model object) – A model describing the scattering system which leads to your data and the parameters to vary to fit it to the data
  • data (Marray object) – The data to fit
  • minimizer ((optional) Minimizer) – The minimizer to use to do the fit
  • random_subset (float (optional)) – Fit only a randomly selected fraction of the data points in data
Returns:

result – an object containing the best fit parameters and information about the fit

Return type:

FitResult

make_subset_data(data, random_subset=None, pixels=None, return_selection=False)

holopy.fitting.minimizer module

Interfaces to minimizers. Classes here provide a common interface to a variety of third party minimizers.

class Minimizer

Bases: holopy.core.holopy_object.HoloPyObject

Common interface to all minimizers holopy supports

minimize(parameters, cost_func)

Find the best solution to an optimization problem

Parameters:
  • parameters (list of Parameter objects) – Parameters to vary in the model
  • cost_func (function) – A function taking parameters as arguments that returns the residual for the minimization problem
pars_from_minimizer(parameters, values)
class Nmpfit(quiet=False, ftol=1e-10, xtol=1e-10, gtol=1e-10, damp=0, maxiter=100)

Bases: holopy.fitting.minimizer.Minimizer

Levenberg-Marquardt minimizer, from Numpy/Python translation of Craig Markwardt’s mpfit.pro.

Parameters:
  • quiet (Boolean) – If True, suppress output on minimizer convergence.
  • ftol (float) – Convergence criterion for minimizer: converges if actual and predicted relative reductions in chi squared <= ftol
  • xtol (float) – Convergence criterion for minimizer: converges if relative error between two Levenberg-Marquardt iterations is <= xtol
  • gtol (float) – Convergence criterion for minimizer: converges if absolute value of cosine of angle between vector of cost function evaluated at current solution for minimized parameters and any column of the Jacobian is <= gtol
  • damp (float) – If nonzero, residuals larger than damp will be replaced by tanh. See nmpfit documentation.
  • maxiter (int) – Maximum number of Levenberg-Marquardt iterations to be performed.

Notes

See nmpfit documentation for further details. Not all functionalities of nmpfit are implemented here: in particular, we do not allow analytical derivatives of the residual function, which is impractical and/or impossible to calculate for holograms. If you want to weight the residuals, you need to supply a custom residual function.

minimize(parameters, cost_func, debug=False)

Find the best solution to an optimization problem

Parameters:
  • parameters (list of Parameter objects) – Parameters to vary in the model
  • cost_func (function) – A function taking parameters as arguments that returns the residual for the minimization problem

holopy.fitting.model module

Classes for defining models of scattering for fitting

class BaseModel(scatterer, medium_index=None, illum_wavelen=None, illum_polarization=None, theory='auto')

Bases: holopy.core.holopy_object.HoloPyObject

get_par(name, pars, schema=None, default=None)
get_pars(names, pars, schema=None)
par(name, schema=None, default=None)
parameters
class Model(scatterer, calc_func, medium_index=None, illum_wavelen=None, illum_polarization=None, theory='auto', alpha=None, use_random_fraction=None, constraints=[])

Bases: holopy.fitting.model.BaseModel

Representation of a model to fit to data

Parameters:
  • alpha (float or Parameter) – Extra scaling parameter, hopefully this will be removed by improvements in our theory soon.
  • constraints (function or list of functions) – One or a list of constraint functions. A constraint function should take a scaterer as an argument and return False if you wish to disallow that scatterer (usually because it is un-physical for some reason)
get_alpha(pars=None)
guess
guess_dict
residual(pars, data)
class ParameterizedObject(obj)

Bases: holopy.fitting.model.Parametrization

Specify parameters for a fit by including them in an object

Parameters are named automatically from their position in the object

Parameters:obj (scatterer) – Object containing parameters specifying any values vary in the fit. It can also include numbers for any fixed values
guess
make_from(parameters)
class Parametrization(make_scatterer, parameters)

Bases: holopy.core.holopy_object.HoloPyObject

Description of free parameters and how to make a scatterer from them

Parameters:
  • make_scatterer (function) – A function which should take the Parametrization parameters by name as keyword arguments and return a scatterer
  • parameters (list) – The list of parameters for this Parametrization
guess
make_from(parameters)
limit_overlaps(fraction=0.1)

Generator for constraint prohibiting overlaps beyond a certain tolerance

Parameters:fraction (float) – Fraction of the sphere diameter that the spheres should be allowed to overlap by
Returns:constraint – A function which tests scatterers to see if the exceed the specified tolerance
Return type:function (scatterer -> bool)
tied_name(name1, name2)

holopy.fitting.parameter module

Classes for describing free parameters in fitting models

class ComplexParameter(real, imag, name=None)

Bases: holopy.fitting.parameter.Parameter

A complex free parameter

ComplexParameters have 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 name’s for the parameters; ComplexParameter will name them
  • name (string) – Short descriptive name of the ComplexParameter. Do not provide this if using a ParameterizedScatterer, a name will be assigned based its position within the scatterer.
guess
class Parameter(guess=None, limit=None, name=None, **kwargs)

Bases: holopy.core.holopy_object.HoloPyObject

Describe a free parameter in a fitting model

Parameters:
  • guess ((optional) float) – Your inital guess for this parameter
  • limit ((optional) float or (float, float)) – Describe how the minimizer should allow a parameter to vary. A single value here fixes the parameter to that value, a pair limits the parameter to vary between (min, max)
  • name ((optional) string) – A short descriptive name of the parameter. Do not provide this if using the parameter in a ParameterizedScatterer, it will assign a name based on the Parameter’s position within the scatterer
  • **kwargs (varies) – Additional information made available to the minimizer. This can be used for things like step sizes.
fixed
scale(physical)

Scales parameters to approximately unity

Parameters:physical (np.array(dtype=float)) –
Returns:scaled
Return type:np.array(dtype=float)
unscale(scaled)

Inverts scale’s transformation

Parameters:scaled (np.array(dtype=float)) –
Returns:physical
Return type:np.array(dtype=float)