Module Documentation¶
This page contains documentation to everything symfit
has to offer.
BaseFit¶

class
symfit.core.fit.
BaseFit
(model, *ordered_data, **named_data)[source]¶ Bases:
object
Abstract Base Class for all fitting objects. Most importantly, it takes care of linking the provided data to variables. The allowed variables are extracted from the model.

__init__
(model, *ordered_data, **named_data)[source]¶ Parameters:  model – (dict of) sympy expression or
Model
object.  bool (absolute_sigma) – True by default. If the sigma is only used for relative weights in your problem, you could consider setting it to False, but if your sigma are measurement errors, keep it at True. Note that curve_fit has this set to False by default, which is wrong in experimental science.
 ordered_data – data for dependent, independent and sigma variables. Assigned in the following order: independent vars are assigned first, then dependent vars, then sigma’s in dependent vars. Within each group they are assigned in alphabetical order.
 named_data – assign dependent, independent and sigma variables data by name.
Standard deviation can be provided to any variable. They have to be prefixed with sigma_. For example, let x be a Variable. Then sigma_x will give the stdev in x.
 model – (dict of) sympy expression or

__weakref__
¶ list of weak references to the object (if defined)

dependent_data
¶ Readonly Property
Returns: Data belonging to each dependent variable. Return type: dict with variable names as key, data as value.

error_func
(*args, **kwargs)[source]¶ Every fit object has to define an error_func method, giving the function to be minimized.

eval_jacobian
(*args, **kwargs)[source]¶ Every fit object has to define an eval_jacobian method, giving the jacobian of the function to be minimized.

execute
(*args, **kwargs)[source]¶ Every fit object has to define an execute method. Any * and ** arguments will be passed to the fitting module that is being wrapped, e.g. leastsq.
Args kwargs: Returns: Instance of FitResults

independent_data
¶ Readonly Property
Returns: Data belonging to each independent variable. Return type: dict with variable names as key, data as value.

initial_guesses
¶ Returns: Initial guesses for every parameter.

sigma_data
¶ Readonly Property
Returns: Data belonging to each sigma variable. Return type: dict with variable names as key, data as value.

Fit¶

class
symfit.core.fit.
BaseFit
(model, *ordered_data, **named_data)[source] Bases:
object
Abstract Base Class for all fitting objects. Most importantly, it takes care of linking the provided data to variables. The allowed variables are extracted from the model.

__init__
(model, *ordered_data, **named_data)[source] Parameters:  model – (dict of) sympy expression or
Model
object.  bool (absolute_sigma) – True by default. If the sigma is only used for relative weights in your problem, you could consider setting it to False, but if your sigma are measurement errors, keep it at True. Note that curve_fit has this set to False by default, which is wrong in experimental science.
 ordered_data – data for dependent, independent and sigma variables. Assigned in the following order: independent vars are assigned first, then dependent vars, then sigma’s in dependent vars. Within each group they are assigned in alphabetical order.
 named_data – assign dependent, independent and sigma variables data by name.
Standard deviation can be provided to any variable. They have to be prefixed with sigma_. For example, let x be a Variable. Then sigma_x will give the stdev in x.
 model – (dict of) sympy expression or

__weakref__
list of weak references to the object (if defined)

dependent_data
Readonly Property
Returns: Data belonging to each dependent variable. Return type: dict with variable names as key, data as value.

error_func
(*args, **kwargs)[source] Every fit object has to define an error_func method, giving the function to be minimized.

eval_jacobian
(*args, **kwargs)[source] Every fit object has to define an eval_jacobian method, giving the jacobian of the function to be minimized.

execute
(*args, **kwargs)[source] Every fit object has to define an execute method. Any * and ** arguments will be passed to the fitting module that is being wrapped, e.g. leastsq.
Args kwargs: Returns: Instance of FitResults

independent_data
Readonly Property
Returns: Data belonging to each independent variable. Return type: dict with variable names as key, data as value.

initial_guesses
Returns: Initial guesses for every parameter.

sigma_data
Readonly Property
Returns: Data belonging to each sigma variable. Return type: dict with variable names as key, data as value.


