
--------------------------------
Getting Started with NebulaBayes
--------------------------------


About NebulaBayes
-----------------
NebulaBayes is a package for astronomers that aims to provide a very general
way to compare observed emission line fluxes to model predictions, in order to
constrain physical parameters such as the nebular metallicity.

NebulaBayes is provided with two photoionization model grids produced using the
MAPPINGS 5.1 model.  One grid is a 3D HII-region grid which may be used to
constrain the oxygen abundance (12 + log O/H), ionisation parameter (log U) and
gas pressure (log P/k).  The other grid is for AGN narrow-line regions (NLRs)
and has 4 dimensions, with the added parameter "log E_peak" being a measure of
the hardness of the ionising continuum.  NebulaBayes accepts model grids in a
simple table format, and is agnostic to the number of dimensions in the grid,
the parameter names, and the emission line names.

The NebulaBayes.NB_Model class is the entry point for performing Bayesian
parameter estimation.  The class is initialised with a chosen model grid, at
which point the model flux grids are loaded, interpolated, and stored.  The
NB_Model instance may then be called one or more times to run Bayesian
parameter estimation using observed fluxes.  Many outputs are available,
including tables and figures, and all results and working are stored on the
object returned when the NB_Model instance is called.

The documentation assumes some knowledge of Bayesian statistics and scientific
python (numpy, matplotlib and pandas).

NebulaBayes is heavily based on IZI (Blanc+ 2015).

If you use NebulaBayes, please cite
http://adsabs.harvard.edu/abs/2018ApJ...856...89T
\bibitem[Thomas et al.(2018)]{2018ApJ...856...89T} Thomas, A.~D., Dopita, M.~A.,
Kewley, L.~J., et al.\ 2018, \apj, 856, 89


Starting out
------------
Here are some general notes and suggestions for starting out with NebulaBayes:
 -  NebulaBayes compares a set of observed line fluxes from a single spectrum
    to a grid of models (e.g. photoionization models).  The assumptions used in
    the models should be compatible with the observations.  E.g. Emission line
    diagnostics might be used to ensure that e.g. a HII region spectrum is
    being compared to a HII model grid.
 -  Configure the inputs using the example scripts in this directory and the
    documentation, with a uniform prior at first.
 -  Manually inspect the initial NebulaBayes results (tables and plots) to see
    if they are reasonable.  Are parameter estimates physical, and if they're
    at the edge of the parameter space is this plausible?  What's the shape of
    the posterior?
 -  The question "Is there a good fit to the data anywhere in the parameter
    space?" cannot be answered by the calculated parameter estimates or plots
    of the posterior PDF.  Inspect the "best model" table to see if observed
    emission line fluxes are well fit, and which fluxes are inconsistent with
    the "best" model.
 -  It may be helpful to iterate to gain a sense of how different choices
    affect the results, for example by choosing a different set of emission
    lines, a  different line for normalisation, or a different systematic grid
    error.
 -  Once the results are reasonable, consider using a non-uniform prior.  There
    might be particular diagnostic line ratios that could help constrain the
    posterior further.  Is it necessary to depend heavily on a prior to
    constrain the parameter space?
 -  NebulaBayes may be easily used on a large number of spectra once the
    various NebulaBayes settings and results for test spectra are satisfactory.


Resources
---------
The following additional resources are available to learn about running
Nebulabayes and the available options:
 1. The 1_Example-basic.py script in this directory
 2. The 2_Example-advanced.py script in this directory
 3. The documentation available in the code, especially the detailed docstrings
    in NebulaBayes/NB0_Main.py.  This documentation may be explored
    interactively in the ipython terminal in various ways by typing:
        >>> from NebulaBayes import NB_Model
        >>> NB_Model?  # Shows class and __init__ docstrings
        >>> help(NB_Model)  # Similar; also shows __call__ docstring
        >>> NB_model.__init__?
        >>> NB_model.__call__?
        >>> NB_Model??  # Shows source for entire class
    The docstrings describe the input arguments and outputs in detail,
    including descriptions of the objects returned programmatically.
 4. The descriptions of theory and implementation in the NebulaBayes paper,
    Thomas+2018, ApJ, 856, 89



Adam D. Thomas
Research School of Astronomy and Astrophysics
Australian National University
adam.thomas AT anu.edu.au
2015 - 2017
