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

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 result – an object containing the best fit parameters and information about the fit 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

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)

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')
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=[])

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)

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)

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 constraint – A function which tests scatterers to see if the exceed the specified tolerance 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)

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)

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)) – scaled np.array(dtype=float)
unscale(scaled)

Inverts scale’s transformation

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