man(1)

🌸 NAME 🌸

okay so bestie, you're reading man(1), and the icon of this page is neat — which stands for nebular empirical analysis tool. yes that's the whole name. it's giving acronym excellence. 💖

---

✨ SYNOPSIS ✨

neat [option1] [value1] ...

like. that's it. that's the summoning ritual. 🪄

---

🦋 DESCRIPTION 🦋

so neat does a whole comprehensive empirical analysis on a list of nebular emission line fluxes. like, you hand it your lines, it hands you science. 🫶

if you need uncertainties, it gets them for you via a Monte Carlo approach. very demure, very statistical. 🎲

and here's the philosophy, which honestly? iconic. neat believes abundance determinations should be as objective as possible, so user input should be minimised. you can make a bunch of choices if you want, but the default options should yield meaningful results — so if you just run it and chill, you're probably fine. no cap. 👑

---

💅 OPTIONS 💅

• -c [VALUE] — the logarithmic extinction at H beta. by default this gets calculated from the Balmer line ratios, so you don't have to do anything unless you really want to. ✨
• -cf, --configuration-file [FILE] — since version 2.0, NEAT's analysis scheme lives in a configuration file that's read in at run time, instead of being hard coded like some kind of feral gremlin. if you skip this option, the default configuration file is used, which is meant to be suitable for any line list and should only really need changing if you need particular lines excluded from the analysis. the config file holds a series of weights applied when calculating diagnostics and abundances, and the format of the default file should be clear enough that editing it is straightforward. here's the tea on weights: a negative value for a weight means the line is weighted by its observed intensity; a positive value means the line is weighted by the given value. any weights not specified in FILE take their values from the default configuration file. 🎀
• --citation — prints out the bibliographic details of the paper to cite if you use neat in your research. cite your sources bestie, it's the law. 📚
• -e, --extinction-law [VALUE] — the extinction law to use for dereddening. pick your fighter:
  • How — Galactic law of Howarth (1983, MNRAS, 203, 301)
  • CCM — Galactic law of Cardelli, Clayton, Mathis (1989, ApJ, 345, 245)
  • Fitz — Galactic law of Fitzpatrick & Massa (1990, ApJS, 72, 163)
  • LMC — LMC law of Howarth (1983, MNRAS, 203, 301)
  • SMC — SMC law of Prevot et al. (984, A&A, 132, 389)

Default: How

• -he, --helium-data [VALUE] — the atomic data to use for He I abundances. your options:
  • S96 — Smits, 1996, MNRAS, 278, 683
  • P12 — Porter et al., 2012, MNRAS, 425, 28

Default: P12

• -i, --input [FILENAME] — the line list to be analysed. neat can read plain text files with two, three or four columns of numbers. full details of the input format are down in the "methodology" section below, so keep scrolling. 👀
• -icf, --ionisation-correction-scheme [VALUE] — the ICF scheme used to correct for unseen ions. the lineup:
  • KB94 — Kingsburgh & Barlow (1994, MNRAS, 271, 257)
  • PT92 — Peimbert, Torres-Peimbert & Ruiz (1992, RMxAA, 24, 155)
  • DI14 — Delgado-Inglada, Morisset & Stasinska (2014, MNRAS, 440, 536)
  • DI14mod — DI14, but using the classical ICF for nitrogen (N/O=N+/O+)

Default: DI14. also heads up: the KB94 ICF implemented in neat additionally contains a correction for chlorine, from Liu et al., 2000, MNRAS, 312, 585. bonus content fr. 🧪

