PyNeb: a new tool for analyzing emission lines. I. Code description and validation of results

Valentina Luridiana; Christophe Morisset; Richard A. Shaw

Source-linked AI summary

PyNeb: a new tool for analyzing emission lines. I. Code description and validation of results

Valentina Luridiana, Christophe Morisset, Richard A. Shaw

arXiv:1410.6662v2Oct 24, 2014astro-ph.IMastro-ph.SR

TL;DR

Emission-line analysis requires numerical treatment and adaptable atomic data as observations and atomic calculations grow more complex. PyNeb addresses this with a customizable Python toolbox that computes nebular conditions and abundances, and the paper reports practical adoption, visualization capabilities, and validation against NEBULAR. Its scope excludes photoionization modeling, energy-balance issues, and fluorescence.

Problem
Emission-line analysis requires numerical solutions and depends on atomic data whose approximations and continual improvements complicate reliable, scalable analysis.
Method
PyNeb combines n-level equilibrium calculations for collisional lines, emissivity-table interpolation for recombination lines, diagnostic tools, abundance calculations, visualization, and customizable atomic data.
Results
PyNeb provides print-quality and tailored plots, insight into emissivity properties through emissivity grids, and has been used in numerous published papers.
Takeaways & Limitations
PyNeb is a public, extensible toolbox for direct nebular analysis whose intermediate calculations and graphical outputs can be adapted to particular scientific objectives.
Takeaways & Limitations
PyNeb cannot account for fluorescence or energy-balance issues and is not a photoionization code for finite-depth, complex physical models.

Abstract

from arXiv · show

Analysis of emission lines in gaseous nebulae yields direct measures of physical conditions and chemical abundances and is the cornerstone of nebular astrophysics. Although the physical problem is conceptually simple, its practical complexity can be overwhelming since the amount of data to be analyzed steadily increases; furthermore, results depend crucially on the input atomic data, whose determination also improves each year. To address these challenges we created PyNeb, an innovative code for analyzing emission lines. PyNeb computes physical conditions and ionic and elemental abundances, and produces both theoretical and observational diagnostic plots. It is designed to be portable, modular, and largely customizable in aspects such as the atomic data used, the format of the observational data to be analyzed, and the graphical output. It gives full access to the intermediate quantities of the calculation, making it possible to write scripts tailored to the specific type of analysis one wants to carry out. In the case of collisionally excited lines, PyNeb works by solving the equilibrium equations for an n-level atom; in the case of recombination lines, it works by interpolation in emissivity tables. The code offers a choice of extinction laws and ionization correction factors, which can be complemented by user-provided recipes. It is entirely written in the python programming language and uses standard python libraries. It is fully vectorized, making it apt for analyzing huge amounts of data. The code is stable and has been benchmarked against IRAF/NEBULAR. It is public, fully documented, and has already been satisfactorily used in a number of published papers.

1. Introduction

PyNeb was developed to make increasingly data-intensive emission-line analysis adaptable to improving atomic data. It modernizes earlier tools while adding extensibility, visualization, and access to intermediate calculations.

Motivation: Emission-line spectra provide physical conditions and chemical abundances, but numerical methods are required because the governing equations cannot be solved analytically.The calculations also depend on atomic data that are approximate and continually improving.
Context: PyNeb is a new Python package for analyzing emission-line spectra in ionized nebulae, extending a lineage that includes FIVEL and NEBULAR.NEBULAR extended FIVEL with abundance, diagnostic, dereddening, and externally updateable atomic-data functionality.
Design goals: Python recasting exposes internal functionality through APIs and supports richer visualization, GUI and web interfaces, and easier extension by developers and advanced users.These goals motivated replacing the earlier NEBULAR implementation.
Contributions: PyNeb adds analysis and visualization features while exposing intermediate quantities so users can write scripts tailored to specific analyses.This extends the functionality inherited from NEBULAR.
Paper scope: The paper overviews PyNeb’s physics, functionality, validation against NEBULAR, software requirements, documentation, and future expansion.It describes version 1.0.1.

2. Underlying physics

