alfa(1)

Bestie, this is the alfa(1) man page 💖, the manual for alfa, so let's get into it 🌸

✨ NAME ✨

alfa - automated line fitting algorithm 🦋

💅 SYNOPSIS 💅

alfa [OPTION] [VALUE]... [FILE]

🌈 DESCRIPTION 🌈

okay so alfa rapidly fits emission line spectra ✨, and it's giving genetic algorithm energy because it uses one to optimise the fitting parameters 🧬. It's meant to be totally automated 🫶, but even though the defaults slay in lots of situations, getting a good fit to your observed spectrum might need a few tweaks to the input parameters 💅. It's optimised for optical spectra, but it can be applied to any wavelength range too, as long as you give it a suitable line catalogue 🌸.

alfa reads one dimensional spectra in either plain text or FITS format 📖. Plain text input should have 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 every value in a spectrum is below the number you give, alfa won't fit it 🙈. Most useful for not wasting time on low signal regions of data cubes 💀.
• --citation — Prints the bibliographic details of the paper to cite if you use alfa in your research 📚.
• -cl, --clobber — By default alfa refuses to overwrite any pre-existing output file 🚫. Specify this option and it'll overwrite the output file instead 💥.
• --collapse — Sums all spectra in multi-dimensional FITS files into one single spectrum ➕. Spectra whose peak value is below any value you give with the --bad-data option get 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 the representative continuum level 📊. This option sets the size of that 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 before it counts as a detection 🔍. Default: 3.0
• -el, --exclude-line [REAL] — When reading in the line catalogues, any wavelengths you give with this option get ignored 🙅‍♀️. For example, if H alpha were saturated, you could exclude it from the fit with --exclude-line 6562.77 🌟. You can exclude as many lines as you want by repeating the option with the wavelengths you need 🔁.
• -fc, --flux-column [INTEGER] — When reading FITS tables, this option picks which table column holds the flux values 🪄. For any other file type it does nothing. Default: 2
• -g, --generations [INTEGER] — The number of generations used in the genetic algorithm 🧬. Default: 500
• -n, --normalise [VALUE] — Normalises to Hb=100, assuming that F(Hb)=VALUE 💫. If VALUE is zero, no normalisation happens 🙃. If you don't specify this option, fluxes get normalised using the measured value of Hb if it was detected, and left unnormalised otherwise 🤷‍♀️.
• -nc, --no-continuum — If the spectrum you're fitting is already continuum subtracted, set this option to skip alfa's continuum fitting ⏭️.
• -o, --output-dir [DIRECTORY] — The directory where the output files go 📁. Default: current working directory.
• -of, --output-format [VALUE] — The format of the output files 🎨. Valid values are text, csv, fits, latex. If you're using alfa alongside 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] — Rebins the input spectrum by the factor you specify 🧱. Super useful for high resolution spectra where the line profiles are kinematic rather than instrumental 🌈. This option is currently only implemented for 1d spectra 🚧.
• -rg, --resolution-guess [VALUE] — Your 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] — How much variation in resolution is allowed in the first pass 🎢. Default: equal to 0.9 x resolution guess.
• -rtol2, --resolution-tolerance-2 [VALUE] — How much variation in resolution is allowed in the second pass 🎢. Default: 500.
• -skyc, --sky-catalogue; -sc, --strong-catalogue; -dc, --deep-catalogue [FILENAME] — These point to the line catalogues used for removing sky lines, estimating velocity and resolution, and the full line fitting 📜. The default catalogues live in /usr/share/alfa 🏡. Want your own catalogue? Each line needs to be 85 characters wide, with a wavelength in the first column 📏. alfa doesn't use the rest of the characters, but they get transferred to the output files, so, like in the supplied catalogues, you can use them for line transition data 💅. To use the default catalogues but skip some lines, use the --exclude-line option 🙌.
• -ss, --subtract-sky — Fits and subtracts night sky emission lines before fitting the nebular emission lines 🌌.
• -ul, --upper-limits — Writes out upper limits for every line searched for and not detected 🔻. The upper limit is the detection limit (default 3, set by --detection-limit) multiplied by the uncertainty 🧮. With FITS output this option gets ignored, since all upper limits are written out anyway and marked with negative flux values ⚠️. If the FITS file is later analysed with neat, those negative values are simply ignored 🫧.
• -vg, --velocity-guess [VALUE] — Your initial guess for the velocity of the object [km/s] 🚀. Default: 0.
• -vtol1, --velocity-tolerance-1 [VALUE] — How much variation in velocity is allowed in the first pass of the fitting 🌀. Default: 900km/s
• -vtol2, --velocity-tolerance-2 [VALUE] — How much variation in velocity is allowed in the second pass of the fitting 🌀. Default: 60km/s
• -wc, --wavelength-column [INTEGER] — When reading FITS tables, this option picks which table column holds the wavelength values 🌟. For any other file type it does nothing. Default: 1
• -ws, --wavelength-scaling [VALUE] — alfa checks the units in FITS file headers to set the wavelength scale, and assumes Angstroms if there's no keyword 📐. If your input spectrum isn't in Angstroms, use this option to set the value that wavelengths get multiplied by to convert them to A 🔁. For example, -ws 10.0 would apply if your spectra have wavelengths in nm 🍭.

