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:

      `FunctionDescription`

  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:

      ParameterDescription

  y0

    y-coordinate of the function block/set’s center

    Type:

      ParameterDescription

  _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:

      `FunctionSetDescription`

  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 `int` specifying 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:

      `ModelDescription`

  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:

      `ModelDescription`

    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

      1. [param-value]

      2. [param-value, “fixed”] – if parameter is fixed

      3. [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:

      ParameterDescription

  y0

    ParameterDescription object for the y-coordinate of the model center

    Type:

      ParameterDescription

  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`.