class
symfit.core.fit.
Constraint
(constraint, model)[source]¶ Bases:
symfit.core.fit.Model
Constraints are a special type of model in that they have a type: >=, == etc. They are made to have lhs  rhs == 0 of the original expression.
For example, Eq(y + x, 4) > Eq(y + x  4, 0)
Since a constraint belongs to a certain model, it has to be initiated with knowledge of it’s parent model. This is important because all
numerical_
methods are done w.r.t. the parameters and variables of the parent model, not the constraint! This is because the constraint might not have all the parameter or variables that the model has, but in order to compute for example the Jacobian we still want to derive w.r.t. all the parameters, not just those present in the constraint.
__init__
(constraint, model)[source]¶ Parameters:  constraint – constraint that model should be subjected to.
 model – A constraint is always tied to a model.
Returns:

constraint_type
¶ alias of
Equality

jacobian
¶ Returns: Jacobian ‘Matrix’ filled with the symbolic expressions for all the partial derivatives. Partial derivatives are of the components of the function with respect to the Parameter’s, not the independent Variable’s.

numerical_components
¶ Returns: lambda functions of each of the components in model_dict, to be used in numerical calculation.

numerical_jacobian
¶ Returns: lambda functions of the jacobian matrix of the function, which can be used in numerical optimization.


class
symfit.core.fit.
Fit
(model, *ordered_data, **named_data)[source]¶ Bases:
symfit.core.fit.NumericalLeastSquares
Wrapper for NumericalLeastSquares to give it a more appealing name. In the future I hope to make this object more intelligent so it can search out the best fitting object based on certain qualifiers and return that instead.
Therefore do not assume this object to always behave as a certain fitting type! If it matters to you to have for example
NumericalLeastSquares
orNonLinearLeastSquares
for your problem, use those objects directly. What of course will not change, is the API.

class
symfit.core.fit.
FitResults
(params, popt, pcov, infodic, mesg, ier, ydata=None, sigma=None)[source]¶ Bases:
object
Class to display the results of a fit in a nice and unambiguous way. All things related to the fit are available on this class, e.g.  parameters + stdev  R squared (Regression coefficient.)  fitting status message
This object is made to behave entirely readonly. This is a bit unnatural to enforce in Python but I feel it is necessary to guarantee the integrity of the results.

__init__
(params, popt, pcov, infodic, mesg, ier, ydata=None, sigma=None)[source]¶ Excuse the ugly names of most of these variables, they are inherited. Should be changed. from scipy. :param params: list of
Parameter
‘s. :param popt: best fit parameters, same ordering as in params. :param pcov: covariance matrix. :param infodic: dict with fitting info. :param mesg: Status message. :param ier: Number of iterations. :param ydata:

__weakref__
¶ list of weak references to the object (if defined)

covariance
(param_1, param_2)[source]¶ Return the covariance between param_1 and param_2. :param param_1:
Parameter
Instance. :param param_2:Parameter
Instance. :return: Covariance of the two params.

infodict
¶ Readonly Property.

iterations
¶ Readonly Property.

params
¶ Readonly Property.

r_squared
¶ r_squared Property.
Returns: Regression coefficient.

status_message
¶ Readonly Property.

stdev
(param)[source]¶ Return the standard deviation in a given parameter as found by the fit. :param param:
Parameter
Instance. :return: Standard deviation ofparam
.


class
symfit.core.fit.
Likelihood
(model, *args, **kwargs)[source]¶ Bases:
symfit.core.fit.Maximize
Fit using a MaximumLikelihood approach.

class
symfit.core.fit.
LinearLeastSquares
(*args, **kwargs)[source]¶ Bases:
symfit.core.fit.BaseFit
Experimental. Solves the linear least squares problem analytically. Involves no iterations or approximations, and therefore gives the best possible fit to the data.
The
Model
provided has to be linear.Currently, since this object still has to mature, it suffers from the following limitations: * It does not check if the model can be linearized by a simple substitution.
For example, exp(a * x) > b * exp(x). You will have to do this manually. Does not use bounds or guesses on the
Parameter
‘s. Then again, it doesn’t have too, since you have an exact solution. No guesses required.  It only works with scalar functions. This is strictly enforced.

