Description Classes¶
The are classes which hold information about individual instances of Imfit image functions (FunctionDescription), the function sets which group one or more functions with a common central coordinate (FunctionSet), and finally Models which combine all function sets with optional image-description information (ModelDescription, SimpleModelDescription).
Each FunctionDescription, in turn, holds a set of ParameterDescription objects, which keep track of parameter names, initial or current values, and limits.
To properly instantiate an instance of the Imfit class, you must supply it with a previously generated instance of the ModelDescription (or SimpleModelDescription) class.
- class pyimfit.descriptions.FunctionDescription(func_name: str, label: str | None = '', parameters=None)¶
Holds information describing a single Imfit image function and its associated parameters, including their values and limits.
This contains the official Imfit image-function name (e.g., “Gaussian”, “EdgeOnDisk”), an optional label (e.g., “disk”, “outer ring”), and a list of ParameterDescription objects which describe the parameter names, values, and limits (or fixed status) for each of the image function’s parameters.
- label¶
optional label for this image function (e.g., “NSC”, “Outer disk”, etc.)
- Type:
str
- _funcName¶
name of the image function (e.g., “Gaussian”, “EdgeOnDisk”)
- Type:
str
- _label¶
unique (optional) label for this function (e.g., “disk”, “nuclear ring”)
- Type:
str
- _parameters¶
the list of ParameterDescription objects for the image-function parameters
- Type:
list of ParameterDescription
- nParameters¶
number of parameters for this function
- Type:
int
- addParameter(p)¶
Add a ParameterDescription instance for one of the function’s parameter
- parameterList()¶
Returns a list of the ParameterDescription objects
- addParameter(p: ParameterDescription)¶
Add a new ParameterDescription object.
Params¶
p : ParameterDecription
- classmethod dict_to_FunctionDescription(inputDict)¶
This is a convenience method to generate a FunctionDescription object from a dict specifying the function.
- Parameters:
inputDict (dict) –
- dict describing the function. Examples:
fDict = {‘name’: “Gaussian”, ‘label’: “blob”, ‘parameters’: p} where p is a dict containing parameter names and values, e.g. p = {‘PA’: 0.0, ‘ell’: 0.5, ‘I_0’: 100.0, ‘sigma’: 10.0} OR p = {‘PA’: [0.0, “fixed”], ‘ell’: [0.5, 0.1,0.8], ‘I_0’: [100.0, 10.0,1e3], ‘sigma’: [10.0, 5.0,20.0]}
- Returns:
fdesc – The function description.
- Return type:
- getFunctionAsDict()¶
- Returns a dict describing the function (suitable for use in e.g. dict_to_FunctionDescription())
- Examples:
fDict = {‘name’: “Gaussian”, ‘label’: “blob”, ‘parameters’: p} where p is a dict containing parameter names and values, e.g. p = {‘PA’: 0.0, ‘ell’: 0.5, ‘I_0’: 100.0, ‘sigma’: 10.0} OR p = {‘PA’: [0.0, “fixed”], ‘ell’: [0.5, 0.1,0.8], ‘I_0’: [100.0, 10.0,1e3], ‘sigma’: [10.0, 5.0,20.0]}
- getStringDescription(noLimits=False, errors: Sequence[float] | None = None)¶
Returns a list of strings suitable for inclusion in an imfit/makeimage config file.
- Parameters:
noLimits (bool, optional) – if True, then only parameter values (no limits or “fixed” indicators) are output
errors (sequence float, optional) – errors on parameter values (e.g., from Levenberg-Marquardt minimization)
- Returns:
outputStrings – list of newline-terminated strings, starting with function name and followed by one string for each parameter, as output by ParameterDescription.getStringDescription If errors is supplied, then parameter strings will contain “# +/- <error>” at end
- Return type:
list of string
- property label¶
Custom name/label for the function (e.g., “disk”, “nuclear ring”).
- parameterList()¶
A list of the parameters (ParameterDescription objects) of this image function.
- Returns:
param_list – List of the parameters.
- Return type:
list of
ParameterDescription
- parameterNameList()¶
A list of the parameters names (list of str) of this image function.
- Returns:
param_list – List of the parameter names.
- Return type:
list of str
- class pyimfit.descriptions.FunctionSetDescription(label: str | None = '', x0param: ParameterDescription | None = None, y0param: ParameterDescription | None = None, functionList: List[FunctionDescription] | None = None)¶
Holds information describing an image-function block/set: one or more Imfit image functions sharing a common (X0,Y0) position on the image.
This contains the X0 and Y0 coordinates, a list of FunctionDescription objects, and an optional label for the function set (e.g., “fs0”, “star 1”, “galaxy 5”, “offset nucleus”, etc.)
- label¶
label for the function set (”” = default no-name value)
- Type:
str
- _label¶
label for the function set
- Type:
str
- x0¶
x-coordinate of the function block/set’s center
- Type:
- y0¶
y-coordinate of the function block/set’s center
- Type:
- _functions¶
the FunctionDescription objects, one for each image function
- Type:
list of FunctionDescription
- nFunctions¶
number of functions in the function set
- Type:
int
- nParameters¶
total number of parameters for this function set, including X0 and Y0
- Type:
int
- hasPointSources¶
whether or not any of the image functions are PointSource-like (implementing interpolation of a PSF image)
- Type:
bool
Class methods¶
- dict_to_FunctionSetDescription(dict)
Returns a new instance of this class based on a dict
- addFunction(f)¶
Add a FunctionDescription instance
- functionList()¶
Returns a list of the FunctionDescription objects in the function set
- functionNameList()¶
Returns a list of names for the image-functions in the function set
- functionLabelList()¶
Returns a list of labels for the image-functions in the function set
- parameterList()¶
Returns a list of ParameterDescription objects corresponding to the function block/set (including X0,Y0)
- addFunction(f: FunctionDescription)¶
Add an Imfit image function created using
make_image_function().- Parameters:
f (
FunctionDescription.) – Function description to be added to the function set.
- classmethod dict_to_FunctionSetDescription(inputDict: dict)¶
A convenience method to generate a FunctionSetDescription object from a dict
- Parameters:
inputDict (dict) –
dict describing the function set {‘X0’: val-or-list, ‘Y0’: val-or-list, ‘function_list’: [list of dicts describing functions]} {‘label’: str, ‘X0’: val-or-list, ‘Y0’: val-or-list, ‘function_list’: [list of dicts describing functions]}
- where “val-or-list” for X0 and Y0 is one of
value [value, “fixed”] [value, lower-limit, upper-limit]
- Returns:
fset – The function-set description.
- Return type:
- functionLabelList()¶
A list of labels for the Imfit image-functions making up this function set.
- Returns:
function_list – List of the function types.
- Return type:
list of str
- functionList()¶
A list of the FunctionDescription objects making up this function set.
- Returns:
function_list – List of the functions.
- Return type:
list of FunctionDescription
- functionNameList()¶
A list of the Imfit image-function names making up this function set.
- Returns:
function_list – List of the function types.
- Return type:
list of str
- getFuncSetAsDict()¶
Returns a dict describing the function set (suitable for use in e.g. dict_to_FunctionSetDescription())
{‘X0’: list, ‘Y0’: list, ‘function_list’: [list of dicts describing functions]} OR {‘label’: str, ‘X0’: list, ‘Y0’: list, ‘function_list’: [list of dicts describing functions]}
- getStringDescription(noLimits=False, errors: Sequence[float] | None = None)¶
Returns a list of strings suitable for inclusion in an imfit/makeimage config file.
- Parameters:
noLimits (bool, optional) – if True, then only parameter values (no limits or “fixed” indicators) are output
errors (sequence float, optional) – errors on parameter values (e.g., from Levenberg-Marquardt minimization)
- Returns:
outputStrings – list of newline-terminated strings describing the function set. If errors is supplied, then parameter strings will contain “# +/- <error>” at end
- Return type:
list of string
- property label¶
Custom name/label for the function set.
- parameterList()¶
A list of all the parameters corresponding to this function set (including the X0,Y0 position).
- Returns:
param_list – List of the parameters.
- Return type:
list of
ParameterDescription
- class pyimfit.descriptions.ModelDescription(functionSetsList: List[FunctionSetDescription] | None = None, options: Dict[str, float] | None = None)¶
Holds information describing an Imfit model, including image-description data.
The main components are a dict containing image-descriptions parameters and their values (e.g., {“GAIN”: 4.5, “ORIGINAL_SKY”: 325.39} and a list of FunctionSetDescription objects, corresponding to the image-function sets/blocks making up the model proper.
- optionsDict¶
dict mapping image-description parameters (e.g., “GAIN”) to their corresponding values
- Type:
dict of {str: float}
- options¶
dict mapping image-description parameters (e.g., “GAIN”) to their corresponding values [this is the internal name for the property optionsDict]
- Type:
dict of {str: float}
- _functionSets¶
the individual image-function sets making up the model
- Type:
list of FunctionSetDescription
- nFunctionSets¶
- Type:
int
- nParameters¶
total number of model parameters
- Type:
int
- hasPointSources¶
whether or not any of the image functions are PointSource-like (implementing interpolation of a PSF image)
- Type:
bool
Class methods¶
- load(fname)
Returns a new instance of this class based on a standard Imfit configuration file (fname).
- addFunctionSet(fs)¶
Add a function block/set to the model description
- addOptions(optionDict)¶
Add image-description options via a dict
- functionSetIndices()¶
Returns a list of
intspecifying the function-set start indices
- functionList()¶
Retuns a list of FunctionDescription instances for all the image functions in the model
- functionNameList()¶
Returns a list of names for the image-functions in the function set
- functionLabelList()¶
Returns a list of labels for the image-functions in the function set
- parameterList()¶
Returns a list of ParameterDescription instances corresponding to all the parameters in the model
- addFunctionSet(fs: FunctionSetDescription)¶
Add a function set to the model description.
- Parameters:
fs (
FunctionSetDescription) – Function set description instance.
- classmethod dict_to_ModelDescription(inputDict: dict)¶
A convenience method to generate a ModelDescription object from a dict.
- Parameters:
inputDict (dict) –
dict describing the model, with one required entry – “function_sets” – and one optional entry – “options”
”function_sets” : list of dict, each one specifying a function set, suitable as input to FunctionSetDescription.dict_to_FunctionSetDescription()
”options” : dict of {str: float} specifying image-description options (“GAIN”, “ORIGINAL_SKY”, etc.)
- Returns:
mdesc – The model description.
- Return type:
- functionLabelList()¶
Get list of labels for the image functions making up this model.
- Returns:
functionLabels – List of the function labels.
- Return type:
list of str
- functionList()¶
Get list of the FunctionDescription objects making up this model.
- Returns:
functions
- Return type:
list of FunctionDescription objects
- functionNameList()¶
Get list of names of the image functions making up this model.
- Returns:
functionNames – List of the function names.
- Return type:
list of str
- functionSetIndices()¶
Get the indices in the full parameters list corresponding to the starts of individual function sets/blocks.
- Returns:
indices
- Return type:
list of int
- functionSetNameList()¶
Get list of the functions composing this model, as strings, grouped by function set.
- Returns:
functionSetList – List of the function names, grouped by function set: [[functions_in_set1], [functions_in_set2], …]
- Return type:
list of list of string
- getModelAsDict()¶
Returns the model in dict form (suitable for use in e.g. dict_to_ModelDescription)
- Returns:
modelDict
- Return type:
dict
- getParameterLimits()¶
Get list containing lower and upper limits for all parameters in the model.
- Returns:
parameterLimits – [(lower_limit, upper_limit)_1, (lower_limit, upper_limit)_2, …]
- Return type:
list of 2-element tuples of float
- getRawParameters()¶
Get Numpy array of the ModelDescription’s current parameter values
- Returns:
paramValues
- Return type:
ndarray of float
- getStringDescription(noLimits=False, errors: Sequence[float] | None = None, saveOptions=False)¶
Get list of strings suitable for inclusion in an imfit/makeimage config file.
- Parameters:
noLimits (bool, optional) – if True, then only parameter values (no limits or “fixed” indicators) are output
errors (sequence float, optional) – errors on parameter values (e.g., from Levenberg-Marquardt minimization)
saveOptions (bool, optional) – if False, then image-description options (GAIN, READNOISE, etc.) are not output
- Returns:
outputLines – list of newline-terminated strings describing the model. If errors is supplied, then parameter strings will contain “# +/- <error>” at end
- Return type:
list of string
- classmethod load(fileName: str)¶
A convenience method to generate a ModelDescription object from a standard Imfit configuration file.
- Parameters:
fileName (string) – Path to the Imfit configuration file.
- Returns:
model – The model description.
- Return type:
See also
parse_config_file
- property numberedParameterNames¶
List of parameter names for the current model, annotated by function number. E.g., [“X0_1”, “Y0_1”, “PA_1”, “ell_1”, “I_0_1”, “h_1”, …]
- property optionsDict¶
Image-description options, as a dict E.g., {“GAIN”: 2.75, “READNOISE”: 103.43}
- parameterList()¶
Get list of the parameters (ParameterDescription objects) making up this model.
- Returns:
params – List of the parameters.
- Return type:
list of
ParameterDescription
- replaceOptions(optionsDict: Dict[str, float])¶
Replace the current image-descriptions dict. This differs from updateOptions() in that it will completely replace the current image-descriptions dict, discarding any key-value pairs with keys not in the replacement dict.
- Parameters:
optionDict (dict) –
- updateOptions(optionsDict: Dict[str, float])¶
Update the internal image-descriptions dict, replacing current values for keys already in the dict and added key-value pairs for keys not already present.
- Parameters:
optionDict (dict) –
- class pyimfit.descriptions.ParameterDescription(name: str, value: float, limits: Sequence[float] | None = None, fixed=False)¶
Holds information for a single parameter of an Imfit image function, or the X0 or Y0 parameter of a function block/set (corresponding to what is encoded in a single parameter line of an Imfit configuration file).
It holds the name, current value (e.g., a suggested initial value), possible lower and upper limits for fitting purposes, and whether or not the value is to be held fixed during a fit.
- name¶
label of the parameter (e.g., “X0”, “sigma”)
- Type:
str
- value¶
current value of the parameter
- Type:
float
- limits¶
lower and upper limits for parameter when fitting
- Type:
2-element tuple of float
- fixed¶
whether a parameter should be held fixed during fitting
- Type:
bool
- _name¶
label of the parameter (e.g., “X0”, “sigma”)
- Type:
str
- _value¶
current value of the parameter
- Type:
float
- _limits¶
lower and upper limits for parameter when fitting
- Type:
2-element tuple of float
- _fixed¶
whether a parameter should be held fixed during fitting
- Type:
bool
- setValue(value, limits=None, fixed=False)¶
Set the value (and limits, fixed state) of the parameter
- setTolerance(tol)¶
Set the limits as +/- fraction of parameter value
- setLimitsRel(i1, i2)¶
Set the limits as -i1,+i2 relative to parameter value
- setLimits(v1, v2)¶
Set the limits directly
- getStringDescription(noLimits=False, error=none)¶
Returns a string containing parameter name and value (and optionally limits or 1-sigma uncertainty)
- property fixed¶
Whether or not this parameter is to be held fixed, as a bool.
- getParamInfoList()¶
- Returns a list in one of three formats
[param-value]
[param-value, “fixed”] – if parameter is fixed
[param-value, lower-limit, upper-limit] – if parameter has limits
- getStringDescription(noLimits=False, error: float | None = None)¶
Returns a string with parameter name, value, limits, suitable for inclusion in an imfit/makeimage config file.
- Parameters:
noLimits (bool, optional) – if True, then only parameter values (no limits or “fixed” indicators) are output
error (float, optional) – error on parameter value (e.g., from Levenberg-Marquardt minimization); if supplied then no limit info is output, but “# +/- <error>” is appended
- Returns:
outputString
- Return type:
str
- property limits¶
The low and upper limits for the parameter, as a tuple of float.
- property name¶
“x0”, “I_e”.
- Type:
The label of the parameter (str). Examples
- setLimits(v1: float, v2: float)¶
Set the parameter limits using specified values: [v1, v2]
- Parameters:
v1 (float) – Lower limit.
v2 (float) – Upper limit.
- setLimitsRel(i1: float, i2: float)¶
Set the parameter limits using relative intervals. The limits will be [value - i1, value + i2]
- Parameters:
i1 (float) – Lower limit interval.
i2 (float) – Upper limit interval.
- setTolerance(tol: float)¶
Set the parameter limits using a fractional “tolerance” value, so that the lower limit = (1 - tol)*value and the upper limit = (1 + tol)*value. For example, a tolerance of 0.2 for a property of value 1.0 sets the limits to [0.8, 1.2].
- Parameters:
tol (float) – Fractional offset for lower and upper limits; must lie between 0.0 and 1.0.
- setValue(value: float, limits: Sequence[float] | None = None, fixed: bool = False)¶
Set the value and (optionally) constraints of the parameter.
- Parameters:
value (float) – Value of the parameter.
limits (2-element sequence of float, optional) – Lower and upper limits of the parameter. Default:
None(= no limits).fixed (bool, optional) – Flag the parameter as fixed. Default:
False.
- property value¶
The value of the parameter (float).
- class pyimfit.descriptions.SimpleModelDescription(inst=None)¶
Simple version of ModelDescription with only one function set.
- x0¶
ParameterDescription object for the x-coordinate of the model center
- Type:
- y0¶
ParameterDescription object for the y-coordinate of the model center
- Type:
- addFunction(f: FunctionDescription)¶
Add a function created using
function_description().- Parameters:
f (
FunctionDescription.) – Function description to be added to the model.
- property x0¶
X coordinate of the center of the model. Instance of
ParameterDescription.
- property y0¶
Y coordinate of the center of the model. Instance of
ParameterDescription.