• -id, --identify — this option triggers an algorithm that tries to convert observed wavelengths into rest wavelengths. if the option isn't there, neat just assumes your input line list already has rest wavelengths sitting in the first column. 🕵️
• -idc, --identify-confirm — same energy as --identify but it doesn't stop for user confirmation. super useful when you're reanalysing a line list where you already ran --identify and were happy with the result. no need to re-litigate it. 💅
• -n, --n-iterations [VALUE] — number of iterations. Default: 1
• -nelow, -nemed, -nehigh, -telow, -temed, -tehigh [VALUE] — by default, electron densities and temperatures get calculated from the available diagnostics, but you can override their values with these commands if you're feeling bossy. required units are cm-3 for densities and K for temperatures. 🌡️
• -rp — so when calculating Monte Carlo uncertainties, neat's default behaviour is to assume all uncertainties are Gaussian. if you specify -rp, it'll compensate for the upward bias affecting weak lines described by Rola and Pelat (1994), assuming log normal probability distributions for weaker lines. fun lore drop: until version 1.8, the default behaviour was the opposite — log normal probability distributions were assumed unless -norp was specified. this got changed after the discovery that the effect described by Rola and Pelat only occurred under extremely specific conditions: see Wesson et al. 2016 for details. character development arc. 😭
• -sr, --subtract-recombination — the recombination contribution to some important diagnostic collisionally excited lines is always calculated but, by default, is not subtracted. this option causes the subtraction to actually be carried out. ⚠️ note that the code takes roughly twice as long to run if this is enabled, because the temperature and abundance calculations need to be repeated following the subtraction. worth it? you decide.
• -u, --uncertainties — calculate uncertainties, using 10,000 iterations. and listen: if this option is specified, the -n option will be ignored. she said what she said. 🔥
• -v, --verbosity [VALUE] — how much output gets written for each derived quantity. this option has no effect unless -n or -u is specified, so don't be surprised if nothing happens.
  • 1 — write out summary files, binned results and complete results
  • 2 — write out summary files and binned results
  • 3 — write out summary files only

Default: 3

---

💜 USING NEAT 💜

🌈 Input file format 🌈

neat requires a plain text file containing a list of emission line fluxes as input. the file can contain two, three or four columns:

• two columns → the code assumes they're the laboratory wavelength of the line (λ0) and its flux (F)
• three columns → assumed to be λ0, F, and the uncertainty on F (ΔF)
• four columns → assumed to be the observed wavelength of the line, λobs, λ0, F, and ΔF

the rest wavelengths should correspond exactly to those listed in the file /usr/share/neat/complete_line_list. the flux column can use any units, and the uncertainty on the flux should be given in the same units. examples live in the /usr/share/neat/examples/ directory if you need inspo. 🍓

🌸 Rest wavelengths 🌸

neat identifies lines by comparing the quoted wavelength to its list of rest wavelengths. but here's the thing — rest wavelengths of lines can differ by up to a few tenths of an Angstrom depending on the source. so making sure neat is identifying your lines properly is probably the most important step in using the code, and misidentifications are the first thing to suspect if you get unexpected results. 🚨

to help with preparing the line list, the command line option -id can be used. it applies a very simple algorithm to the input line list to determine their rest wavelengths, which works like this:

1. A reference list of 10 rest wavelengths of common bright emission lines is compared to the wavelengths of the 20 brightest lines in the observed spectrum.
2. Close matches are identified and the mean offset between observed and rest wavelengths is calculated.
3. The shift is applied, and then an RMS scatter between shifted and rest wavelengths is calculated.
4. This RMS scatter is then used as a tolerance to assign line IDs based on close coincidences between shifted observed wavelengths and the full catalogue of rest wavelengths listed in utilities/complete_line_list

the routine is not intended to provide 100% accuracy, and you should always check very carefully whether the lines are properly identified — particularly in the case of high resolution spectra. she's helpful, not omniscient. 🙈

🦋 Line blends 🦋

in low resolution spectra, lines of comparable intensity may be blended into a single feature. you can flag these with an asterisk instead of a flux in the input line list.

currently, neat has only limited capabilities for dealing with blends: lines marked as blends are not used in any abundance calculations, and apart from a few cases, it assumes all other line fluxes represent unblended or deblended intensities.