__init__
(*args, **kwargs)[source]¶ Raises: ModelError
in case of a nonlinear model or when a vector valued function is provided.

best_fit_params
()[source]¶ Fits to the data and returns the best fit parameters. :return: dict containing parameters and their bestfit values.

covariance_matrix
(best_fit_params)[source]¶ Given best fit parameters, this function finds the covariance matrix. This matrix gives the (co)variance in the parameters.
Parameters: best_fit_params – dict
of best fit parameters as given by .best_fit_params()Returns: covariance matrix.

execute
()[source]¶  Execute an analytical (Linear) Least Squares Fit. This object works by symbolically solving when :math:`
abla chi^2 = 0`.
To perform this task the expression of :math:` abla chi^2` is determined, ignoring that
\(\chi^2\) involves summing over all terms. Then the sum is performed by substituting the variables by their respective data and summing all terms, while leaving the parameters symbolic.
The resulting system of equations is then easily solved with
sympy.solve
. :return:FitResult
 Does not use bounds or guesses on the

class
symfit.core.fit.
Maximize
(model, *args, **kwargs)[source]¶ Bases:
symfit.core.fit.Minimize
Maximize a model subject to constraints. Simply flips the sign on error_func and eval_jacobian in order to maximize.

class
symfit.core.fit.
Minimize
(model, *args, **kwargs)[source]¶ Bases:
symfit.core.fit.BaseFit
Minimize a model subject to constraints. A wrapper for
scipy.optimize.minimize
.Minimize
currently doesn’t work when data is provided to Variables, and doesn’t support vector functions.
__init__
(model, *args, **kwargs)[source]¶ Because in a lot of use cases for Minimize no data is supplied to variables, all the empty variables are replaced by an empty np array.
Constraints: constraints the minimization is subject to.

error_func
(p, data)[source]¶ The function to be optimized. Scalar valued models are assumed. For Minimize the thing to evaluate is simply self.model(*(list(data) + list(p)))
Parameters:  p – array of floats for the parameters.
 data – data to be provided to
Variable
‘s.

eval_jacobian
(p, data)[source]¶ Takes partial derivatives of model w.r.t. each
Parameter
.Parameters:  p – array of floats for the parameters.
 data – data to be provided to
Variable
‘s.
Returns: array of length number of
Parameter
‘s in the model, with all partial derivatives evaluated at p, data.

scipy_constraints
¶ Readonly Property of all constraints in a scipy compatible format.
Returns: dict of scipy compatible statements.


class
symfit.core.fit.
Model
(*ordered_expressions, **named_expressions)[source]¶ Bases:
object
Model represents a symbolic function and all it’s derived properties such as sum of squares, jacobian etc. Models can be initiated from several objects:
a = Model.from_dict({y: x**2}) b = Model(y=x**2)
Models are callable. The usual rules apply to the ordering of the arguments:
 first independent variables, then dependent variables, then parameters.
 within each of these groups they are ordered alphabetically.

__call__
(*args, **kwargs)[source]¶ Evaluate the model for a certain value of the independent vars and parameters. Signature for this function contains independent vars and parameters, NOT dependent and sigma vars.
Can be called with both ordered and named parameters. Order is independent vars first, then parameters. Alphabetical order within each group.
Parameters:  args –
 kwargs –
Returns: A namedtuple of all the dependent vars evaluated at the desired point. Will always return a tuple, even for scalar valued functions. This is done for consistency.

__eq__
(other)[source]¶ Model
‘s are considered equal when they have the same dependent variables, and the same expressions for those dependent variables. The same is defined here as passing sympy == for the vars themselves, and as expr1  expr2 == 0 for the expressions. For more info check the `sympy docs<https://github.com/sympy/sympy/wiki/Faq>`_. :param other: Instance ofModel
. :return: bool

__init__
(*ordered_expressions, **named_expressions)[source]¶ Initiate a Model from keyword arguments:
b = Model(y=x**2)
Parameters:  ordered_expressions – sympy Expr
 named_expressions – sympy Expr

__weakref__
¶ list of weak references to the object (if defined)

