API Reference

Building models

The Expr class

class squmfit.Expr

An expression capable of taking parameters from a packed parameter vector. All of the usual Python arithmetic operations are supported as well as a good fraction of the Numpy ufuncs. Note, however, that the ufuncs’ out parameter is not supported.

evaluate(params, **user_args)

Evaluate the model with the given parameter values.

Parameters:

• params (array, shape = [n_params]) – Packed parameters vector
• user_args (kwargs) – Keyword arguments from user

gradient

The gradient of the expression with respect to the fitted parameters or raise a ValueError if not applicable.

Return type:Expr evaluating to array of shape (Nparams,)

parameters()

Return the set of fitted parameters used by this expression.

Return type:set of FittedParam.

map(f)

Lift a function into an Expr.

Parameters:f (Function of type A -> B) – The function to lift. Returns:Given an Expr evaulating to a value of type A and a function A -> B, returns an Expr of type B.

negative(out=None)

absolute(out=None)

rint(out=None)

sign(out=None)

conj(out=None)

exp(out=None)

log(out=None)

log2(out=None)

log10(out=None)

expm1(out=None)

log1p(out=None)

sqrt(out=None)

square(out=None)

reciprocal(out=None)

sin(out=None)

cos(out=None)

tan(out=None)

arcsin(out=None)

arccos(out=None)

arctan(out=None)

sinh(out=None)

cosh(out=None)

tanh(out=None)

arcsinh(out=None)

arccosh(out=None)

arctanh(out=None)

deg2rad(out=None)

rad2deg(out=None)

floor(out=None)

ceil(out=None)

trunc(out=None)

Evaluating Exprs

squmfit.model(func)

Transforms a function to ensure that all of its parameters are evaluated. Calls to the transformed function will result in an Expr when any of its parameters are Exprs.

The FittedParam class

class squmfit.parameter.FittedParam(param_set, idx, name=None, initial=None)

A parameter to be fitted to data.

evaluate(params, **user_args)

Evaluate the model with the given parameter values.

Parameters:

• params (array, shape = [n_params]) – Packed parameters vector
• user_args (kwargs) – Keyword arguments from user

gradient()

The gradient of the expression with respect to the fitted parameters or raise a ValueError if not applicable.

Return type:Expr evaluating to array of shape (Nparams,)

parameters()

Return the set of fitted parameters used by this expression.

Return type:set of FittedParam.

Performing fits

The Fit class

class squmfit.Fit

This represents a fit configuration.

add_curve(name, model, data, weights=None, **user_args)

Add a curve to the fit.

Parameters:

• name (str) – A unique name for the curve.
• model (Expr) – The analytical model which will be fit to the curve.
• data (array, shape = [n_samples]) – An array of the dependent values for each sample.
• weights (array, shape = [n_samples], optional) – An array of the weight of each sample. Often this is \(1 / \sigma\) where sigma is the standard deviation of the dependent value. If not given uniform weights are used.
• user_args (kwargs) – Keyword arguments passed to the model during evaluation.

eval(params, **user_args)

Evaluate the model against a dictionary of parameters

Parameters:

• params (dict, param_name -> float) – A dictionary of parameters values.
• user_args (kwargs) – Keyword arguments passed to the model.

Return type:

dict, curve_name -> array, shape = [n_samples]

Returns:

The value of the model evaluated with the given parameters.

eval_packed(params, **user_args)

Evaluate the model against packed parameters values

Parameters:

• params (array, shape = [n_params]) – A packed array of parameters.
• user_args (kwargs) – Keyword arguments passed to the model.

Return type:

dict, curve_name -> array, shape = [n_samples]

fit(params0=None, report_progress=None, **user_args)

Carry out the fit.

Parameters:

• params0 (dict, param_name -> float) – The initial parameter values.
• report_progress (float or None) – Period with which to report on fit progress (in seconds).
• user_args (kwargs) – Keyword arguments passed to the model.

Return type:

A FitResults object.

param(name=None, initial=None)

Create a new parameter.

Parameters:

• name (str, optional) – The name of the new parameter. A name will be generated if this is omitted.
• initial (float, optional) – The initial value of the parameter. If not provided then a value must be provided when fit() is called.

Return type:

parameter.FittedParam

residuals(params, weighted=True, **user_args)

Evaluate the weighted model residuals against a dictionary of parameters values. See eval() for parameter descriptions.

residuals_packed(params, weighted=True, **user_args)

Compute the weighed residuals against packed paramater values. See eval_packed() for parameter descriptions.

The FitResult class

class squmfit.FitResult(fit, params, covar_p=None, initial_result=None)

This embodies a set of parameter values, possibly originating from a fit.

correl

The correlation coefficient between parameters or None if not available.

Return type:dict, param_name -> param_name -> float or None

covar

The covariances between parameters, or None if not available (which may either be due to numerical trouble in calculation or simply not being provided when the FitResult was created).

Return type:dict of dicts, param_name -> param_name -> float or None

curves

Results for particular curves.

Return type:dict, curve_name -> CurveResult

eval(expr)

Evaluate the given Expr against the fitted parameter values.

Parameters:expr (Expr) – The expression to evaluate. Returns:The evaluation of expr

fit

