JWST/NIRSpec-IFU Simulator Pipeline

Written by Simon Zieleniewski

Last Edited: 21-06-16


----------
RELEASE NOTES

 - 01-12-15: MULTICORE PROCESSING NOT CURRENTLY WORKING


----------
PURPOSE:

The JSIM pipeline code is designed to simulate observations using the NIRSpec-IFU mode on the JWST. The pipeline takes a high spectral and spatial resolution input FITS format datacube, and processes it according to the chosen observing parameters. The code returns several output cubes:
 - a mock observed cube (with variance as first extension)
 - a background cube (with variance as first extension) (both noisy and noiseless versions returned)
 - a SNR cube

With further options to return:
 - a background subtracted ("Reduced") cube (with variance as first extension)
 - a transmission cube
 - an object cube giving object flux only (both noisy and noiseless versions returned)

This pipeline provides a self contained and consistent way of performing simulations of the performance of NIRSpec-IFU. The mock observed output cubes can be analysed as if they are real observational data.


----------
FILES:

The pipeline currently uses 8 main python files:
jsim.py
JSIM_main.py
JSIM_Specres.py
JSIM_Background.py
JSIM_Transmission.py
JSIM_Loop.py
JSIM_Lowres.py
JSIM_Config.py

as well as several functions found in the src/modules/ sub directory.

There are also several data files found in Sim_data subdirectory.


----------
DEPENDENCIES:

The following Python modules are essential to run the pipeline:
numpy - http://www.scipy.org/scipylib/download.html
scipy - http://www.scipy.org/scipylib/download.html
astropy - http://www.astropy.org/

JSIM requires the JWST PSF generation Python module: WebbPSF
This can be found at: http://pythonhosted.org/webbpsf/installation.html
WebbPSF itself requires the following (extra modules):
 - matplotlib - http://matplotlib.org/users/installing.html
 - POPPY - https://pypi.python.org/pypi/poppy


The following are strongly recommended for optimum running:
wxPython - This is used to load the GUI. It can be downloaded from: http://www.wxpython.org/download.php
pprocess - This is used to allow parallel processing to improve performance. Download from https://pypi.python.org/pypi/pprocess


Make sure the modules can by found by your Python implementation. E.g. in a Python environment try:
>>> import webbpsf
>>> import numpy
>>> import astropy
>>> import scipy
>>> import wx
>>> import pprocess

there should be no errors!


----------
DIRECTORY SETUP:

The root directory contains several sub directories containing essential data files:

./src - main python functions stored here
     /modules - additional python functions stored here
./Output_cubes - output cubes are stored here
./Sim_data - Simulation data is stored here
	  /Background
	  /Throughput
	  /Prism


----------
HOW TO USE:

The code can be run in two ways:

1. Running the GUI:
$ python jsim.py
This opens the graphical interface from which you can enter the various parameters and start the simulation.

2. From the command line:
$ python jsim.py -c arg1 arg2 arg3 etc…

Use:
$ python jsim.py -c
to display arguments list

The commands must be entered in the following order:
            1. datacube: Input datacube filepath
            2. DIT: Exposure time [s]
            3. NDIT: No. of exposures
            4. grating: [F070-G140M, F100-G140M, G235M, G395M, F070-G140H, F100-G140H, G235H, G395H, Prism]
            5. Ignore LSF convolution? (True/False) - turnes off LSF convolution in spectral dimension
            6. PSF blur: Additional telescope PSF blur [mas]
            7. Spec_Nyquist: (True/False) - Set spectral sampling to Nyquist sample spectral resolution element
            8. Spec samp: Spectral sampling [A/pix] - Only used if Spec_Nyquist=False, but enter a value regardless!
            9. Noise force seed: Force random number seed to take a set value (0=No, 1-10=yes and takes that value)
            10. Remove background: (True/False) - Subtract background spectrum
            11. Return object cube: (True/False) - Return object FITS cube
            12. Return transmission cube: (True/False) - Return transmission FITS cube
            13. Approximate Drizzle technique: (True/False) - Output sampling of 50 mas

Use -h or --help to display help message and exit
Use -c or --cline option to use command line.
Use -o or --odir when using command line to specify output file directory. Default is /jsim/Output_cubes/
Use -p or --proc when using command line to specify number of cores for parallel processing. Default is N_PROC-1 (if N_PROC>1)

An example command line entry:
$ python jsim.py -c -p 5 -o /Path/to/output_dir/ /Path/to/Input_cubes/Input_cube.fits 100 1000 F100-G140M True 0.0 True 1.0 0 True True True False


----------
INPUT CUBES:

The pipeline takes an input FITS file datacube containing spatial and spectral information about the astrophysical source of interest. The format should be an (x,y,lambda) datacube with each pixel containing the value of flux per sq. arcsec (e.g. J/s/m^2/A/arcsec^2).

The following FITS headers are essential:

NAXIS1, NAXIS2, NAXIS3 - Size of the x, y, and wavelength axes respectively.
CTYPE1, CTYPE2, CTYPE3 - Axis type. Accepted values: [x, y, WAVELENGTH] or [RA, DEC, WAVELENGTH].
CUNIT1, CUNIT2, CUNIT3 - Units for each axis. Accepted values: [mas, mas, microns], [mas, mas, angstroms], [mas, mas, metres], [mas, mas, nm].
CDELT1, CDELT2, CDELT3 - Sampling for each axis in units given by CUNIT1/2/3 headers.
CRVAL3 - Value of array element given by CRPIX3 in units of CUNIT3.
CRPIX3 - Denotes the array element for CRVAL3. Should be set to 1 so CRVAL3 denotes first wavelength value.
FUNITS - Flux units for each element in datacube. Accepted values: [J/s/m2/um/arcsec2], [J/s/m2/A/arcsec2], [erg/s/cm2/um/arcsec2], [erg/s/cm2/A/arcsec2].
SPECRES - Spectral resolution FWHM in units of CUNIT3.

All other headers will be ignored by the pipeline so extra information can be added.

N.B, please make sure all header keys do not have white space in them! The FITS handling modules used break down when they find header keys with spaces in. Please use underscores instead.