bounds
¶ Returns: List of tuples of all bounds on parameters.

chi
¶ Returns: Symbolic Square root of \(\chi^2\). Required for MINPACK optimization only. Denoted as \(\sqrt(\chi^2)\)

chi_jacobian
¶ Return a symbolic jacobian of the \(\sqrt(\chi^2)\) function. Vector of derivatives w.r.t. each parameter. Not a Matrix but a vector! This is because that’s what leastsq needs.

chi_squared
¶ Returns: Symbolic \(\chi^2\)

chi_squared_jacobian
¶ Return a symbolic jacobian of the \(\chi^2\) function. Vector of derivatives w.r.t. each parameter. Not a Matrix but a vector!

components
¶ Returns: An iterator over the symbolic components of this model

classmethod
from_dict
(model_dict)[source]¶ Initiate a Model from a dict:
a = Model.from_dict({y: x**2})
Preferred way of initiating
Model
.Parameters: model_dict – dict of Expr
, where dependent variables are the keys.

jacobian
¶ Returns: Jacobian ‘Matrix’ filled with the symbolic expressions for all the partial derivatives. Partial derivatives are of the components of the function with respect to the Parameter’s, not the independent Variable’s.

numerical_chi
¶ Returns: lambda function of the .chi
method, to be used in MINPACK optimisation.

numerical_chi_jacobian
¶ Returns: lambda functions of the jacobian of the .chi
method, which can be used in numerical optimization.

numerical_chi_squared
¶ Returns: lambda function of the .chi_squared
method, to be used in numerical optimisation.

numerical_chi_squared_jacobian
¶ Returns: lambda functions of the jacobian of the .chi_squared
method.

numerical_components
¶ Returns: lambda functions of each of the components in model_dict, to be used in numerical calculation.

numerical_jacobian
¶ Returns: lambda functions of the jacobian matrix of the function, which can be used in numerical optimization.

ss_res
¶ Returns: Residual sum of squares. Similar to chi_squared, but without considering weights.

vars
¶ Returns: Returns a list of dependent, independent and sigma variables, in that order.

class
symfit.core.fit.
NonLinearLeastSquares
(*args, **kwargs)[source]¶ Bases:
symfit.core.fit.BaseFit
Experimental. Implements nonlinear least squares. Works by a two step process: First the model is linearised by doing a first order taylor expansion around the guesses for the parameters. Then a LinearLeastSquares fit is performed. This is iterated until a fit of sufficient quality is obtained.
Sensitive to good initial guesses. Providing good initial guesses is a must.
[wiki] https://en.wikipedia.org/wiki/Nonlinear_least_squares 
execute
(relative_error=0.0001, max_iter=5)[source]¶ Perform a nonlinear least squares fit. :param relative_error: Relative error between the sum of squares
of subsequent itterations. Once smaller than the value specified, the fit is considered complete.Parameters: max_iter – Maximum number of iterations before giving up. Returns: Instance of FitResults
.


class
symfit.core.fit.
NumericalLeastSquares
(model, *ordered_data, **named_data)[source]¶ Bases:
symfit.core.fit.BaseFit
Solves least squares numerically using leastsqbounds. Gives results consistent with MINPACK except when borders are provided.

class
symfit.core.fit.
ParameterDict
(params, popt, pcov, *args, **kwargs)[source]¶ Bases:
object
Container for all the parameters and their (co)variances. Behaves mostly like an OrderedDict: can be **ed, allowing the sexy syntax where a model is called with values for the Variables and **params. However, under iteration it behaves like a list! In other words, it preserves order in the params.

__getattr__
(name)[source]¶ A user can access the value of a parameter directly through this object.
Parameters: name – Name of a Parameter
. Naming convention: let a = Parameter(). Then: .a gives the value of the parameter. .a_stdev gives the standard deviation.

__getitem__
(param_name)[source]¶ This method allows this object to be addressed as a dict. This allows for the ** unpacking. Therefore return the value of the best fit parameter, as this is what the user expects.
Parameters: param_name – Name of the Parameter
whose value your interested in.Returns: the value of the best fit parameter with name ‘key’.

__weakref__
¶ list of weak references to the object (if defined)

