Programmatic Replacements for NICMOS Units Conversion Form

nicmos_unit_conversion.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Programmatic Replacements for NICMOS Units Conversion Form\n",
    "\n",
    "This notebook illustrates programmatic ways to perform unit conversions as provided by [NICMOS Units Conversion Form](http://www.stsci.edu/hst/nicmos/tools/conversion_form.html). The examples here are not exhaustive and will never be. They are meant to give users enough basic knowledge to then calculate what they really want."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All the examples require this import below from `astropy` package. See [Units and Quantities in Astropy](http://docs.astropy.org/en/stable/units/) for more information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from astropy import units as u"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For *some* examples, you might need an extra package called [synphot](https://synphot.readthedocs.io)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from synphot import SourceSpectrum\n",
    "from synphot import units as syn_u\n",
    "from synphot.models import BlackBodyNorm1D"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And for some, you need the `math` library."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 1: Simple Jy to AB mag\n",
    "\n",
    "```\n",
    "INPUT FROM THE FORM IS \n",
    "Input units = Jy             \n",
    "Output units = AB magnitude   \n",
    "Input flux =    1.00000E-13 Jy             \n",
    "Temperature of the blackbody =    5500.00\n",
    "INPUT wavelength =     1.00000 micron\n",
    "OUTPUT wavelength =     1.00000 micron\n",
    "AB magnitude   = 41.43\n",
    "```\n",
    "\n",
    "In plain English, user wants to know what is 1e-13 Jy converted to AB magnitude at 1 micron. Blackbody is not needed for this conversion."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "41.40 mag(AB)\n"
     ]
    }
   ],
   "source": [
    "input_flux_ex1 = 1e-13 * u.Jy\n",
    "input_wave_ex1 = 1 * u.micron\n",
    "abmag_ex1 = input_flux_ex1.to(u.ABmag, u.spectral_density(input_wave_ex1))\n",
    "print('{:.2f}'.format(abmag_ex1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 2: PHOTLAM to FNU for Blackbody\n",
    "\n",
    "```\n",
    "INPUT FROM THE FORM IS \n",
    "Input units = photons/cm2/s/A\n",
    "Output units = erg/cm2/s/Hz   \n",
    "Input flux =    1.00000 photons/cm2/s/A\n",
    "Temperature of the blackbody =    5500.00\n",
    "INPUT wavelength =    0.500000 micron\n",
    "OUTPUT wavelength =    0.600000 micron\n",
    "Flux=4.62E-23 erg/cm2/s/Hz   \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This example is more complicated in that it requires assumption of a blackbody and has different input and output units.\n",
    "\n",
    "First, we create a source spectrum with a blackbody model with the given temperature of 5500 K."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "bb_ex2 = SourceSpectrum(BlackBodyNorm1D, temperature=5500*u.K)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we calculate the normalization factor required for the blackbody to have the given input flux at the given input wavelength."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "input_flux_ex2 = 1 * syn_u.PHOTLAM\n",
    "input_wave_ex2 = 0.5 * u.micron\n",
    "factor_ex2 = input_flux_ex2 / bb_ex2(input_wave_ex2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We apply this factor to our blackbody source."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "input_ex2 = bb_ex2 * factor_ex2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we calculate the desired flux in given output unit and wavelength."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "4.62e-23 FNU\n"
     ]
    }
   ],
   "source": [
    "output_wave_ex2 = 0.6 * u.micron\n",
    "flux_ex2 = input_ex2(output_wave_ex2, flux_unit=syn_u.FNU)\n",
    "print('{:.2e}'.format(flux_ex2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 3: W/m2/Hz to I-mag for Power-Law\n",
    "\n",
    "\n",
    "```\n",
    "INPUT FROM THE FORM IS \n",
    "Input units = W/m2/Hz        \n",
    "Output units = magnitude I    \n",
    "Input flux =    1.00000E-23 W/m2/Hz        \n",
    "Index of the power-law spectrum as a function of frequency =   0.250000\n",
    "INPUT wavelength =     1.00000 micron\n",
    "OUTPUT wavelength =    0.900000 micron\n",
    "I =  0.85\n",
    "```\n",
    "\n",
    "First, we define the input flux and wavelength."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "input_flux_ex3 = 1e-23 * (u.W / (u.m * u.m * u.Hz))\n",
    "input_wave_ex3 = 1 * u.micron"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we define a power-law function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "def powerlaw_ex3(nu):\n",
    "    \"\"\"F(nu)=nu**(spectral index)\n",
    "    \n",
    "    nu is a Quantity.\n",
    "    \"\"\"\n",
    "    spectral_index = 0.25\n",
    "    return (nu.to(u.Hz, u.spectral()) ** spectral_index).value"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use this power-law and a normalization factor based on input flux and wavelength to calculate output flux at output wavelength in input flux unit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "output_wave_ex3 = 0.9 * u.micron\n",
    "flux_ex3 = powerlaw_ex3(output_wave_ex3) * input_flux_ex3 / powerlaw_ex3(input_wave_ex3) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we convert the flux to *I* magnitude, as defined by the converter as:\n",
    "\n",
    "```\n",
    "magnitude I: zero-flux=2250 Jy; central wavelength=0.90 microns;\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.85\n"
     ]
    }
   ],
   "source": [
    "imag_zpt = 2250 * u.Jy\n",
    "i = -2.5 * math.log10(flux_ex3 / imag_zpt)\n",
    "print('{:.2f}'.format(i))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}