Superbol

Python program to calculate a bolometric luminosity from a set of input magnitudes, which can be apparent mags or absolute mags.

Requirements and usage:

• numpy
• scipy
• matplotlib
• (astropy)

To run code:

python superbol.py

• superbol.py (Python 3 version, preferred)
• superbol-py2.py (Python 2 version WILL NOT BE MAINTAINED AFTER v1.8)

Maintenance and updates will prioritise python 3 version, but python 2 version also appears to work.

Versions

Version 2.2 : Prompt user for initial guess in temperature and radius for the first epoch. Subsequent epochs use T/R from previous step as the initial guess
Version 2.1 : Allow limit to MJDs to slice up light curve after plotting. Also duplicate Gaia G == E in case computer can't differentiate _g.txt and _G.txt (MN)
Version 2.0 : Implement Nicholl+ 2017 / Yan+ 2018 BB absorption function in UV for SED fits, removes need to fit UV/optical separately (MN)
Version 1.12: Fix bug in default answers to absolute/apparent mags - thanks to Aysha Aamer for catching (MN)
Version 1.11: Add NEOWISE bands (MN)
Version 1.10: If no overlap in temporal coverage with reference band, extrapolate to nearest epoch for colour (MN)
Version 1.9 : Add w band (MN)
Version 1.8 : Fix bug in suppression integral - thanks Sebastian Gomez (MN)
Version 1.7 : Fix bug introduced in 1.6 where extinction/Swift corrections not always applied (MN)
Version 1.6 : Save interpolations before applying other corrections (MN)
Version 1.5 : Add prompt to convert Swift AB to Vega (MN)
Version 1.4 : Narrow date range for finding max of polynomial fit to peak (MN)
Version 1.3 : Minor tweaks to output plots (MN)
Version 1.2 : Add extinction correction as an option (MN)
Version 1.1 : Add bibliographic reference, output file now includes K-correction info (MN)
Version 1.0 : Release version, Nicholl 2018 RNAAS (MN)
Version 0.17: Fix bug to write nans instead of blanks when BB fit fails
Version 0.16: Correct inconsistency in x axis labels, automatically exit if <2 filters used
Version 0.15: Plot temperature and radius, other small figure adjustments (MN)
Version 0.14: Fixed bug where having two reference epochs the same broke manual interpolation (MN)
Version 0.13: Give user control over whether to fit UV separately, improve commenting and output files, change min integration wavelength to 100A (MN)
Version 0.12: Change UV suppression to power law (lambda/lambda_max)^x following Nicholl, Guillochon & Berger 2017 (MN)
Version 0.11: Added ATLAS c and o filters (MN)
Version 0.10: Added Gaia G filter. Automatically sort wavelength array when calculating Luminosity. Updated constants in bbody. Added option to change cosmologies with astropy. (SG)
Version 0.9 : Only do separate UV fit if > 2 UV filters (MN)
Version 0.8 : New feature! Can choose to shift SED to rest-frame for data with no K-correction (MN)
Version 0.7 : Improved handling of errors (MN)
Version 0.6 : Tidied up separate blackbody integrations in UV/NIR (MN)
Version 0.5 : Specifying files on command line now COMMA separated to handle 2-digit indices (MN)
Version 0.4 : Fixed bug in blackbody formula - missing factor of pi led to overestimate of radius (MN)
Version 0.3 : Added GALEX NUV and FUV bands in AB system (MN)
Version 0.2 : Swift effective wavelengths now match Poole et al 2008 (update by MN)
Version 0.1 : Origin and veracity of all zeropoints checked by SJS. Comments added, with more details in superbol.man file. Archived this version in /home/sne/soft
Version 0   : Written by Matt Nicholl (QUB), 2015
(note: pre-release version numbers have been downgraded from 1.x->0.x from .14 onwards)

Usage

The program does not do extinction corrections or K-corrections from spectra. K-correction not strictly required, if user chooses to shift SED to rest-frame before integration. Extinction corrections should be applied before use (for now).

Should run in directory with photometry data. User prompted at all steps (goal: no prior knowledge of superbol required to use it!)

The user is prompted for the input files, which should be called SNname_filters.txt, e.g.

PTF12dam_ugriz.txt, LSQ14bdq_JHK.dat

Multiple files per transient are allowed, with different filters included in each. The format of files must be:

MJD filter1 err1 filter2 err2...

MJD can be replaced by phase or some other time parameter, but must be consistent between files.

• Important: Bands must be in their common systems: AB mag for ugrizy, Gaia, ATLAS, GALEX; Vega mags for UBVRIJHK, Swift (S=UVW2 D=UVM2 A=UVW1) and NEOWISE (W=W1 Q=W2)
• Important : Order of filter magnitudes in file must match order of filters in filename.