PyNeb models nebular emission through distinct recombination and collisional processes. It solves level populations and uses diagnostic ratios and abundance corrections to infer physical conditions and abundances.

Line formation: Hydrogen and helium lines mainly arise from recombination cascades, whereas strong metal lines mainly arise from collisional excitation followed by radiative de-excitation.In both cases, line emissivity is proportional to upper-level population times transition probability.
Collisional lines: Collisional metal ions can be represented as n-level systems because collisions predominantly populate only their lowest levels.The approximation follows from higher levels being progressively less efficiently excited.
Collisional lines: PyNeb derives collisional excitation and de-excitation rates from effective collision strengths and solves coupled equilibrium equations for relative level populations at specified electron density and temperature.Most ions use five or six levels, while the database spans two to 34 levels.
Diagnostics: Ratios of lines from the same ion cancel total abundance, allowing observed intensity ratios to determine electron density or temperature when the other quantity is known.This applies when the ions are cospatial.
Abundances: Ionic abundances are computed relative to H+, while elemental abundances require summing observed ions and correcting for unseen ions with ionization correction factors.ICFs depend on ionization-structure knowledge and are often specific to object classes such as planetary nebulae or H ii regions.

3. Overview of the code

PyNeb is a modular toolbox for direct nebular analysis and visualization, organized around classes representing atoms, observations, diagnostics, and ionization corrections. Its structure supports varied workflows and customization.

Core functionality: PyNeb solves emissivities, derives electron temperature and density from diagnostic ratios, and computes ionic and total abundances under simplifying assumptions.It supports many elements typically observed in gaseous nebulae.
Customization: The code is designed for users to update atomic data, extend classes, build analysis scripts, and develop new software or interfaces.This includes users with modest scientific-programming and Python experience.
Class structure: Atom and RecAtom represent ion models, Observation represents observed emission lines, Diagnostics represents diagnostic ratios, and ICF represents ionization correction factors.Ancillary classes support additional workflows, including stellar calculations.
Workflows: The class methods support workflows ranging from simple diagnostics and atomic-data visualization to complete abundance analyses.Example scripts provide worked demonstrations and can be run from the command line or imported into Python.
Class structure: Figure 1 schematically links PyNeb’s classes with output quantities, showing class names, arguments, and methods in an abridged illustrative structure.The figure is intended as an overview rather than a complete description.

3.2. The model collisional atom: The Atom class

The Atom class encapsulates collisional-ion data and the machinery needed to calculate populations, emissivities, abundances, and physical conditions. Its accessible internal properties support inspection and customized analysis.

Atom representation: An Atom object stores atomic transition probabilities and effective collision strengths loaded from the database for a selected ion.The object represents the physical atom relevant to collisional-line calculations.
Calculations: The Atom class solves population equations, calculates emissivities and ionic abundances, and computes other standard quantities.These operations use the equations described for collisional atoms.
Atomic data: Changing atomic-data sets can change both the number of modeled levels and the resulting calculations for an ion.The number of levels is therefore data-dependent rather than intrinsic to the ion.
Access and inspection: PyNeb exposes atomic properties through the Atom object, including populations, critical densities, level energies, transition probabilities, collision strengths, and Grotrian diagrams.Users can retrieve and explore these properties with standard Python commands.
Diagnostics: Atom.getTemDen determines an electronic temperature from a specified line ratio and electron density.The example solves for the temperature corresponding to [O iii] λ4363/λ5007 = 0.01 at Ne = 1000 cm^-3.

3.3. Atoms emitting recombination lines: the RecAtom class

The RecAtom class computes recombination-line emissivities through interpolation in tables or fitting functions, while keeping recombination and collisional spectra as distinct objects.

RecAtom functionality: RecAtom computes recombination-line emissivities by interpolating tables or using a fitting function.The H i recombination spectrum is instantiated through the RecAtom class.
RecAtom functionality: Recombination atoms share many features and syntax with collisional atoms.Their methods provide recombination counterparts to analogous Atom methods.
Related abundance tools: Table 2 lists the ionization correction factors included in PyNeb version 1.0.1.The table documents available ICFs rather than RecAtom emissivity calculations.
Object separation: PyNeb requires separate Atom and RecAtom objects when both collisional and recombination spectra of the same ion are needed.Atom('O', 2) describes [O ii], whereas RecAtom('O', 2) describes O ii recombination lines.

