Configuration File Format¶
The imfit
, imfit-mcmc
, and makeimage
programs always
require a configuration file (“config file” for short): a text file
which describes the model to be fit to or compared with the data (in the
case of imfit or imfit-mcmc) or to be generated (in the case of
makeimage), plus some optional information about the image itself.
Note that you can use the --sample-config
command-line option with
imfit
or makeimage
to have an example of a config file saved to
the current directory; this can then be edited to taste and used with
the appropriate program.
This page provides a basic description of the configuration file format.
(In what follows, I generally use “imfit” to refer to both imfit
and imfit-mcmc
, unless otherwise noted.)
Blank lines and Comments¶
Any blank lines in the file are ignored. Any lines beginning with the hash/pound symbol “#” are also ignored.
Finally, if a hash symbol is found in the middle of a line, then it and the rest of the line are ignored. This allows comments to be added on the same line as a meaningful entry (function declaration, parameter name and value, etc.).
(There is one minor exception to that last point, having to do with optional labels for funtions; see below.)
(Optional) Prelude: Describing the Image¶
The configuration file can start with a prelude which provides information about the data image (for imfit) or the output model image (in the case of makeimage). This is in the form of lines containing single “NAME value” pairs, e.g.
GAIN 4.5
These do not have to be provided, and you can provide as many or as
few of these as are needed (the exception being the NCOLS and NROWS
entries for a makeimage configuration file – both of those should be
provided unless you know you will be supplying makimage with relevant
info on the command line, via the --nrows
and --ncols
or
--refimage
options).
The allowed entries for an imfit configuration file are:
GAIN – the A/D gain value (electrons/count) for the image
READNOISE – any Gaussian read noise (electrons)
EXPTIME – total integration time if pixel values are counts/sec
NCOMBINED – number of images combined if pixel values are mean or median
ORIGINAL_SKY – any original constant value (e.g., sky background) which has already been subtracted from the image
The allowed entries for a makeimage configuration file are:
NCOLS – integer defining the width (number of columns) of the output image
NROWS – integer defining the height (number of rows) of the output image
All of this information can also be provided via command-line options, which if present will override any corresponding values in the configuration file.
Main Section: Defining the Model¶
The main (and required) section of the configuration file is the part which describes the actual model to be fit (or generated and saved in the case of makeimage). This consists of one or more function sets.
Function Sets¶
A function set is a central-coordinate (x0,y0) specification followed by one or more image-function declarations. This specifies a set of image functions which share the same center.
X0 <initial_value> [<limits>]
Y0 <initial_value> [<limits>]
FUNCTION <function_name>
<parameter specifications ...>
The optional limit specifications for X0 and Y0, which are only used by imfit, can have one of two forms:
The word “fixed”, which indicates that the parameter should be held fixed. E.g.
X0 101.5 fixed
A comma-separated pair of numbers specifying lower and upper limits, e.g.
X0 101.5 98.0,103.5
Image-Function Declarations¶
An image-function declaration consists of the word “FUNCTION”
followed by the name of one of Imfit’s image functions. (Recall that you
can use --list-functions
to get a list of the available image
functions and --list-parameters
to get that list along with the
parameter list for each function.) This is followed by the list of
parameter values; these are the values for generating a model image with
makeimage, or the initial values for the fitting process in imfit.
FUNCTION <function_name>
<parameter_name1> <initial_value> [<limits>]
<parameter_name2> <initial_value> [<limits>]
[etc.]
Optionally, you can include an arbitrary text label for a given function
on the same line as the world “FUNCTION” by adding
# LABEL <some text>
after the function name, e.g.:
FUNCTION <function_name> # LABEL <some label text>
(These labels do not affect the fitting, but are copied to the output; they are for allowing the user to more easily keep track of intended meanings of different components in complicated models.)
A simple example:
FUNCTION Exponential # LABEL main disk
PA 90
ell 0.5
I_0 100
h 15
The optional limit specifications for the parameters are exactly like those for the X0 and Y0 values (see above):
The word “fixed”, which indicates that the parameter should be held fixed; or
A comma-separated pair of numbers specifying lower and upper limits.
Note that parameter-limit specifications are actually required by imfit-mcmc. They are also required when using imfit’s Differential Evolution solver; they are optional for the other solvers (including the default Levenberg-Marquardt solver). Limit specifications are ignored by makeimage.
Examples¶
Single-function image¶
This is based on configuration file in the examples/
subdirectory,
where it is meant to be used to fit a single Sersic function to a 256 by
256-pixel cutout of an SDSS image. If used with makeimage, it generates
a 2D Sersic-function image using the specified parameters. This example
does not contain gain or read-noise specifications. Lower and upper
limits are listed for all parameters for use with imfit.
X0 129.0 125,135
Y0 129.0 125,135
FUNCTION Sersic
PA 18.0 0,90
ell 0.2 0,1
n 1.5 0,5
I_e 15 0,500
r_e 25 0,100
Single function set with two functions¶
This is a modification of the previous configuration file, using an Exponential function along with the Sersic function. In addition, the Sersic index n is held fixed with a value of 4 (making the Sersic profile a de Vaucouleurs profile). Both functions share the same center, and are thus part of a single function set. This version also includes an image-description prelude.
GAIN 4.725
READNOISE 4.3
ORIGINAL_SKY 130.14
X0 129.0 125,135
Y0 129.0 125,135
FUNCTION Sersic
PA 18.0 0,90
ell 0.2 0,1
n 4 fixed
I_e 15 0,500
r_e 25 0,100
FUNCTION Exponential
PA 18.0 0,90
ell 0.5 0,0.8
I_0 100 1,500
h 50 5,500
Multiple function sets¶
Multiple function sets can be included in a configuration file; these indicate different sets of image functions which share common centers (i.e, x0,y0 locations on the image).
A simple example, modifying the previous example by including a Sersic function representing a neighboring galaxy located approximately 110 pixels away in the X direction and 45 pixels away in Y:
GAIN 4.725
READNOISE 4.3
ORIGINAL_SKY 130.14
X0 129.0 125,135
Y0 129.0 125,135
FUNCTION Sersic
PA 18.0 0,90
ell 0.2 0,1
n 4 fixed
I_e 15 0,500
r_e 25 0,100
FUNCTION Exponential
PA 18.0 0,90
ell 0.5 0,0.8
I_0 100 1,500
h 50 5,500
X0 240.0 235,245
Y0 183.0 180,186
FUNCTION Sersic
PA -40.0 -10,-60
ell 0.5 0,1
n 1 0.5,2.0
I_e 5 0,520
r_e 10 0,20
Using Imfit Output Files with Makeimage¶
When imfit
successfully fits a model to an image, it saves the
best-fitting parameters to an output file (by default this file is
called bestfit_parameters_imfit.dat
). This file has the same basic
format as a config file, and can in fact be used as a config file by
makeimage
(though it will be missing the NCOLS
and NROWS
parameters, so you will have to add those to the file or else specify
them with command-line options).
An imfit
best-fit output file can even be used as input to another
invocation of imfit
itself, though it will lack any prelude
parameters describing the data image (GAIN
, etc.) and any parameter
limits or “fixed” specifications.
Quick and Dirty Generation of Config Files¶
As noted above, you can always generate a bare-bones sample config file
using the --sample-config
command-line option.
Calling imfit
or makeimage
with the --list-parameters
option
will print a list of all the functions and their parameters. You can
copy and paste the relevant parts of this output into a config file to
make function entries (aside from needing to fill in the initial values
and possible limits, of course!).