Computes pseudobolometric light curves by integrating flux over observed filters only ("Lobs") as well as full bolometric light curves with blackbody extrapolations ("Lbb"). BB fit parameters (temperature and radius) are also saved as output. Optical and UV can be fit separately to mimic line blanketing.

The user will be prompted for redshift or distance modulus to allow calculation of the luminosity. If a redshift is entered then a standard cosmology is employed to determine distance modulus. Default cosmology module has been updated to use astropy, but Ned Wright's cosmocalc is also available (just uncomment that section in code)

If some filters only have a few epochs, code implements a choice of interpolation/extrapolation based on either constant colours or interactve polynomial fitting. All interpolated light curves are saved as output. On subsequent runs, code will detect presence of interpolated light curves so you can choose to skip interpolation stage. Output of each run of the code will contain all the filters used in the integration in the filenames

Steps:

• Find files associated with SN and determine available filters and data
• Correct for time dilation, distance, and approximate K-correction if desired
• Map light curves in each filter to a common set of times (typically defined by the filter with most observations)
  • Interpolation options: linear between neighbouring epochs or polynomial fits (user determines order of polynomial interactively)
  • Extrapolation: using polynomials or assuming constant colour with respect to reference filter. Large extrapolations = large uncertainties!
  • Save interpolated light curves for reproducability
• Fit blackbodies to SED at each epoch (most SNe can be reasonably approximated by blackbody above ~3000 Angstroms). In UV, user can choose to:
  • use a simple prescription for line blanketing at UV wavelengths, defined as L_uv(lambda < cutoff) = L_bb(lambda)*(lambda/cutoff)^x, where x is chosen by user. User can choose cutoff wavelength and suppression index (Nicholl+ 2017, Yan+ 2018)
• Numerically integrate observed SEDs, and account for missing UV and NIR flux using blackbody extrapolations. NIR is easy, UV uses options described above

Outputs

• interpolated_lcs_<SN>_<filters>.txt
  • multicolour light curves mapped to common times.
  • Footer gives methods of interpolation and extrapolation.
  • If file exists, can be read in future to skip interpolating next time.
• bol_<SN>_<filters>.txt
  • main output.
  • Contains pseudobolometric light curve, integrated trapezoidally, and bolometric light curve including the additional BB corrections, and errors on each.
  • Footer gives filters and method of UV fitting.
• logL_obs_<SN>_<filters>.txt
  • same pseudobolometric (observed) light curve, in convenient log form
• logL_obs_<SN>_<filters>.txt
  • light curve with the BB corrections, in convenient log form
• BB_params_<SN>_<filters>.txt
  • fit parameters for blackbodies: T, R and inferred L from Stefan-Boltzmann law (can compare with direct integration method).

Recommended practice: run once with ALL available filters, and fit missing data as best you can. Then re-run choosing only the well-observed filters for the integration. You can compare results and decide for yourself whether you have more belief in the "integrate all filters with light curve extrpolations" method or the "integrate only the well-sampled filters and account for missing flux with blackbodies" method.

To-do:
    - set error floor for interpolation to ref band error
    - make compatible with other inputs (Open Supernova Catalog, output from psf.py)

Notes on various filter systems (courtesy Stephen Smartt)

AB system flux zeropoints (used for SDSS-like filters)

It is worth noting the origin of these numbers for clarifation and to avoid confusion and use of incorrect zeropoints From the definition of AB magnitudes

 m(AB) = -2.5 log(f_nu) - 48.60.

Therefore, AB magnitudes are directly related to a physical flux. They are defined as monocrhomatic fluxes. Bandpasses need to be defined at an effective wavelength

f_nu is recovered from the above in units of ergs/s/cm2/Hz such that m(AB) = 0 has a flux of f_nu = 3.63E-20 erg/s/cm2/Hz = 3631 Jy 1 Jy = 1 Jansky = 10E-26 W Hz-1 m-2 = 10-23 erg s-1 Hz-1 cm-2 Working through the conversion to ergs/s/cm2/Angs (and making sure all units are respected) f_lam = 0.1089/(lambda_eff^2) where lambda_eff is the effective wavelength of the filter in angstroms. Note then that the AB flux zeropoint is defined ONLY by the choice of effective wavelength of the bandpass

These effective wavelengths for SDSS filters are from Fukugita et al. (1996, AJ, 111, 1748) and are the wavelength weighted averages (effective wavelenghts in their Table 2a, first row)

Then then lead to the following fluxes for the SDSS filters (in 10^-11 erg/s/cm2/Angs) for the zeropoints of the system (i.e. for m_AB =