covariance_matrix
¶ ReadOnly Property. Returns the covariance matrix.

get_stdev
(param)[source]¶ Deprecated. :param param:
Parameter
instance. :return: returns the standard deviation of param :raises: DeprecationWarning

get_value
(param)[source]¶ Deprecated. :param param:
Parameter
instance. :return: returns the numerical value of param :raises: DeprecationWarning


class
symfit.core.fit.
TaylorModel
(model)[source]¶ Bases:
symfit.core.fit.Model
A firstorder Taylor expansion of a model around given parameter values (\(p_0\)). Is used by NonLinearLeastSquares. Currently only a first order expansion is implemented.

__str__
()[source]¶ When printing a TaylorModel, the point around which the expansion took place is included.
For example, a Taylor expansion of {y: sin(w * x)} at w = 0 would be printed as:
@{w: 0.0} > y(x; w) = w*x

params
¶ params for a TaylorModel is defined differently, since the normal Model.params has both the \(p_0\)
Parameter
‘s around which to expand, and the parameters to be fitted. But when calling on the param property, you expect to get only the free parameters, not the \(p_0\) around which to expand.

Argument¶

class
symfit.core.argument.
Argument
(name=None, *sympy_args, **sympy_kwargs)[source]¶ Bases:
sympy.core.symbol.Symbol
Base class for
symfit
symbols. This helps makesymfit
symbols distinguishable fromsympy
symbols.The
Argument
class also makes DRY possible in definingArgument
‘s: it usesinspect
to read the lhs of the assignment and uses that as the name for theArgument
is none is explicitly set.For example:
x = Variable() print(x.name) >> 'x'

__weakref__
¶ list of weak references to the object (if defined)


class
symfit.core.argument.
Parameter
(value=1.0, min=None, max=None, fixed=False, name=None, *sympy_args, **sympy_kwargs)[source]¶ Bases:
symfit.core.argument.Argument
Parameter objects are used to facilitate bounds on function parameters.

__call__
(*values, **named_values)¶ Call an expression to evaluate it at the given point.
Future improvements: I would like if func and signature could be buffered after the first call so they don’t have to be recalculated for every call. However, nothing can be stored on self as sympy uses __slots__ for efficiency. This means there is no instance dict to put stuff in! And I’m pretty sure it’s ill advised to hack into the __slots__ of Expr.
However, for the moment I don’t really notice a performance penalty in running tests.
p.s. In the current setup signature is not even needed since no introspection is possible on the Expr before calling it anyway, which makes calculating the signature absolutely useless. However, I hope that someday some monkey patching expert in shining armour comes by and finds a way to store it in __signature__ upon __init__ of any
symfit
expr such that calling inspect_sig.signature on a symbolic expression will tell you which arguments to provide.Parameters:  self – Any subclass of sympy.Expr
 values – Values for the Parameters and Variables of the Expr.
 named_values – Values for the vars and params by name.
named_values
is allowed to contain too many values, as this sometimes happens when using **fit_result.params on a submodel. The irrelevant params are simply ignored.
Returns: The function evaluated at
values
. The type depends entirely on the input. Typically an array or a float but nothing is enforced.

__init__
(value=1.0, min=None, max=None, fixed=False, name=None, *sympy_args, **sympy_kwargs)[source]¶ Parameters:  value – Initial guess value.
 min – Lower bound on the parameter value.
 max – Upper bound on the parameter value.
 fixed (bool) – Fix the parameter to
value
during fitting.  name – Name of the Parameter.
 sympy_args – Args to pass to
sympy
.  sympy_kwargs – Kwargs to pass to
sympy
.


class
symfit.core.argument.
Variable
(name=None, *sympy_args, **sympy_kwargs)[source]¶ Bases:
symfit.core.argument.Argument
Variable type.
Operators¶
Monkey Patching module.
This module makes sympy
Expressions callable, which makes the whole project feel more consistent.

