Parameter Management¶
- class PyAstronomy.funcFit.Params(paramNames)¶
Manage a set of parameters.
This class provides a framework for managing parameter values and several associated aspects such as restrictions and relation. Parameter management is implemented in view of later use by a a fit routine.
- Parameters
- paramNameslist of strings
Specifies the names of the parameters to be managed.
Notes
Different models make different demands on the variables. For example, only certain ranges may be valid, some are constant and others not, or there may be a functional dependence between different variables. This class provides a framework to manage a parameter set appropriately.
Depending on what kind of model is currently adapted, the number, names, allowed ranges, and interdependencies of variables can differ. On creation, this class is given a list with parameter names to manage. Those can than be assigned values. Parameters can be “thawed”, i.e., regarded free during the fit process, or frozen. The allowed ranges can be restricted either on one or both sides, and interdependencies can be defined via the relate method.
- Attributes
- __paramsdict
A dictionary containing entries of the kind [variable-name:value]. The __params dictionary may only be access by the assignValue function to prevent causing inconsistencies, which may occur especially if relations exist. .
- paramNumdict
A dictionary assigning every parameter name to a number (e.g., paramNum[2] = “XYZ”). Such a numbering is important to guarantee the correct order of variables in the fitting process. The ordering is the same as the order in which the constructor obtains the parameter names.
- isFreedict
A dictionary associating each parameter with a boolean saying whether it shall be considered a free parameter during optimization.
- isRestricteddict
A dictionary associating each parameter with a boolean saying whether there is a restriction to the allowed range (see restrictions).
- restrictionsdict
A dictionary containing entries of the form [parName:[lower, upper]. Here ‘lower’ and ‘upper’ are floats defining lower and upper limits for the variable’s value.
- relationsdict
Parameters may be interrelated, e.g., A = B + C. This dictionary holds the definition of such relations. In particular, the entries have the form {“b”:[ [“a”, func, [“b”, “c”]], […] ]…}. This means that a = func(b, c). func is a function pointer. Whenever b is assigned a new value, ‘a’ has to be updated as well. Note that it is important that the independent variables “know” about the relation, because if their value changes, the value of the dependent variable (in this case a) has to be updated.
- conditionalRestrictionsdict
A dictionary holding the `conditional restrictions’, i.e., complex restrictions, which may, e.g., depend in the values of other parameters. The dictionary key is a unique ID generated, when a conditional restriction is added. For each key, the dictionary holds a tuple of which the first entry is a list holding the names of the parameters on which the conditional restrictions depends and the second is a callable, which is called with the values of those parameters specified in the first entry. The callable must return a float that specifies the penalty (or reward) depending on the given parameter values. Because conditional restrictions are referred to using a unique ID, their name (i.e., ID) does not change if models are combined.
Methods
addConditionalRestriction(pars, func)Define a conditional restriction.
applyConditionalRestrictions([fullout])Apply all conditional restrictions.
assignValue(namval)Define new parameter values.
Provides a list of existing parameters.
delRestriction(parName)Delete restriction
Get the names of the free parameters.
Get names and values of free parameters.
freeze(name)Freeze parameter(s) (contrary of thaw).
Get names and values of frozen parameters.
Get values of free parameters.
getPenalty([penaltyFact])Get applied penalty for current parameter set.
getRelationsOf(parName)Obtain relations for a parameter.
Get all restrictions.
hasParam(name)Check whether parameter exists.
Get number of free parameters.
parameterSummary([lines, toScreen, prefix, ...])Writes a summary of the parameters in text form.
Obtain parameter names and values.
relate(parName1, pars[, func, force])Apply functional relation between parameters.
Remove an existing conditional constraint.
renameParameter(old, new)Rename an existing parameter.
restoreState(resource)Restores parameter values from file or dictionary.
saveState([fn, clobber])Save the state of the fitting object.
Change the values of the free parameters.
setRestriction(restricts)Apply restrictions to parameter ranges.
showConditionalRestrictions([toScreen])Show conditional restrictions.
thaw(name)Thaw (regard as free) a parameter.
untie(parName[, forceFree])Remove all relations of parameter "parName".
- addConditionalRestriction(pars, func)¶
Define a conditional restriction.
Conditional restrictions can be used to modify the behavior in a more complex manner. For instance, penalties can be added to the objective function depending on the relation of one or more parameters.
The given function is evaluated in each iteration and its return value (a float) is added to the objective function (e.g., chi square).
- Parameters
- parslist of strings
The names of the parameters the given function needs as input.
- funccallable object
This callable object must take the specified parameters (in that exact order) as input. It must return a float, which is added to the value of the objective function.
- Returns
- identifierstring
A unique ID used to refer to the conditional restriction.
- applyConditionalRestrictions(fullout=False)¶
Apply all conditional restrictions.
- Parameters
- fulloutboolean, optional
If True, a dictionary holding the values of the individual restrictions is returned. The IDs are used as dictionary keys. The default is False.
- Returns
- Modificationfloat
The summed value of the existing conditional restrictions.
- Individual valuesdictionary, optional
The contributions of the individual conditional restrictions.
- assignValue(namval)¶
Define new parameter values.
- Parameters
- namvaldict
A dictionary containing [‘name’:’value’] pairs.
- availableParameters()¶
Provides a list of existing parameters.
- Returns
- Parameterslist of strings
A list with the names of available parameters.
- delRestriction(parName)¶
Delete restriction
- Parameters
- parNamestring
Name of restricted parameter
- freeParamNames()¶
Get the names of the free parameters.
- Returns
- Free parameterslist of strings
The names of the free parameters. The order is determined by the paramNum attribute.
- freeParameters()¶
Get names and values of free parameters.
- Returns
- Free parameters: dict
Dictionary containing the names and values of all free parameters ({“parName”:value, …}).
- freeze(name)¶
Freeze parameter(s) (contrary of thaw).
- Parameters
- namestring or list of strings
The name(s) of the parameter(s) to be frozen.
- frozenParameters()¶
Get names and values of frozen parameters.
- Returns
- Frozen parameters: dict
Dictionary containing the names and values of all frozen parameters ({“parName”:value, …}).
- getFreeParams()¶
Get values of free parameters.
- Returns
- Valueslist of floats
The values of the free parameters. Note that the order is determined by the paramNum attribute.
- getPenalty(penaltyFact=1e+20)¶
Get applied penalty for current parameter set.
- Parameters
- penaltyFactfloat, optional
The higher the number the higher the penalty for small deviations (default is 10**20).
- Returns
- Penaltyfloat
The applied penalty for current parameter set.
- Penaltiesdict
A dictionary with a key for every parameter values for which a bound is violated. The value is the amount by which the bound (upper or lower) is violated.
- getRelationsOf(parName)¶
Obtain relations for a parameter.
- Parameters
- parNamestring
The name of the parameter of which relations shall be searched.
- Returns
- Relationslist of relations
Those relations in which parName is the dependent variable, i.e., parName = f(x,y).
- getRestrictions()¶
Get all restrictions.
- Returns
- Restrictionsdict
Dictionary associating parameter name and restriction (see restrictions attribute).
- hasParam(name)¶
Check whether parameter exists.
- Parameters
- namestring
The parameter name.
- Returns
- flagboolean
True if parameter exists, False otherwise.
- numberOfFreeParams()¶
Get number of free parameters.
- Returns
- nint
The number of free parameters (determined by isFree).
- parameterSummary(lines=None, toScreen=True, prefix='', onlyParams=False)¶
Writes a summary of the parameters in text form.
- Parameters
- lineslist of strings, optional
If given, the output will be attached to this list.
- toScreenboolean, optional
If False, screen output will be suppressed (default is True).
- prefixstring, optional
A prefix applied to every output line (e.g., ‘#’)
- @FIXME - This is antique…
- Attaches the text lines
- to the lines list if given. If lines is not given, ‘toScreen’ will be set to True
- and the result is written to the screen.
- Returns either a new list containing the text, or (if given) the ‘lines’ list
- with result appended.
- A ‘prefix’ may be specified (e.g., ‘#’), which will preceded every line.
- parameters()¶
Obtain parameter names and values.
- Returns
- Name-valuedict
A dictionary with the names and values of all parameters ({“parName”:value, …}).
- relate(parName1, pars, func=None, force=False)¶
Apply functional relation between parameters.
Relates parameters, i.e., par1 = func(pars). The two values are related by ‘func’. In order to be tied, all involved parameters have to be free.
- Parameters
- parName1string
The name of the dependent variable.
- parslist of strings
Names of independent variables.
- funccallable
The function that determines the form of the dependence. The default is “equal”.
- forceboolean, optional
Set to True in order to suppress error when the dependent variable is frozen.
- removeConditionalRestriction(id)¶
Remove an existing conditional constraint.
- Parameters
- idstring
The identifier used to refer to the conditional constraint (returned by addConditionalRestriction).
- renameParameter(old, new)¶
Rename an existing parameter.
- Parameters
- oldstring
The existing (old) name.
- newstring
The new name.
- restoreState(resource)¶
Restores parameter values from file or dictionary.
- Parameters
- resourcestring or dictionary
If string, it is interpreted as filename of a pickle file holding the data dictionary. If dictionary, it uses the data saved in it; note that a valid data dictionary is returned by saveState.
- saveState(fn=None, clobber=False)¶
Save the state of the fitting object.
This method collects the parameter values, the applied restrictions, and the information whether parameters are free or frozen and saves them to the specified file (if given) using pickle. The saved state can be restored using the restoreState method.
Note
Unfortunately, “relations” cannot be saved.
- Parameters
- fnstring, optional
The filename to which the state shall be written. If None, the output will not be written to a file.
- clobberboolean, optional
If True, existing files will be overwritten (default is False).
- Returns
- Saved datadict
The dictionary containing the data saved to the file.
- setFreeParams(X)¶
Change the values of the free parameters.
- Parameters
- Xlist of floats
Contains the values for all free parameters. Note that the numbering is according to the paramNum attribute.
Notes
This method is primarily implemented to be used by fit routines.
- setRestriction(restricts)¶
Apply restrictions to parameter ranges.
- Parameters
- restrictsdict
A dictionary associating name and [lower-bound, upper-bound]. If no boundary shall exist on one side, use ‘None’.
- showConditionalRestrictions(toScreen=True)¶
Show conditional restrictions.
- Parameters
- toScreenboolean, optional
If True (default), the output is written to stdout.
- Returns
- Outputlist of strings
The output as a list of strings.
- thaw(name)¶
Thaw (regard as free) a parameter.
- Parameters
- namestring or list of strings
The name(s) of the parameter(s) to be thawed.
- untie(parName, forceFree=False)¶
Remove all relations of parameter “parName”.
After this operation, the parameter no longer depends on other parameters. Unless foreFree is True, the parameter referred to by “parName” is “frozen”.
- Parameters
- parNamestring
The name of the dependent variable, which shall be untied.
- forceFreeboolean
Set parName to “free” instead of “frozen” if set to True.