the exceptions are some collisionally excited lines which are frequently blended, such as the [O II] lines at 3727/3729Å. in these cases the blended flux can be given with the mean wavelength of the blend, and the code will treat it properly. these instances are indicated in the utilities/complete_line_list file by a "b" after the ion name. ✨

🎀 Uncertainties 🎀

the uncertainty column of the input file is of crucial importance if you want to estimate uncertainties on the results you derive. points to bear in mind:

• the more realistic your estimate of the line flux measurement uncertainties, the more realistic the estimate of the uncertainties on the results will be
• in all cases, the final reported uncertainties are a lower limit to the actual uncertainty on the results, because they account only for the propagation of the statistical errors on the line fluxes and not on sources of systematic uncertainty

in some cases you may not need or wish to propagate uncertainties. in that case you can run just one iteration of the code, and the uncertainty values are ignored if present. lowkey freeing. 💆

🚀 RUNNING THE CODE 🚀

Okay bestie, so you've got your line list all prepped like we talked about, and now it's time to actually run this thing. And because the whole vibe of neat is "simple and objective as possible", this is gonna be super straightforward. To use the code in its simplest form on one of the example linelists, you'd type:

% cp /usr/share/neat/examples/ngc6543_3cols.dat .
% neat -i ngc6543_3cols.dat

This runs a single iteration of the code, and no, it is not propagating uncertainties. You'll see some logging output in your terminal, and the calculated results will be written to the file ngc6543_3cols.dat_results. If that's all you need, then job done, go write that paper. 💅

But your results will be enhanced greatly if you can estimate the uncertainty associated with them. To do that, invoke the code like this:

% neat -i ngc6543_3cols.dat -u

The -u switch makes the code run 10,000 times. In each iteration, the line flux is drawn from a normal distribution with a mean of the quoted flux and a standard deviation of the quoted uncertainty. By repeating this randomisation process lots of times, you build up a realistic picture of the uncertainties associated with the derived quantities. The more iterations you run, the more accurate the results; 10,000 is a sensible number to achieve well sampled probability distributions. If you want a different number of iterations for any reason, you can use the -n command line option to specify your preferred value. ✨

If the -rp option is specified, then for lines with a signal to noise ratio of less than 6, the line flux is drawn from a log-normal distribution which becomes more skewed the lower the signal to noise ratio is. This corrects the low SNR lines for the upward bias in their measurement described by Rola & Pelat (1994). The full procedure is described in Wesson et al. (2012). However, use of this option is no longer recommended as the bias is highly dependent on the fitting procedure — see Wesson et al. (2016).

⚠️ Heads up: -rp is giving "don't do it" energy these days. It's not recommended anymore, fr fr.

🚨 Error codes 🚨

If the code does not complete the analysis, it will return one of the following exit codes:

• 100 — no input file specified
• 101 — input file does not exist
• 102 — config file does not exist
• 103 — invalid number of iterations
• 104 — invalid output format requested
• 105 — could not read input line list
• 106 — could not read LINES extension in FITS input
• 107 — error reading line list from FITS
• 108 — error creating FITS output
• 109 — invalid configuration file
• 200 — invalid temperature or density
• 201 — no Hbeta found
• 202 — unknown ion
• 203 — line identifications rejected

In the case of a FITS handling error, it will also return the CFITSIO exit code.

🔬 METHODOLOGY 🔬

🌈 Extinction correction 🌈

The code corrects for interstellar reddening using the ratios of the Hα, Hβ, Hγ and Hδ lines. Intrinsic ratios of the lines are first calculated assuming a temperature of 10,000K and a density of 1000cm-3. The line list is then dereddened, and temperatures and densities are then calculated as described below. The temperatures and densities are then used to recalculate the intrinsic Balmer line ratios, and the original line list is then dereddened using this value.

🌡️ Temperatures and densities 🌡️

neat determines temperatures, densities and abundances by dividing emission lines into low (ionisation potential <20eV), medium (20eV<IP<45eV) and high excitation (IP>45eV) lines. In each zone, the diagnostics are calculated as follows:

1. A temperature of 10000K is initially assumed, and the density is then calculated from the line ratios relevant to the zone.
2. The temperature is then calculated from the temperature diagnostic line ratios, using the derived density.
3. The density is recalculated using the appropriately weighted average of the temperature diagnostics.
4. The temperature is recalculated using this density.

This iterative procedure is carried out successively for low-, medium- and high-ionization zones, and in each case if no diagnostics are available, the temperature and/or density will be taken to be that derived for the previous zone. Temperatures and densities for each zone can also be specified on the command line with the -telow, -temed, -tehigh and -nelow, -nemed, -nehigh options.

neat also calculates a number of diagnostics from recombination line diagnostics. These are:

1. The Balmer jump temperature is calculated using equation 3 of Liu et al. (2001)
2. The Paschen jump temperature is calculated using equation 7 of Fang et al. (2011)
3. A density is derived from the Balmer and Paschen decrements if any lines from H10-H25 or P10-P25 are observed. Their ratios relative to Hβ are compared to theoretical ratios from Storey & Hummer (1995), and a density for each line calculated by linear interpolation. The final density is calculated as the weighted average of all the densities.
4. Temperatures are estimated from helium line ratios, using equations derived from fits to tabulated values of 5876/4471 and 6678/4471. The tables are calculated at ne=5000cm-3 only. We plan to improve this calculation in future releases.
5. OII recombination line ratios are used to derive a temperature and density, using atomic data calculations from Storey et al. (2017). Values are found by linearly interpolating the logarithmic values.
6. Recombination line contributions to CELs of N+, O+ and O2+ are estimated using equations 1-3 of Liu et al. (2000).

These recombination line diagnostics are not used in abundance calculations. By default, the recombination contribution to CELs is reported but not subtracted. The command line option --subtract-recombination can be used if the subtraction is required — this requires an additional loop within the code which makes it run roughly half as fast as when the subtraction is not carried out.

🧪 Ionic abundances 🧪

Ionic abundances are calculated from collisionally excited lines (CELs) using the temperature and density appropriate to their ionization potential. Where several lines from a given ion are present, the ionic abundance adopted is a weighted average of the abundances from each ion.

Recombination lines (RLs) are also used to derive ionic abundances for helium and heavier elements. The method by which the helium abundance is determined depends on the atomic data set being used; neat includes atomic data from Smits (1996) and from Porter et al. (2012, 2013). The Smits data is given for seven temperatures between 312.5K and 20000K, and for densities of 1e2, 1e4 and 1e6 cm-3; we fitted fourth order polynomials to the coefficient for each line at each density. neat then calculates the emissivities for each density using these equations, and interpolates logarithmically to the correct density.

For the Porter et al. data, the emissivities are tabulated between 5000 and 25000K, and for densities up to 1e14cm-3. neat interpolates logarithmically in temperature and density between the tabulated values to determine the appropriate emissivity.

In deep spectra, many more RLs may be available than CELs. The code calculates the ionic abundance from each individual RL intensity using the atomic data listed in Table 1 of Wesson et al. (2012). Then, to determine the ionic abundance to adopt, it first derives an ionic abundance for each individual multiplet from the multiplet’s co-added intensity, and then averages the abundances derived for each multiplet to obtain the ionic abundance used in subsequent calculations.

The weakness of recombination lines means that care must be taken in deriving abundances from them. neat applies some simple checks to the N2+/H+ and O2+/H+ abundances it derives to see if they are reliable: they will be flagged as unreliable in the _results file if any of the following apply:

1. only one multiplet is detected
2. the highest abundance calculated for a multiplet exceeds the lowest by a factor greater than 3.0
3. (O2+ only) no lines are detected from either the V1 or V10 multiplets

If either abundance is flagged as unreliable, an abundance discrepancy factor for the relevant ion and element is not calculated. Weights may be set to exclude any unreliable multiplets so that a reliable abundance and ADF can be calculated.