3.4. Determining ionic and total abundances with PyNeb

PyNeb organizes abundance and diagnostic analysis through Atom, Diagnostics, and related classes, supporting ionic abundances, total abundances, and simultaneous temperature-density solutions.

Ionic abundances: Known physical conditions allow PyNeb to derive an ion’s ionic abundance relative to H+ from observed line intensities.This calculation is implemented by the Atom method getIonAbundance.
Total abundances: PyNeb computes total abundances using ionization-correction-factor formalism.Version 1.0.1 includes a large inventory of published ICFs and supports customized expressions through addICF.
Diagnostic organization: The Diagnostics class stores multiple diagnostic ratios and their associated ions, lines, and error information.User-defined diagnostics may combine lines from the same ion, provided their expressions and rms terms are meaningful.
Diagnostic organization: Version 1.0.1 includes default line ratios, with a '+' suffix marking blended lines.These defaults are listed in Table 3.
Physical-condition diagnostics: getCrossTemDen simultaneously determines electron temperature and density by fitting two line ratios.It iteratively calls getTemDen within a multisection procedure until the requested precision is reached.

3.6. Emissivities as a function of temperature and density: EmisGrid

The EmisGrid class precomputes emission-line emissivity grids over temperature and density, enabling PyNeb calculations and visual diagnostic displays.

Grid construction: EmisGrid produces a stack of emissivity grids for the selected atom as functions of temperature and density.Each layer corresponds to one emission line in the atom.
Grid construction: PyNeb uses precomputed EmisGrid data for many of its tasks.The grids cover selected temperature and density ranges.
Visualization: EmisGrid supports color-coded emissivity maps and contour plots for visualizing the grids.These methods are illustrated for an O iii object in Figs. 2 and 3.

3.7. Managing observational data: the Observation class

The Observation class stores observational line data and supports diagnostic visualization, while interpretation must account for measurement, theoretical, and atomic-data uncertainties.

Data management: Observation objects hold line intensities for one or more objects and may include errors, extinction information, dereddened intensities, and the dereddening law.Observational data are generally read from a file.
Diagnostic visualization: Observation, Diagnostic, and EmisGrid objects jointly support observational diagnostic plots.These plots combine measured data with theoretical emissivity information.
Interpretive limits: When more than two line ratios are available, a unique solution generally does not exist.Analysis should incorporate observational errors and possible causes of discordant diagnostics.
Atomic-data dependence: PyNeb results depend on assumed transition probabilities and collision strengths, whose uncertainties are larger for some complex atoms.Nebular analyses can therefore depend strongly on the selected atomic-data set.
Diagnostic visualization: The O iii EmisGrid example represents emissivities of individual O iii lines across a chosen temperature-density range.Each stack layer corresponds to one line.
Diagnostic visualization: The O iii diagnostic figure maps [O iii] λ4363/λ5007 and contours ratios used for simultaneous temperature-density determination.The contour levels are numbered by the logarithm of the ratio.

4. Code validation

PyNeb reproduces NEBULAR results closely when the same atomic data are used, with only negligible discrepancies in tested populations, emissivities, and diagnostics. The validation also delineates physical problems outside PyNeb’s scope, including fluorescence, radiation transfer, energy balance, and finite-depth modeling.