symfit.core.operators.
call
(self, *values, **named_values)[source]¶ Call an expression to evaluate it at the given point.
Future improvements: I would like if func and signature could be buffered after the first call so they don’t have to be recalculated for every call. However, nothing can be stored on self as sympy uses __slots__ for efficiency. This means there is no instance dict to put stuff in! And I’m pretty sure it’s ill advised to hack into the __slots__ of Expr.
However, for the moment I don’t really notice a performance penalty in running tests.
p.s. In the current setup signature is not even needed since no introspection is possible on the Expr before calling it anyway, which makes calculating the signature absolutely useless. However, I hope that someday some monkey patching expert in shining armour comes by and finds a way to store it in __signature__ upon __init__ of any
symfit
expr such that calling inspect_sig.signature on a symbolic expression will tell you which arguments to provide.Parameters:  self – Any subclass of sympy.Expr
 values – Values for the Parameters and Variables of the Expr.
 named_values – Values for the vars and params by name.
named_values
is allowed to contain too many values, as this sometimes happens when using **fit_result.params on a submodel. The irrelevant params are simply ignored.
Returns: The function evaluated at
values
. The type depends entirely on the input. Typically an array or a float but nothing is enforced.
Support¶
This module contains support functions and convenience methods used throughout symfit. Some are used predominantly internally, others are designed for users.

class
symfit.core.support.
RequiredKeyword
[source]¶ Bases:
object
Flag variable to indicate that this is a required keyword.

__weakref__
¶ list of weak references to the object (if defined)


exception
symfit.core.support.
RequiredKeywordError
[source]¶ Bases:
Exception
Error raised in case a keywordonly argument is not treated as such.

__weakref__
¶ list of weak references to the object (if defined)


symfit.core.support.
cache
(func)[source]¶ Decorator function that gets a method as its input and either buffers the input, or returns the buffered output. Used in conjunction with properties to take away the standard buffering logic.
Parameters: func – Returns:

symfit.core.support.
jacobian
(expr, symbols)[source]¶ Derive a symbolic expr w.r.t. each symbol in symbols. This returns a symbolic jacobian vector.
Parameters:  expr – A sympy Expr.
 symbols – The symbols w.r.t. which to derive.

symfit.core.support.
key2str
(target)[source]¶ In
symfit
there are many dicts with symbol: value pairs. These can not be used immediately as **kwargs, even though this would make a lot of sense from the context. This function wraps such dict to make them usable as **kwargs immidiately. :param target: dict to be made save :return: dict of str(symbol): value pairs.

class
symfit.core.support.
keywordonly
(**kwonly_arguments)[source]¶ Bases:
object
Decorator class which wraps a python 2 function into one with keywordonly arguments.
Example:
@keywordonly(floor=True) def f(x, **kwargs): floor = kwargs.pop('floor') return np.floor(x**2) if floor else x**2
This decorator is not much better than:
floor = kwargs.pop('floor') if 'floor' in kwargs else True
However, I prefer it’s usage because: it’s clear from reading the function deceleration there is an option to provide this argument. Plus your guaranteed that the pop works.
Please note that this decorator needs a ** argument in order to work.

__weakref__
¶ list of weak references to the object (if defined)


symfit.core.support.
parameters
(names)[source]¶ Convenience function for the creation of multiple parameters.
Parameters: names – string of parameter names. Should be comma seperated. Example: a, b = parameters(‘a, b’)

symfit.core.support.
seperate_symbols
(func)[source]¶ Seperate the symbols in symbolic function func. Return them in alphabetical order.
Parameters: func – scipy symbolic function. Returns: (vars, params), a tuple of all variables and parameters, each sorted in alphabetical order. Raises TypeError: only symfit Variable and Parameter are allowed, not sympy Symbols.

symfit.core.support.
sympy_to_py
(func, vars, params)[source]¶ Turn a symbolic expression into a Python lambda function, which has the names of the variables and parameters as it’s argument names.
Parameters:  func – sympy expression
 vars – variables in this model
 params – parameters in this model
Returns: lambda function to be used for numerical evaluation of the model. Ordering of the arguments will be vars first, then params.
Distributions¶
Some common distributions are defined in this module. That way, users can easily build more complicated expressions without making them look hard.
I have deliberately chosen to start these function with a capital, e.g. Gaussian instead of gaussian, because this makes the resulting expressions more readable.