🌟 Total abundances 🌟

Total elemental abundances are estimated using the ionisation correction scheme selected from Kingsburgh and Barlow (1994), Peimbert, Torres-Peimbert and Ruiz (1992), or Delgado-Inglada et al. (2014). Total oxygen abundances estimated from several strong line methods are also reported.

Where ionic or total abundances are available from both collisionally excited lines and recombination lines, the code calculates the measured discrepancy between the two values.

✨ OUTPUTS ✨

Okay bestie, so when the code runs, it yells stuff at your terminal — logging messages, so you can see which iteration it's on and whether anything went 💀. Starting from version 2.3, outputs are created in FITS format by default. And here's the cute part: if your input file was already in FITS format (as generated by v2.0 or later of alfa), then the results of the analysis get written to the same file — it updates the LINES extension and creates a RESULTS extension. But if your input was plain text, then a brand-new FITS file is created, in the same directory as the input file. fv is a convenient way to view the tables. 🫶

If plain text output is requested, then the results are written to a summary file and a linelist file, and the paths to both are indicated in the terminal output. The summary file lists the results of the calculations of extinction, temperatures, densities, ionic and total abundances. Two linelist files get written — one is a plain text file listing observed and rest wavelengths, ionic identifications, observed and dereddened fluxes, and ionic abundances for each line used in the abundance calculations. The other is latex-formatted, intended to be usable with minimal further editing in a publication. Iconic, honestly. ✨

In the case of a single iteration, these files are the only output. But if you've run multiple iterations, you can also use the -v option to tell the code to create additional results files for each quantity calculated:

• -v 1 tells the code to write out, for each quantity, all the individual results and a binned probability distribution file
• -v 2 — only the binned distributions are written out
• -v 3 — the default — no additional results files are created

🚨 Plain text output is deprecated, and will be removed in a future release. Consider this your soft launch warning, bestie.

---

🌸 Normality test 🌸

The code now applies a simple test to the probability distributions to determine whether they are well described by a normal, log-normal or exp-normal distribution. The test applied is that the code calculates the mean and standard deviation of the measured values, their logarithm and their exponent, and calculates in each case the fraction of values lying within 1, 2 and 3σ of the mean. If the fractions are close to the expected values of 68.3%, 95.5% and 99.7%, then the relevant distribution is considered to apply. In these cases, the summary file contains the calculated mean and reports the standard deviation as the 1σ uncertainty. 💅

If the file is not well described by a normal-type distribution, then the code reports the median of the distribution and takes the values at 15.9% and 84.1% of the distribution as the lower and upper limits.

---

🔍 Inspecting the output 🔍

It is often useful to directly inspect the probability distributions. In the utilities directory there is a small shell script, utilities/plot.sh, which will plot the histogram of results together with a bar showing the value and its uncertainty as derived above. It will create PNG graphics files for easy inspection. 🎀

The script requires that you ran the code with -v 1 or -v 2, and that you have gnuplot installed. It takes one optional parameter, the prefix of the files generated by neat. So, for example, if you've run 10,000 iterations on examples/ngc6543_3cols.dat, then there will now be roughly 150 files in the example directory, with names like examples/ngc6543_3cols.dat_mean_cHb, examples/ngc6543_3cols.dat_Oii_abund_CEL, etc. You can then generate plots of the probability distributions for the results by typing:

% /usr/share/neat/utilities/plot.sh ngc6453.dat

Running the code without the optional parameter will generate plots for all files with names ending in "binned" in the working directory. 🦋

---

👀 SEE ALSO 👀

alfa, equib06, mocassin

---

💀 BUGS 💀

No known bugs. If reporting a bug, please state which version of neat you were using, and include input and any output files produced if possible.

---

👑 AUTHORS 👑

Roger Wesson, Dave Stock, Peter Scicluna

---

And that's the whole page, bestie — this lil masterpiece is version 2.1, dated 5 June 2016, and it ate, no cap. Go run something beautiful with it. 💖✨