Validation against NEBULAR: PyNeb predictions coincide with NEBULAR when both adopt the same atomic data.The comparison covers shared quantities such as level populations, critical densities, emissivities, temperatures, densities, and ionic abundances.
Validation against NEBULAR: Differences in [O iii] level populations and derived quantities are negligible and not systematic; PyNeb is slightly more precise on the smallest scales.The reported differences are attributed to differences in computed level populations and likely reflect PyNeb’s greater numerical precision.
Emissivities and diagnostics: 2%: PyNeb’s default Storey & Hummer (1995) Hβ emissivity is roughly 2% lower than the Aller (1984) prediction.Linear interpolation produces visible wiggles in the tabulated emissivity comparison, suggesting that smooth interpolation may be preferable.
Emissivities and diagnostics: Differences in the [O iii] temperature diagnostic are about 10 K when the NEBULAR and PyNeb results are examined closely.On the plotted scale the results are indistinguishable, and comparisons across the listed density and temperature diagnostics likewise find negligible differences.
Diagnostic plots: PyNeb supports essentially the same diagnostic-plot usage as NEBULAR while offering greater flexibility in graphical features.The validation includes density and temperature diagnostic comparisons and a direct plot comparison.
Limitations and caveats: PyNeb is not designed to model fluorescence, radiation transfer, energy balance, dust-driven thermal or ionization effects, or finite-depth complex physical structures.Fluorescence must be corrected explicitly before observed intensities are interpreted, and PyNeb is an emission-line analysis code rather than a photoionization code.

5. Practical details

PyNeb supports both interactive and scripted use, with documentation and examples for learning and repeatable analyses. Its vectorized and parallelized computations target efficient processing of repetitive or large-scale calculations.

Requirements: Python 2.7, NumPy, Matplotlib, and SciPy comprise PyNeb’s required software environment.Python and NumPy are required for core functionality; Matplotlib supports graphics, while SciPy supports selected recombination and stellar-temperature calculations.
Usage: Interactive commands suit quick computations, whereas scripts are better for executing many commands sequentially.Documentation provides examples of both usage modes.
Performance: Vectorized NumPy operations avoid repetitive loops when computing emissivity grids.Atom.getTemDen is also parallelized for multiple processors, further reducing execution time.
Documentation: PyNeb provides a manual, docstrings, reference documentation, commented science scripts, and this paper plus Paper II.The manual is continuously updated, and docstrings generate HTML and PDF reference documents.

6. Concluding remarks: The present and future of PyNeb

PyNeb combines customizable atomic data, visualization, diagnostics, abundance tools, and a modular design for nebular analysis. The code is stable and already used in published studies, while future work targets broader ion coverage, improved blend handling, and uncertainty estimation.

Present functionality: PyNeb supplies atomic-data inventories, visualization tools, diagnostic calculations, abundance methods, recombination intensities, emissivity grids, and modular scripting support.Its built-in ICF collection can also be extended with user-provided formulae.
Present functionality: Full access to intermediate calculations and print-quality graphics enables tailored plots beyond built-in visualization commands.The modular structure also makes PyNeb components easy to embed in scripts.
Future development: Future development includes adding collisional and recombination ions, including s-process elements, O ii, and C ii.These additions are described as potential extensions to the current inventory.
Future development: Blend treatment is incomplete because blended lines can enter diagnostics but not yet getIonAbundance inputs.The authors intend to improve this functionality in the near future.
Future development: A Monte Carlo procedure for estimating abundance errors from flux errors is planned.This is listed as a future addition to the code.
Present status: PyNeb has already been used in a number of published papers, and the scientific community is invited to continue using it.The authors request citation when PyNeb calculations contribute to published work.

Appendix A: Sample scripts

The appendix demonstrates PyNeb through scripts for diagnostic plots and density-inhomogeneity analysis. The examples read and deredden observations, construct diagnostics and emissivity grids, and compare separate regions with their combined, potentially misanalyzed spectrum.

Diagnostic script: The first sample script produces a diagnostic plot similar to Fig. 5 using an observational data file.The script’s data file contains line intensities and an extinction coefficient for SMC_24.
Diagnostic script: The diagnostic workflow defines an Observation, reads line data, applies Cardelli’s extinction law, adds selected line-ratio diagnostics, and builds emission grids.The listed diagnostics include ratios from N, O, S, and Ne ions.
Density-inhomogeneity script: The second script models two subregions with equal temperatures but densities of 3e2 and 5e5, then forms virtual observations for each region and their sum.The subregions are assigned masses of 1 and 5e-4, respectively, and line intensities are computed for the considered ions.
Density-inhomogeneity script: Diagnostic plots are generated separately for both subregions and for the combined region analyzed as homogeneous.Fig. A.2 illustrates the bias resulting from treating a two-density region as homogeneous.