zap Documentation Release 1.0.dev86 Kurt Soto February 03, 2016
Contents 1 Installation 3 1.1 Requirements............................................... 3 1.2 Steps................................................... 3 2 Examples 5 2.1 Sparse Field Case............................................ 5 2.2 Filled Field Case............................................. 6 3 Extra Functions 7 4 Command Line Interface 9 5 Interactive mode 11 i
ii
zap Documentation, Release 1.0.dev86 ZAP (the Zurich Atmosphere Purge) is a high precision sky subtraction tool which can be used as complete sky subtraction solution, or as an enhancement to previously sky-subtracted data. The method uses PCA to isolate the residual sky subtraction features and remove them from the observed datacube. Though the operation of ZAP is not dependent on perfect flatfielding of the data in a MUSE exposure, better results are obtained when these corrections are made ahead of time. Contents 1
zap Documentation, Release 1.0.dev86 2 Contents
CHAPTER 1 Installation 1.1 Requirements ZAP requires the following packages: Numpy 1.6.0 or later Astropy v1.0 or later SciPy v0.13.3 or later Many linear algebra operations are performed in ZAP, so it can be beneficial to use an alternative BLAS package. In the Anaconda distribution, the default BLAS comes with Numpy linked to OpenBlas, which can amount to a 20% speedup of ZAP. 1.2 Steps Once the code is downloaded, cd into the zap directory and install via:: python setup.py install 3
zap Documentation, Release 1.0.dev86 4 Chapter 1. Installation
CHAPTER 2 Examples In its most hands-off form, ZAP can take an input fits datacube, operate on it, and output a final fits datacube: import zap zap.process('input.fits', outcubefits='output.fits') Care should be taken, however, since this case assumes a sparse field, and better results can be obtained by applying masks. The main function is zap.process: There are a number of options that can be passed to the code which we describe here: The code can handle datacubes trimmed in wavelength space. Since the code uses the correlation of segments of the emission line spectrum, it is best to trim the cube at specific wavelengths. The cube can include any connected subset of these segments. (for example 6400-8200 Angstroms) [0, 5400] [5400, 5850] [5850, 6440] [6440, 6750] [6750, 7200] [7200, 7700] [7700, 8265] [8265, 8602] [8602, 8731] [8731, 9275] [9275, 10000] 2.1 Sparse Field Case This case specifically refers to the case where the sky can be measured in the sky frame itself, using: zap.process('input.fits', outcubefits='output.fits') In both cases, the code will create a resulting processed datacube named DATACUBE_ZAP.fits and an SVD file named ZAP_SVD.fits in the current directory. While this can work well in the case of very faint sources, masks can improve the results. For the sparse field case, a mask file can be included, which is a 2d fits image matching the spatial dimensions of the input datacube. Masks are defined to be >= 1 on astronomical sources and 0 at the position of the sky. Set this parameter with the mask keyword 5
zap Documentation, Release 1.0.dev86 zap.process('input.fits', outcubefits='output.fits', mask='mask.fits') 2.2 Filled Field Case This approach also can address the saturated field case and is robust in the case of strong emission lines, in this case the input is an offset sky observation. To achieve this, we calculate the SVD on an external sky frame using the function zap.svdoutput An example of running the code in this way is as follows: zap.svdoutput('offset_field_cube.fits', svdfn='zap_svd.fits', mask='mask.fits') zap.process('source_cube.fits', outcubefits='output.fits', extsvd='zap_svd.fits', cfwidthsp=50) The integration time of this frame does not need to be the same as the object exposure, but rather just a 2-3 minute exposure. Often residuals can be further reduced by changing cfwidthsp to a smaller value. However, this parameter should not be reduced to smaller than 15 pixels. 6 Chapter 2. Examples
CHAPTER 3 Extra Functions Aside from the main process, three functions are included that can be run outside of the entire zap process to facilitate some investigations. 7
zap Documentation, Release 1.0.dev86 8 Chapter 3. Extra Functions
CHAPTER 4 Command Line Interface ZAP can also be used from the command line: python -m zap INPUT_CUBE.fits More information use of the command line interface can be found with the command python -m zap -h 9
zap Documentation, Release 1.0.dev86 10 Chapter 4. Command Line Interface
CHAPTER 5 Interactive mode ZAP can also be used interactively from within IPython import zap zobj = zap.process('input.fits', interactive=true) The run method operates on the datacube, and retains all of the data and methods necessary to process a final data cube in a python class named zclass. You can elect to investigate the data product via the zclass, and even reprocess the cube with a different number of eigenspectra per region. A workflow may go as follows: import zap from matplotlib import pyplot as plt # allow ZAP to run the optimize routine zobj = zap.process('input.fits', optimization='normal', interactive=true) # plot the variance curves and the selection of the number of eigenspectra used zobj.plotvarcurve(5) # plot a spectrum extracted from the original cube plt.figure() plt.plot(zobj.cube[:,50:100,50:100].sum(axis=(1,2)), 'b', alpha=0.3) # plot a spectrum of the cleaned ZAP dataproduct plt.plot(zobj.cleancube[:,50:100,50:100].sum(axis=(1,2)), 'g') # choose just the first 3 spectra for all segmments zobj.reprocess(nevals=3) # plot a spectrum extracted from the original cube plt.plot(zobj.cube[:,50:100,50:100].sum(axis=(1,2)), 'b', alpha=0.3) # plot a spectrum of the cleaned ZAP dataproduct plt.plot(zobj.cleancube[:,50:100,50:100].sum(axis=(1,2))), 'g') # choose some number of modes by hand zobj.reprocess(nevals=[2,5,2,4,6,7,9,8,5]) # plot a spectrum plt.plot(zobj.cleancube[:,50:100,50:100].sum(axis=(1,2))), 'k') # Use the optimization algorithm to identify the best number of modes per segment zobj.optimize() 11
zap Documentation, Release 1.0.dev86 # compare to the previous versions plt.plot(zobj.cleancube[:,50:100,50:100].sum(axis=(1,2))), 'r') # identify a pixel in the dispersion axis that shows a residual feature in the original plt.figure() plt.matshow(zobj.cube[2903,:,:]) # compare this to the zap dataproduct plt.figure() plt.matshow(zobj.cleancube[2903,:,:]) # write the processed cube as a single extension fits zobj.writecube('datacube_zap.fits') # or merge the zap datacube into the original input datacube, replacing the data extension zobj.writefits(outcubefits='datacube_final_zap.fits') 12 Chapter 5. Interactive mode