Provided by: alfa_2.2-1build3_amd64 
NAME
alfa - automated line fitting algorithm
SYNOPSIS
alfa [OPTION] [VALUE]... [FILE]
DESCRIPTION
alfa rapidly fits emission line spectra, using a genetic algorithm to optimise fitting
parameters. It is intended to be entirely automated, but while the default values should
work well in many situations, a good fit to your observed spectrum may require some
adjustments to the input parameters. It is optimised for optical spectra, but can be
applied to any wavelength range if a suitable line catalogue is provided.
alfa reads one dimensional spectra in either plain text or FITS format. Plain text input
should consist of two columns, giving wavelength and flux. It can also read data cubes
and row-stacked spectra in FITS format. Results are written out in plain text, to files
containing the fit (total fit, continuum-subtracted original, continuum, sky lines and
residuals), and the line flux measurements.
OPTIONS
-b, --bad-data [REAL]
If all values in a spectrum are below the value specified, alfa will not fit it.
Most useful for avoiding wasting time on low signal regions of data cubes.
--citation
Prints out the bibliographic details of the paper to cite if you use alfa in your
research.
-cl, --clobber
alfa's default behaviour is that it will not overwrite any pre-existing output
file. If this option is specified, then the output file will be overwritten.
--collapse
Sums all spectra in multi-dimensional FITS files into a single spectrum. Spectra
whose peak value is below any value specified with the --bad-data option are
excluded. --collapse has no effect on 1D data.
-cw, --continuum-window [INTEGER]
ALFA's continuum fitting takes the 25th percentile of flux values in a moving
window as representative of the continuum level. This option can be used to set the
size of the window. The value must be an odd integer. Default: 101
-dl, --detection-limit [REAL]
Sets the factor by which a line's flux must exceed the locally estimated noise
level for it to be considered a detection. Default: 3.0
-el, --exclude-line [REAL]
When reading in the line catalogues, any wavelengths indicated with this option
will be ignored. For example, if H alpha were saturated, it could be excluded from
the fit with --exclude-line 6562.77. Any number of lines can be excluded by
repeating the option with the appropriate wavelengths.
-fc, --flux-column [INTEGER]
When reading FITS tables, this option can be used to specify in which table column
the flux values are. For any other file type it will have no effect. Default: 2
-g, --generations [INTEGER]
The number of generations used in the genetic algorithm. Default: 500
-n, --normalise [VALUE]
Normalise to Hb=100 assuming that F(Hb)=VALUE. If VALUE is zero, no normalisation
is applied. If this option is not specified, fluxes are normalised using the
measured value of Hb if it is detected, and not normalised otherwise.
-nc, --no-continuum
In case the spectrum you are fitting is already continuum subtracted, setting this
option skips alfa's continuum fitting.
-o, --output-dir [DIRECTORY]
The directory in which to put the output files. Default: current working directory.
-of, --output-format [VALUE]
The format of the output files. Valid values are text, csv, fits, latex. If you are
using alfa in conjunction with neat, plain text and fits formats can currently be
read in. Default: text
-pr, --pressure [REAL]
The fraction of the population retained from each generation. The product of the
pressure and the population size should be an integer. Default: 0.3
-ps, --populationsize [INTEGER]
The size of the population used in the genetic algorithm. Default: 30
-rb, --rebin [INTEGER]
Rebin the input spectrum by the specified factor. Useful for high resolution
spectra where line profiles are not instrumental but kinematic. This option is
currently only implemented for 1d spectra.
-rg, --resolution-guess [VALUE]
Initial guess for the resolution [lambda/delta lambda]. Default: estimated using
the sampling of the input spectrum, assuming that it is Nyquist sampled.
-rtol1, --resolution-tolerance-1 [VALUE]
Variation allowed in resolution in first pass. Default: equal to 0.9 x resolution
guess.
-rtol2, --resolution-tolerance-2 [VALUE]
Variation allowed in resolution in second pass. Default: 500.
-skyc, --sky-catalogue; -sc, --strong-catalogue; -dc, --deep-catalogue [FILENAME]
The files containing the line catalogues to be used for the removal of sky lines,
the estimation of velocity and resolution, and the full line fitting. The default
catalogues are stored in /usr/share/alfa . If you wish to create your own
catalogue, the required format is that each line should be 85 characters wide, with
a wavelength in the first column, and the rest of the characters are not used by
the code but are transferred to the output files. They can thus be used, as in the
supplied catalogues, for line transition data. To use the default catalogues but
exclude some lines, the --exclude-line option can be used.
-ss, --subtract-sky
Fit and subtract night sky emission lines before fitting nebular emission lines.
-ul, --upper-limits
Write out upper limits for all lines searched for and not detected. The upper limit
is calculated as the detection limit (default 3, set by --detection-limit)
multiplied by the uncertainty. In FITS output, this option is ignored - all upper
limits are written out, and are indicated by negative flux values. If the FITS file
is later anaysed with neat, these negative values are simply ignored.
-vg, --velocity-guess [VALUE]
Initial guess for the velocity of the object [km/s]. Default: 0.
-vtol1, --velocity-tolerance-1 [VALUE]
Variation allowed in velocity in first pass of the fitting. Default: 900km/s
-vtol2, --velocity-tolerance-2 [VALUE]
Variation allowed in velocity in second pass of the fitting. Default: 60km/s
-wc, --wavelength-column [INTEGER]
When reading FITS tables, this option can be used to specify in which table column
the wavelength values are. For any other file type it will have no effect. Default:
1
-ws, --wavelength-scaling [VALUE]
alfa checks the units of FITS file headers to set the wavelength scale, defaulting
to assuming Angstroms if no keyword is present. If your input spectrum is not in
Angstroms, use this option to set the value by which wavelengths should be
multiplied to convert them to A. For example, -ws 10.0 would apply if your spectra
have wavelengths in nm.
ALGORITHM
alfa works in three stages. First, it estimates and subtracts the continuum. Second, it
estimates the resolution of the spectra and the velocity of the object. And third, it
fits the emission lines. These stages work as follows:
Continuum subtraction
alfa estimates the continuum using a percentile filter, taking the 25th percentile
in a moving window 101 pixels wide. Currently these values are hard-coded, but
will be user-configurable in a future release. Regions such as the Balmer and
Paschen jumps may be poorly fitted by this method if the spectral resolution is low
and the continuum gradient is changing fast. Broad stellar emission lines and
telluric absorption features may also not be well fitted by this method.
Inspection of the fitted continuum is recommended.
Estimation of the resolution and velocity
If no relevant command line options are specified, alfa begins by assuming that the
velocity of the object is zero, and that the spectrum is Nyquist-sampled. It then
carries out a fit on a subset of strong lines, using the genetic algorithm
described below, to obtain an overall estimate for the velocity and the resolution.
If necessary, the initial guesses can be specified with the -vg and -rg options
described above, and the parameter space for the fine tuning can be specified with
-vtol1 and -rtol1.
Fitting of the emission lines
With the continuum subtracted and the resolution and velocity estimated, alfa
divides the spectrum up into chunks 440 pixels wide, with 20 pixels at either end
overlapping with adjacent chunks. Then the genetic algorithm fits all lines from
the deep catalogue that fall within the central 400 pixels, with the overlap
regions providing the full line profile for lines close to the edge of the chunk.
The initial guess for the resolution and velocity are taken from the global
estimate for the first chunk, and from the preceding chunk's fine tuned value for
all succeeding chunks.
With the parameters optimised in each chunk, uncertainties are estimated using the
root mean square of the residuals in a 20 pixel window, exlucing the two largest
residuals to mitigate against overestimated uncertainties in the neighbourhood of
bad pixels or strong lines.
INPUT FILES
alfa can read either plain text files or FITS format files. For plain text, the file
should contain a wavelength and a flux, with the wavelength in the same units as the line
catalogues (the default catalogues have wavelengths in Angstroms). FITS files are read
using the CFITSIO library, so any FITS-compliant file should be fine. However, a
surprisingly large fraction of all FITS files do not comply with the standard, so in case
of problems, trying using fitsverify to check your FITS file.
The FITS file can have one, two or three dimensions. If it has two, it is assumed to be
in Row-Stacked Spectra (RSS) format, while if it has three, it is assumed to be a data
cube with two axes representing spatial dimensions and the third representing the spectral
dimension.
If you don't want to fit the whole dataset, you can specify the range of pixels on each
axis that you want alfa to read in by appending the filename with
[startx:endx,starty:endy]. This functionality is part of the CFITSIO library, and the
format is described at
https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node97.html. alfa itself does
not read in the coordinates of the section, and so the output file numbering starts from 1
on each axis regardless of where the image section actually started. The next release of
alfa will have improved support for image sections.
OUTPUT FILES
alfa can produce output in plain text, csv, latex or FITS format. FITS is the default and
recommended format; in future releases, output formats other than FITS will be deprecated
and eventually removed.
When producing plain text, csv or latex output, alfa will produce two files, a fit file
and a line list file. When producing FITS format, a single file is created, with three
extensions, for the fit, the linelist, and a third extension containing the Hbeta flux,
number of lines detected, the radial velocity and average resolution over the spectrum.
Output filenames are based on the input filename, with the extensions noted below.
The fit file (_fit.txt, _fit.csv, _fit.tex) or extension (.fits):
The fit file contains the best fitting synthesised spectrum. It contains seven
columns, representing the wavelength, the input spectrum, the fitted spectrum, the
original after continuum subtraction, the estimated continuum, the fluxes of sky
lines, and the residuals. Thus, to see the fitted spectrum, you need to plot
columns 1 and 3 of this file. In gnuplot, one can compare the input and fitted
spectra using this command:
plot 'filename_fit' w l, 'filename_fit' using 1:3 w l
The lines file (_lines.txt, _lines.csv, _lines.tex) or extension (.fits):
This file contains four columns with parameters of the fitted lines - the observed
wavelength, the rest wavelength, the flux, and the uncertainty estimated from the
residuals. This file can be read directly by neat, which determines abundances for
photoionised nebulae. If latex format is requested, the file additionally contains
atomic data details not currently available in the other formats.
For RSS files and data cubes, alfa currently produces output for each pixel. Thus,
for a large data cube you may end up with tens of thousands of files in the output
directory. A routine to combine these outputs into image maps will be provided in a
future release of alfa.
USAGE NOTES
alfa's default parameters are supposed to work in most cases, but sometimes you might find
that it does not converge on the correct wavelength solution. It searches initially for
velocities in the range +/-900km/s, which is very large for Galactic objects. So, running
the code with --resolution-tolerance-1 100. or so may improve your results.
The genetic parameters (population size, number of generations, pressure) are likely to be
suitable for most cases. There is no algorithm yet known for optimising these parameters
in a genetic algorithm, so changing them requires trial and error. In spectra of regions
with lots of emission lines, such as 4000-4500 Angstrom, increasing the number of
generations can result in a better fit.
Error codes
If alfa encounters an error it will return one of the following status codes:
100 incomplete or invalid command line option
101 input file does not exist
102 output directory does not exist
103 error opening FITS file
104 no axes found in input file
105 too many axes found in input file
106 error reading FITS keywords
107 error writing FITS output
108 no line catalogue file specified
109 line catalogue not found
200 all fluxes below baddata limit
201 no known emission lines in wavelength range
202 failed to estimate velocity and resolution - no lines found
SEE ALSO
neat
BUGS
If reporting a bug, please state which version of alfa you were using, and include input
and any output files produced if possible.
AUTHOR
Roger Wesson