The Fit to which these parameter apply.

Return type:Fit

initial

The FitResult used as the initial parameters for the Fit from which this result originated.

Return type:FitResult

params

The fitted parameter values

Return type:array, shape = [n_params]

stderr

The standard error of the parameter estimate or None if not available.

Return type:dict, param_name -> float or None

total_chi_sqr

The sum of the individual curves’ chi-squared values. This can be useful as a global goodness-of-fit metric.

Return type:float

The CurveResult class

class squmfit.CurveResult(fit_result, curve)

This embodies a set of parameter values describing the goodness-of-fit with respect to a given curve.

chi_sqr

Chi-squared of the fit.

Return type:float

curve

The curve described by this result

Return type:Curve

degrees_of_freedom

The number of degrees-of-freedom of the fit. This is defined as the number of data points in the curve minus the number of free parameters in the fitting model.

Return type:int

eval(**user_args)

Evaluate the curve’s model with overridden user arguments.

fit

The model evaluated with the parameter values.

Return type:ndarray

fit_result

The FitResult this CurveResult was derived from.

Return type:FitResult

reduced_chi_sqr

Reduced chi-squared of the fit. Namely, chi_sqr / degrees_of_freedom.

Return type:float

residuals

The weighted residuals of the fit.

Return type:ndarray

Rendering fit results

Text

squmfit.pretty.html_fit_result(result, min_corr=0.5)

Pretty-print a fit result as an HTML-formatted string

Parameters:min_corr (float) – Don’t show correlations smaller than this threshold Return type:str

squmfit.pretty.ipynb_fit_result(result, min_corr=0.5)

Produce a HTML summary of a FitResult suitable for rendering by IPython notebook.

Parameters:result (FitResult) – The result to summarize.

squmfit.pretty.markdown_fit_result(result, min_corr=0.5)

Pretty-print a fit result as a Markdown-formatted string

Parameters:min_corr (float) – Don’t show correlations smaller than this threshold Return type:str

Plotting

squmfit.plot.plot_curve(x, result, range=None, axes=None, npts=300, xscale='linear', errorbars=True, label=None, color=None, **kwargs)

Plot the result of a fit against a curve.

Parameters:

• x – A key found in the user_args for the curve.
• range (tuple of two floats) – The limits of the X axis.
• npts (int) – Number of interpolation points for fit.
• xscale ('linear', 'log', or 'symlog') – The scale to use for the X axis (see pl.xscale()).
• label – The label for the curve. Defaults to the curve’s name.

squmfit.plot.plot_curve_residuals(x, result, range=None, axes=None, xscale='linear', abs_residuals=False, residual_range=None, **kwargs)

Plot the residuals of a curve.

Parameters:

• x – A key found in the user_args for the curve.
• range ((xmin, xmax), optional) – The limits of the X axis
• xscale ('linear', 'log', or 'symlog') – The scale to use for the X axis (see pl.xscale()).
• axes (pl.Axes) – Axes to plot on.
• abs_residuals (bool) – Whether to plot weighted (relative) or unweighted (absolute residuals).
• residual_range ((ymin, ymax), optional) – Y range of residual plot
• kwargs – Keyword arguments to be passed to Axes.scatter().

squmfit.plot.plot_fit(x, result, range=None, xscale='linear', errorbars=True, fig=None, with_residuals=True, abs_residuals=False, residual_range=None, legend_kwargs={}, marker=None)

Plot the result of a fit.

Parameters:

• x – A key found in user_args for each curve in the fit
• range ((xmin, xmax), optional) – Range of abscissa
• xscale ('linear', 'log', or 'symlog') – The scale to use for the X axis (see pl.xscale()).
• errorbars (bool) – Plot errorbars on points.
• fig (pl.Figure, optional) – The figure on which to plot.
• with_residuals (bool) – Plot residuals alongside fit
• abs_residuals (bool) – Whether to plot weighted (relative) or unweighted (absolute residuals).
• residual_range ((ymin, ymax), optional) – Y range of residual plot
• marker – Set the marker with which to mark points
• legend_kwargs – Keyword arguments passed to pl.legend().

Helper classes

These classes represent the various nodes of the expression tree. It is generally not necessary to use these explicitly but they have been included for completeness.

The Constant class

class squmfit.expr.Constant(value)

An Expr containing a constant value

__init__(value)

Create a constant-valued Expr

Parameters:value – The value

evaluate(params, **user_args)

Evaluate the model with the given parameter values.

Parameters:

• params (array, shape = [n_params]) – Packed parameters vector
• user_args (kwargs) – Keyword arguments from user

parameters()

Return the set of fitted parameters used by this expression.

Return type:set of FittedParam.

The FiniteDiffGrad class

class squmfit.expr.FiniteDiffGrad(expr)

The gradient of an expression computed by finite difference

__init__(expr)

Create an expression representing the gradient of an expression.

Parameters:expr (Expr) – The expression to differentiate.

evaluate(params, **user_args)

Evaluate the model with the given parameter values.

Parameters:

• params (array, shape = [n_params]) – Packed parameters vector
• user_args (kwargs) – Keyword arguments from user

parameters()

Return the set of fitted parameters used by this expression.

Return type:set of FittedParam.