---

part 2 picks up with ALGORITHM next 🦋

📁 INPUT FILES 📁

okay so alfa can read two kinds of files, bestie: plain text files or FITS format files 💖 For plain text, the file needs a wavelength and a flux, and the wavelength has to be in the same units as the line catalogues (the default catalogues use Angstroms ✨). FITS files get read through the CFITSIO library, so any FITS-compliant file should be fine... but ngl, a surprisingly large fraction of FITS files don't follow the standard 💀 So if things go wrong, try using fitsverify to check your file 🙈

The FITS file can have one, two or three dimensions. Two dimensions means it's treated as Row-Stacked Spectra (RSS) format 🌸 Three dimensions means it's treated as a data cube, with two axes for spatial dimensions and a third axis for the spectral dimension 🦋

If you don't want to fit the whole dataset, you can choose the range of pixels on each axis by appending the filename with [startx:endx,starty:endy] 🎀 This is a CFITSIO feature, and the format is described at https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node97.html. Lowkey important: alfa doesn't read the section coordinates itself, so the output file numbering starts from 1 on each axis no matter where the image section actually started 🙃 The next release of alfa will have improved support for image sections 👑

---

💾 OUTPUT FILES 💾

alfa can spit out plain text, csv, latex or FITS format 🧚 FITS is the default and the recommended one ✨ In future releases, output formats other than FITS will be deprecated and eventually removed, so FITS is the main character era 💅

When you go with plain text, csv or latex, alfa makes two files: a fit file and a line list file. With FITS you get a single file with three extensions. One is for the fit, one is for the linelist, and the third holds the Hbeta flux, number of lines detected, the radial velocity and the average resolution over the spectrum 🌈 Output filenames are based on the input filename, with the extensions below 🫶

The fit file (_fit.txt, _fit.csv, _fit.tex) or extension (.fits)

The fit file holds the best fitting synthesised spectrum 💜 It has seven columns: wavelength, input spectrum, fitted spectrum, original after continuum subtraction, estimated continuum, fluxes of sky lines, and residuals. So to see the fitted spectrum, you need to plot columns 1 and 3 🦋 In gnuplot, you can compare the input and fitted spectra with 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 has four columns with the parameters of the fitted lines: observed wavelength, rest wavelength, flux, and the uncertainty estimated from the residuals 🔥 neat can read this file directly, and neat is the one that determines abundances for photoionised nebulae 🌌 If you request latex format, the file also includes atomic data details that aren't available in the other formats yet 📚

For RSS files and data cubes, alfa currently makes output for each pixel 😭 So for a large data cube, you could end up with tens of thousands of files in your output directory 💀 A routine to combine these outputs into image maps is coming in a future release of alfa 🎀

---

🧠 USAGE NOTES 🧠

alfa's default parameters are supposed to work in most cases, but sometimes it won't converge on the correct wavelength solution 😤 It starts by searching for velocities in the range +/-900km/s, which is huge for Galactic objects. So running the code with --resolution-tolerance-1 100 or so might improve your results 💖

The genetic parameters (population size, number of generations, pressure) are likely to be suitable for most cases. There's no algorithm known yet for optimising these parameters in a genetic algorithm, so changing them is pure 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 runs into an error, it will return one of these 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 you're reporting a bug, please say which version of alfa you were using, and include the input and any output files produced if possible 🙏

---

👩‍💻 AUTHOR 👩‍💻

Roger Wesson 🌸

---

And that's the whole page, bestie! 💖 Version 1.0 from 26 Aug 2016, slaying the man page game forever 💅🎀✨