notebooks/NICMOS/nicmos_unit_conversion/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": [
    "## Imports\n",
    "- All the examples require `astropy.units`. See `Units` and `Quantities` in Astropy for more information.\n",
    "- Some examples require the package `snyphot`.\n",
    "- Some examples require the `math` library. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from astropy import units as u\n",
    "\n",
    "from synphot import SourceSpectrum\n",
    "from synphot import units as syn_u\n",
    "from synphot.models import BlackBodyNorm1D\n",
    "\n",
    "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": null,
   "metadata": {},
   "outputs": [],
   "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": null,
   "metadata": {
    "collapsed": true
   },
   "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": null,
   "metadata": {
    "collapsed": true
   },
   "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": null,
   "metadata": {
    "collapsed": true
   },
   "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": null,
   "metadata": {},
   "outputs": [],
   "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": null,
   "metadata": {
    "collapsed": true
   },
   "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": null,
   "metadata": {
    "collapsed": true
   },
   "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": null,
   "metadata": {
    "collapsed": true
   },
   "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": null,
   "metadata": {},
   "outputs": [],
   "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}