Euro 3D Euro3D Visualization Tool User Guide for E3D v1.3.8
Contents
1. 0 RSS image plus 2D plot of the average spectrum 1 RSS image 2 2D plot of all the spectra together 3 RSS image plus 2D plot of all the spectra together and 4 2D plot of the average spectrum simple dar index delta index Determines the empirical DAR correction based on the comparison of the peak position of the interpolated slices maps It requires the spectral index of the slice used as reference and the spectral indeces width of the datacube slices delta index Skysub n spec Subtracts to all the spectra in the cube the stored spectrum number n spec Note This routine is useful to perform an rough sky subtraction 20 E3D v1 3 slicearith n1 operator n2 n3 Performs the arithmetic operation defines by the operator 4 between the slices stored in the buffer n1 and n2 saving the result in the buffer n3 Specarith n1 operator n2 Performs the arithmetic operation defines by the operator between the spectra stored in the buffer n1 and n2 saving the result in the currently in use buffer start server Starts the Shared Memory Server experimental stats spax Performs basic statistics over the fluxes of the currently selected spaxels previously stored using save spectra sel i spax Stop server Stops the Shared Memory Server experimental sub spec n1 n2 Deprecated Subtract the spectrum in the buffer n2 to the spectrum in the buffer n2 saving the result in the currently2. 1 2 Requirements E3D has been coded in C and Tcl Tk It uses the C coded library LCL as I O library This library was developed on propose to handle the input output of data on the Euro3D format 1 It uses PGPLOT as graphical library Therefore as prerequisites it is needed to have installed in your computer both libraries before installing E3D Warning PGPLOT is not a GPL product It is property of Tim Pearson and copyright CalTech Therefore it cannot be distributed However it can be freely downloaded from the webpage http www astro caltech edu tjp pgplot E3D comprises four main elements e The C coded low level functions including the routines calling the Euro3D I O library the SHM routines basic functions needed for plotting and analyzing the data e A number of stand alone C coded tools that help to handle the Euro3D format Perhaps the most interesting routine is any2Euro3D transforming single Group IFS data from any instrument into the Euro3D Format e The tk e3d Tcl Tk interpreter This is a standalone programme that creates its own Tcl Tk interpreter adding Euro3D routines to the standard Tcl ones These routines invoke the C functions included in the C libraries from Tcl and they can be used for different pro poses e g load save Euro3D format files plot single or coadded spectra plot monochro 2 E3D v1 3 matic polychromatic maps interpolate these save maps in FITS format tk_
3. A P contal Rousset Y Copin P Ferruit Document 1 is available at http www aip de Euro3D 1 4 Abbreviations and acronyms AD Applicable Document AIP Astrophysikalisches Institut Postdam DIT Detector Integration Time DQ Data Quality ESO European Southern Observatory E3D Euro3D Visualization Tool FITS Flexible Image Transport System FWHM Full Width at Half Maximum HDU Header and Data Unit IFS Integral Field Spectroscopy IFU Integral Field Unit LCL Lyon C Library MPE Max Planck Institut fiir extraterrestrische Physik NDIT Number of DIT NIR Near Infra Red User Guide NOST PA PSF RD RON RMS RSS SPAXEL S N TBD WCS Nasa Science Office of Standards and Technology Position Angle Point Spread Function Reference Document Read Out Noise Root Mean Square Row Stacked Spectra SPAtial piXture ELement Signal to Noise ratio To Be Determined World Coordinate System 4 E3D v1 3 2 Installation In this section we describe how to install the E3D 2 1 Prerequisites for installation Prior to install the E3D you will need to install the Euro3D I O libraries E3D_io_LCL 1 6 or later distributions The installation procedure is detailed in the Installation Guide of the Euro3D I O libraries 2 You need also to install PGPLOT including the CPS PS GIF VGIF and TK drivers PGPLOT can be downloaded from http www astro caltech edu tjp pgplot Hint You need to have properly define
4. added a simple system to send orders to E3D through the file E3D input e3d It will execute any secuence of tcl tk E3D commands included in this file whatever extend As a simple test execute the following command line with the E3D open echo puts test gt E3D input e3d 22 E3D v1 3 you should have an output on the xterm where you have opened E3D on the form test Once you sent commands to E3D you can recive answers from it just in form of ASCII and FITS files By convention we have defined three different output files for different kind of outputs e E3D output e3d ASCII file It is intended for small outputs both combining numerical and strings information e E3D output_e3d txt ASCII file It is intended for large outputs of numerical data like position tables or slices e E3D output_e3d fits FITS file It is intended for large outputs of numerical data like spectra or maps It is recomended to delete the output file once you have readed it not to allow possible confusions An example of E3D input e3d_ file should looks like cd DIRECTORY load e3d E3D FILENAME euro3d draw raw O 300 1 1 heat 0 7 0 7 1 set data euro3d ask e3d info set fid open E3D output e3d RDWR 0777 puts fid data close fid This script will load an E3D file E3D FILENAME into the E3D plot the row stacked spectra and read the common information of the file and stores it in the standard outputfile E3D o
5. dev id correct dar Correct the data for DAR differential atmospheric refraction A DAR correction should be defined create map ii i2 dpix square 0 1 Creates an interpolated map from the datacube slice defined between the spectral indeces i1 and i2 The size of the interpolated pixel dpix and if the final map is an square or nor not 0 1 are optional values See also set grid create obj Creates an object i e a memory buffer of the currently selected list of spaxels It returns the index of the saved object create slice i1 i2 slice index flag Creates a datacube slice between the spectral indeces i1 and i2 and tries to allocated it in the slice index slice index The flag indicates the kind of slice to be created ie if flag gt 90 it save the slice from the currently in use in other case it creates a new slice See also plot spaxels create spec Save the currently used average spectrum in a memory slot It returns the slot index User Guide 15 e div spec il i2 Deprecated Divide the spectrum stored in the memory slot i1 by the spectrum in the memory slot i2 It returns the memory slot of the result See specarith e draw raw min max device clean palette bright contra sign first spec last spec Draw the spectra contained in the 3D file in its RSS format It requires as parameters the min and max values to plot the device index to plot it the palette brightness bright and contrast contra an inversion paramet
6. e plot flux spax dev id clean Plots the flux of the slice corresponding to the currently in use list of selected spaxels or object along the distance to the first of these spaxels This routine is useful to visualize the flux profile with a pseudo slit selection It requires the id of the PGPLOT device where to plot dev id and a flag indicating if to clean or not this device the next time that we plot on it clean 0 for not to clean plot line dev id colorindex lweight lstyle X points Y points Plots a line defined by the points in the lists X points and Y points in the device dev id with the color defined by the index colorindex the weight lweight and the line style 1style e plot map min max dev id palette bright contra sign n map Plots the map 2D interpolated image of an slice corresponding to the slice in the buffer slot n map in the device dev id with the plotting parameters indicated min max palette bright contra and sign See draw raw e plot scale min max dev id bright contra sign palette units top min top max border Plots an intensity scale on the right size of the device dev id with the indicated plotting parameters min max palette bright contra and sign See draw raw The plotted range will be between the values top min and top max The units can be plotted on top of the scale e plot spaxels min max dev id il i2 palette bright contra sign save fill type new img back color n contours Plots the
7. for the peak in the crosscorrelated image and estimating the DAR from the displacement of this peak through the wavelength Once estimated the DAR correction it is possible to correct the data by clicking on Cor rect DAR This correction displace each datacube slice by the estimated correction spatially interpolating the data using the interpolation configuration Hint You may experience problems with the DAR functions they may take long to complete or hang E3D For data with strong continuum it can work reliably 6 Help This menu contain an item to call up this User s Guide Either XPDF or Acrobat Reader are required to make this work from within E3D The item About E3D gives some short info about this program Warning The E3D GUI is still unfinished and some features may not work as expected 3 2 The spaxel inspector The spaxel inspector allows to visualize the monochromatic polychromatic datacube slices that has been previously selected in the main window or in the spectra inspector see below Figure 3 2 shows an snapshot of this window It comprises a principal image area with 8 small ones a toolbar and a information entry panel The selected slice of the datacube is plotted in the main image area an consecutively in one of each 8 small ones These small image areas are buffers of the last 8 selected slices If more than one slice has been sent to the spaxel inspector is always possible to back to re
8. in use buffer tcl pgptxt x y angle font text size color width Plots the text in the position x and y rotated an angle angle with a font type font and the size size The color of the text is defined by the color index color and the width of the line by width theoretical dar Determines the theoretical DAR correction based on the formulae presented by Filippenko 1995 and the igroup information stored in the Euro3D format zoom raw pixi pix2 dev id Select the wavelength range between the spectral pixels pix1 and pix2 for cutting the row stacked spectra It also wipe out the device dev id Zoom spax dev id x min x max y min y max bordersize aspect Defines the zooming area for map plotting in the device dev id between the values x min x max ymin y_max with a certain bordersize The aspect flag defines whether to mantain the real aspect ratio of the spaxels 1 or not 0 unzoom spax dev id Redefines the zooming area for map plotting in the device dev id to the default values 4 3 Examples of E3D Tcl Tk scripts We list number of simple E3D tcl scripts as examples of the use of the scripting capabilities of E3D All of them have to be executed using tk e3d the E3D interpreter User Guide 21 4 3 1 Extract a single spectrum of an Euro3D cube The following script extracts a single spectrum corresponding to the spaxel number 100 from the Euro3D file e3d_file fits and save it as an ASCII table in the file spectr
9. on the left information panel see the figure The panel on the left size of the GUI includes also information and entries for the current max min values plotted bright and contrast selection bars and the current selected wavelength range It is possible to select both monochromatic or polychromatic cuts or select a range of spaxels on this image area once loaded a file The default selection is the spectral selection allowing to select a wavelength cut by clicking with the left mouse button in one monochromatic or two polychromatic spectral positions on the RSS Once selected a spectral region it is possible to a show a zoomed version of the RSS of this wavelength range by clicking in the Zoom button or and b create a spatial map by an average of the flux over the selected wavelength range per spaxel This map is shown in the spaxel inspector by clicking the right mouse button or clicking on the Plot button on the Spaxel menu Keeping clicked the central mouse button and moving through the image we send different cuts to the spaxel inspector of a spectral pixel width of delta x and initial wavelength corresponding to the position of the mouse This variable has been arbitrary defined to 5 spectral pixel to change it type set delta x NN in the command prompt The type of selection can be changed on the menu see below from the spectral to the spaxel selection This selection allows to select a reduce number of spaxels by clicking on
10. software packages and a lack of any standard have hampered a break through of this powerful observing method leaving it merely as an expert technique with comparatively limited scientific impact Recognizing the importance of this problem a work plan was devised to start creating a package of tools for the analysis and visualization of IFS data Entitled 3D Visualization Task 2 2 of this work plan foresees the development of a programme which should be capable of reading writing and visualizing reduced data from 3D spectrographs of any kind We have named this tool E3D This document describes how to install and use the Euro3D visualization tool E3D One of the major problems for the development of a standard visualization tool is the lack of a stan dard data format Every group has developed its own 3D data format both for the spectral and the position information cubes FITS images FITS tables MIDAS images etc In order to overcome this problem the RTN has proposed a unified data format the Euro3D Data Format 1 6 Taking into account previous experience from more than a decade of operating 3D instrumentation in the visible and the near infrared this data format is supposed to cover most foreseeable require ments of existing and future instruments The Euro3D visualization tool was written specifically to make use of this data format although it can read and write 3D data on another different formats like datacubes
11. spaxel at the spectral index i load_file filename Loads the Euro3D formatted file filename into E3D load_n_spectra_sel Returns the index of the currently loaded memory buffer spectrum load_obj n_obj Loads the object number n_obj into the currently selected list of spaxels load_spec n_spec Loads the spectrum in the buffer slot number n_spec into the current use spectrum load_sepectra_sel n Returns the spaxel identification of the ith element of the currently in use object i e list of selected spaxels mark range dev id colorindex lwidth lstyle text x1 y1 x2 y2 Mark the device dev id with the text in the color defined by the colorindex and a two headed arrow with a line width lwidth and a line style 1style between the positions x1 y2 and x2 y2 message dev id message Writtes the text message in the center of the device dev id nearest spax X Y Returns the spaxel identification of the nearest spaxel to the position X Y open device DEVICE Opens a new PGPLOT DEVICE from the list if allowed devices included in the current PG PLOT installation It returns the device identification for the opened device peak dar index delta index Determines the empirical DAR correction based on the comparison of the position of the peak intensity of the datacube slices It requires the spectral index of the slice used as reference and the spectral indeces width of the datacube slices delta index User Guide 17
12. 2D map created from the average of intensities between the spectral indeces i1 and i2 from the 3D cube in the device dev id with the indicated plotting parameters min max palette bright contra and sign See draw raw E3D includes different representations of the 2D maps that can be selected by selecting dif ferent type values 0 for the spaxels representation keeping the geometry of each element at each group 1 spaxel representation overplotting the outpart of each spaxel 3 spaxel repre sentation overplotting the spaxel Id 4 interpolated reconstructed map using the parameters defined by set grid see below 1 spaxel representation with an overlapped contour plot and 2 contour plot Other options are included new img can be 0 for not plotting a flux scale and a frame border e g when plotting in the GUI or 2 for plotting a flux scale and a frame border e g for generating postscript files When new img is set to 1 the windows settings from a previous plot are used not cleaning the window i e no cpgpage is done This is useful to overplot images from different slices back color defines the PGPLOT color index of the background color n contours defines the number of contours to be plotted by the contour plot fill has no use actually e plot spectra min max dev id clean palette bright contra sign i spax Plots the spectra corresponding to the spaxel indeces included in the i spax list in the device d
13. E 10 0 Gentoo They differ in the names of Tcl Tk libraries normally they are just called libtcl so and libtk so while on SuSE the names include a ver sion number e g libtcl8 4 so and libtk8 4 so If required you might need to edit the file add def makedefs local and select a definition of V3D_LIBS matching the paths of your distri bution or add a new one place a hash character jLin front of the active line and remove it in front of the line matching you distribution User Guide 5 Hint On some 64bit versions of SuSE Linux the libraries might be located in usr 1ib64 or usr X11R6 1ib64 A commented line V3D_LIBS valid for 64bit SuSE was defined in add_def makedefs local for this purpose Uncomment this line if you have such a system If you install PGPLOT you also have to add change these directories in the PGPLOT makefile Hint In case you have unusual paths for include files and libs for example if you installed Tcl Tk in your private directory uncomment and adapt the two lines at the bottom of add def makedefs local which refer to V3D_INC and V3D_LIBS This tells the compiler where to find these files Hint The installation under Solaris requires to edit the file add def makedefs local and un comment the proper definition of V3D_LIBS Before running configure you should copy the file doc makefile sun into pkg v3d source Hint The installation under OSF1 also called Alpha or TruUn
14. Euro 3D Promoting 3D spectroscopy in Europe http www aip de Euro3D Research Training Network Sponsored by the European Commission Euro3D Visualization Tool User Guide for E3D v1 3 8 2011 Original Author S F S nchez Maintained by P M Weilbacher pweilbacher aip de ii This page was intentionally left blank E3D v1 3 User Guide ii Change Record Issue Date Sections affected Remarks 1 0 2003 04 22 all Creation by S F Sanchez 1 1 2003 08 01 External Packages Updated by S F Sanchez 1 2 2003 12 30 all Updated by S F Sanchez 1 2b 2004 04 19 all Updated by S F Sanchez 1 3 5 2005 11 23 all Typos some inconsitencies etc P M Weilbacher 1 3 6 2006 06 21 all Typos MacOSX instructions small updates etc P M Weilbacher 1 9 7 2008 02 06 none Update versions only add hint for PGPLOT add note about DAR 1 3 8 2011 02 14 all typos fixed iv This page was intentionally left blank E3D v1 3 User Guide Contents 1 Introduction 1 1 Purpose and scope e eh s oss 1 2 Requirements a eheu Rue God aU IOLOGLS GO eave SE aoe te mo 1 3 Reference documents s cans manie y aca eee ORG ROG RUE ORDRE OW Ye Ac Pa ae 1 4 Abbreviations and acronyms 4 2 2 22 ll lS oss 2 Installation 2 1 Prerequisites for installation 4 ll ee 2 2 Installing E3D step by step sa r i ce aou ee a e E ee ae 3 The E3D GUI tk e3d tcl 3 1 Themain window a a oa a 2k Pos S04 X od R
15. d the PGPLOT and LCL environment variables E g on a bash shell system export PGPLOT_DIR usr local pgplot export IFU_PATH usr local src or with tcsh setenv PGPLOT DIR usr local pgplot setenv IFU PATH usr local src Be sure to also include these settings in your startup file which are normally bashrc or cshrc for users of bash and tcsh respectively You may also need to add PGPLOT DIR to the LD_LIBRARY_PATH variable 2 2 Installing E3D step by step In the following we describe step by step the procedure to follow to install E3D 1 Download the current stable version of the E3D distribution e g e3d 1 3 8 tar gz The newest version can always be found on http www aip de Euro3D E3D 2 Change to the directory above the location of the LCL library i e cd IFU PATH 3 Extract the tarball using the command tar xvzf e3d 1 3 8 tar gzorgzip dc e3d 1 3 8 tar gz tar xvf add a path before the filename as needed It will be easiest if you execute this in side IFU PATH then it will create the directory e3d 1 3 8 or a corresponding one depending of the version number 4 Change into the new directory cd e3d 1 3 8 and execute configure and make a configure b make Hint The main reason for the make process to fail are different locations and or names of cer tain libraries We have tested the procedure under several Linux distributions RedHat 7 1 and 8 0 and SuSE 8 2 9 3 OpenSuS
16. e single selection or twice multiple selection on the RSS image with the left mouse button The RSS of the selected spaxels is shown in the spectral inspector when clicking the right mouse button or clicking on the Plot button on the Spectra menu Keeping clicked the middle mouse button and moving througt the image we send the spectrum of the spaxel corresponding to the current mouse position of the to the spectral inspector A Command prompt has been included in the window to run tcl and or tc1 E3D routines and scripts by typing in the prompt or in a file that can be run using the source filename routine The menus included in the toolbar are User Guide T 1 File Menu It comprises the different I O options of data files in E3D The Load and a Save buttons allows you to load and save files in the Euro3D format It is possible to import export files in another different formats like data cubes Import Export CUBE and row stacked spec tra fits files Import Export RSS For the RSS format E3D expects two different files a fits file 2D image with a single spectrum per row and an ASCII file for the position table A col lection of E3D position tables for different instruments has been included in the subdirectory data in the E3D directory tree Hint Not all files in row stacked spectra format can be imported directly using the Import RSS menu item For more advanced cases the command line tool any2Euro3D was included The s
17. e3d is the core of E3D Once invoked it runs a Tc1 Tk E3D shell from where both command line commands and scripts can be started plot map tcl included in the scripts subdirectory is an example of the scripts that can be written to be run under tk e3d We will explain below the E3D routines in detail e tk e3d tcl the E3D GUI This is a Tc1 Tk E3D script that creates a graphical user interface for visualizing and analyzing 3D data It includes certain number of procedures that makes it easier to work with 3D data Hint If you intend to visualize analyze 3D data without writing your own scripts then you are mainly interested in tk e3d tc1 the E3D GUI You can skip the other chapters of this document 1 3 Reference documents 1 Euro3D Data Format issue 1 2 15 05 2003 M Kissler Y Copin P Ferruit A P contal Rousset M M Roth 2 Euro3D I O libraries v1 0a Installation guide issue 1 0a 31 03 2003 A P contal Rousset P Ferruit and Y Copin 3 Euro3D I O libraries v1 0a Developers guide issue 1 0a 31 03 2003 Y Copin P Ferruit and A P contal Rousset 4 E8D The Euro8D visualization tool 2004 AN 325 167 S F S nchez 5 E8D The Euro3D visualization tool II 2004 AN 325 171 S F S nchez T Becker A Kelz 6 The Euro3D data format 2004 AN 325 159 M Kissler Patig Y Copig P Ferruit A P contal Rousset M M Roth 7 The Euro3D LCL I O Library 2004 AN 325 163
18. er sign and the first and last spectra to be shown first spec and last spec e empirical dar index delta index Determines the empirical DAR correction based on the comparison of the centroid position of the crosscorrelated databuce slices It requires the spectral index of the slice used as reference and the spectral indeces width of the datacube slices delta index e encircled spax X YR n It returns the spaxel ID of the nth spaxel that lies in a distance smaller than R arcsec from the position defined by the coordinates X and Y e export cube filename Export the 3D data to datacube It regularizes the data into a grid defined by set grid see below creating for each monochromatic slice an interpolated 2D image e export rss fits file pt file Export the 3D data to a RSS fits file fits file and a ASCII position table pt file E3D uses its own definition of how to stored a position table see e feed slice n feed list Save the slice n feed with the data included in the Tcl list This routine can be used to load into the visuzalizatio tool slices created by external tools like velocity maps created by line fitting tools without affecting the 3D data currently in use e fit single line min max device palette bright contra sign Ig D Ig fit Wo D Wo fit sigma D sigma fit Continuum D Continuum fit CHISQ LIM plot Fits a single emission line to the currently in use average spectrum The model includes a gaussian plus a c
19. er with 10 slots It is always possible to load a stored element in the current in use slot in order to plot it again or analyze it Therefore E3D incorporates routines to load and save the currently in use element slice 14 E3D v1 3 or spectrum into one of the buffer slots The XTK device cannot be directly invoked It requires to call the pgplot routine that creates a pgplot image area and then call the device command over it E g it usr local src e3d user bin tk e3d frame frame width 30 height 30 pgplot frame pgplot share true width 300 height 300 mincolors 256 maxcolors 12000 bg black fg white pack frame pgplot side left fill both expand true pack frame side left fill both expand true create env euro3d frame pgplot device 4 2 Anotated list of commands over the E3D enviroment ask e3d info It returns the basic parameters of the 3D spectrum the number of spectral pixel maximum the number of spaxels the starting wavelength the final wavelength the wavelength increment per spectral pixel the data minumum and maximun values the first and the last spectrum actually defined to be plotted these last values are by default 0 and 256 clean device dev id Indicates not to overplot on the device with identification dev id the next time to plot on eat but clear it before plotting clean server Clean the SHM server close device dev id Close the device indicated by the index
20. ev id with the indicated plotting parameters min max palette bright contra and sign see draw raw e plot spectra mem min max device 1 palette bright contra sign clean Plots the actual average spectrum storaged in memory in the device dev id with the indicated plotting parameters min max palette bright contra and sign see draw raw If clean is 0 it wipes out the plotting area 18 E3D v1 3 pm_dar index delta_index Determines the empirical DAR correction based on the comparison of the centroid position of consecutive slices computer by a principal momentum analysis It requires the spectral index of the slice used as reference and the spectral indeces width of the datacube slices delta_index recolor_image palette dev_id Defines a new palette for the device dev_id release_raw dev_id Redefines the spectral range to be plotted to the full range set the number of spaxels to plotted in the raw stacked spectra image to the default value of 256 and clean the device dev_id reverse obj n obj Reverses the object selection of the object n obj i e select all the spaxels not included in the object selecting as the new object n obj save cut filename Saves a raw stacked spectra image with the currently selected spectral range in the fitsfile filename save file filename Saves all the data in memory as an Euro3D formatted file filename save map n map filename Saves the maps number n map in the fits
21. f you have properly followed the previous sections you should be able to execute it by just typing tk e3d tcl This script will run the tk e3d TCL TK interpreter and open a GUI There are three different windows in E3D The main windows the spaxel inspector and the spectral inspector Hint spazel has been defined within the Euro3D network as the spatial element of a 3D spectra It means a fiber or a lenslet or portion of a slit slice depending on the intrument This concept has been introduced to unify the different possibilities for spatial element 6 E3D v1 3 M E3D Euro3D Visualization Tool v1 3 2 m ij 162794382 Fle Spaxels Spectra Configuration DAR Tools File mome pmweilba E3D e3d 1 3 2 scripts test e3d 43 644868 0 65 0 65 3324 309424 we 3347415919 _ Zoom Release Range of Spectra plotted First 0 W 2 29e404 Row N 348 0 FLUX 0 000000 nmmanta Figure 1 Screenshot of the Main Window of the E3D GUI 3 1 The main window Figure 3 shows a snapshot of the main window It contains an image area an information panel and a toolbar containing different menus The image area of this window is used to plot the row stacked spectra RSS representation of the data an spectral image built including in each row the spectrum correponding to each spaxel By default it is shown the RSS of the first 256 spaxels on the file at maximum The range of plotted spaxels can be changed using the prompts
22. file filename Note n map goes from 0 to 7 save obj file n obj filename Saves the object selected n obj as an Euro3D formatted file filename save PT filename Saves the position table of the Euro3D data on memory to an ASCII file filename The position table is stored in the E3D defined format including the information of the shape of the spaxels SHAPE SIZE1 SIZE2 ANGLE in a line per group followed by the position table information ID X Y GROUP with one line per spaxel E g R 0 5 0 5 1 H 0 5 0 5 2 1 1 0 1 0 1 2 1 0 0 0 1 5 1 0 1 0 2 6 1 0 0 0 2 This position table describes an IFU with two groups with two different geometries R Rectangle H Hexagon and sizes of 0 5 SIZE1 and SIZE2 Each group contains 2 spaxels save_raw filename Saves the full wavelength range raw stacked spectra as a fitsfile filename NOTE for saving the currently selected wavelength range save_cut should be used User Guide 19 save slice n slice filename units outputtype Saves the slice number n slice in the file filename The units of the data can be indicated The type of the output file can be selected between fits talble outputtype 0 and an ASCII table outputtype 1 save spec filename i spax Saves the spectra corresponding to the list of spaxels i spax in the fitsfile filename as a row stacked spectra save spec table filename units outtype i spax Saves the average spectrum from the spectra corresponding to the list of s
23. ins also specific entries for the spaxel inspector 1 the identification of the spaxel currently pointed to by the mouse SPAX ID and its flux FLUX 2 a basic statistic information of the currently selected list of spaxels The toolbar contains the following menus 1 File with different I O options It allows to import a MAP a 2D image and export the cur rently selected databuce slice as a FITS and ASCII table a 2D FITS image once interpolated to a regular grid and Postscript or a GIF file It allows also to save the currently selected object described below as a separated Euro3D formatted file 2 Shape Allows to select different representions of the spaxels a AL man a o c D 0 Ne Fill It plots polygons with the shape of the spaxels filled with the color correponding the the spaxel intensity in the current slice following the pattern defined by the position table Outline Similar to Fill but marking the edge of the polygons Spax Id Similar to Fill but writting the spaxel ID inside the polygons Map It plots an interpolated regular image of the slice The characteristics of the interpo lation are defined in the Configuration menu of the main window decrived above OverContour Similar to Fill but overplotting the counterplot of the intensity levels for that an interpolated version of the data was created using the same configuration as in the previous option Contour It plots only the counter
24. ix also requires to edit the file add def makedefs local to uncomment the proper definition of V3D_LIBS Further tips for this platform were contributed by M Zetzl and may be found in the file doc INSTALL OSF1 alpha txt Hint Installation instructions for MacOSX can be found in the file doc MacOSX E3D INSTALL txt They were written by M Lemoine Busserolle amp M Kissler Patig for MacOSX version 10 3 and adapted by C Goessl for MacOSX 10 4 5 Run the installation routine make install This will not install the binaries anywhere but just edit tk e3d tcl and plot map tcl to be compatible with your directory tree and create the E3D directory in your home 6 Add the directory user bin under the E3D tree to your PATH e g export PATH PATH IFU_PATH E3D_io_LCL 1 6 e3d 1 3 8 user bin for bash shell users setenv PATH PATH IFU_PATH E3D_io_LCL 1 6 e3d 1 3 8 user bin for tcsh users then you also need to add this to your startup file bashrc or cshrc or link the contained files to an existing directory already contained in the PATH variable cd usr local bin ln s 1IFU PATH E3D io LCL 1 6 e3d 1 3 8 user bin this specific example would probably require you to have root permissions T Test E3D by executing the script tk e3d tcl and then loading the file data test e3d 3 The E3D GUI tk e3d tcl In this section we describe the main properties of the E3D GUI the TCL TK script tk e3d tcl I
25. n max Loads an E3D file filename into the visualization tool and display the row stacked spectra image on it e spectrum e3d rdspec number Reads the spectrum number from a previous loaded E3D file and save its result in the array spectrum e slice e3d rdslice ii i2 Creates a broad band SLICE from the wavelenght index ii to the wavelength index i2 and save it in the matrix slice Slice is a 4xNSPAXELS matrix that contains in each row the identification of the spaxel the x and y position of the spaxel and the flux associated with this spaxel This flux is the average of the fluxes through the spectra from the wavelength index i1 to i2 Warning To use the python scripts described above some Python modules have to be previously installed pyFITS NumArray Numeric and TableIO0 http stsdas stsci edu pyfits http sourceforge net project showfiles php group id 1369 http sourceforge net project showfiles php group id 1369 http php iupui edu mmiller3 python
26. number of neighbours to be considered Only the three first routines conserve the flux e Spaxel Selection Menu to configure the spaxel selection in the spaxel inspector This selection can be spaxel to spaxel single or in a circular area of a certain radius multiple The selection of spaxels in the spaxel inspector will be explained below 5 DAR Tools This menu includes different options for correcting the Differental Atmospheric Re fraction DAR The DAR correction is estimated based on the theorietical values derived from the atmospheric conditions stored in the GROUP information see Euro3D Format Documen tation by clicking on the Th Det DAR or based on emipiral estimations Different empirical estimations has been included mainly all of them trace the peak of the intensity of datacube slices at different wavelengths estimating the correction from the displacement of this peak along the wavelength PM Det DAR and Peak Det DAR use this technique The 1st trace the peak by a principal momentum analysis the 2nd by a direct peak search on the spaxel pat tern and the 3th by an grid interpolation of the data and a search of the peak This three methods are useful when we have an object on the data with a clear peak always brighter than the rest of the data Emp Det DAR or empirical determination of DAR correction performs a crosscorrelation of each interpolated datacube slice through different wavelengths with the previous one looking
27. o enter in a E3D shell where the routines can be run in an interactive way complete scriptable enviroment is defined for visualizing and analyzing 3D spectra E g the E3D GUI is a Tcl Tk E3D script tk e3d tcl that uses the new defined routines It also defines its own procedures that can be invoked from the command prompt on E3D see previous section We describe here the E3D routines incorporated to Tcl Tk there use and we explain briefly how to built new scripts using them 4 1 The E3D Tcl TK routines The E3D tcl tk interpreter creates a new tcl tk object the Euro3D enviroment that can be created by the routine create env This routine requires two entries the name of the enviroment and the associated plotting device E g create env euro3d XS The available devices depend on the PGPLOT installation although as indicated in the Installation Section E3D requires at least the following ones XTERM XWIN XSERVER XS PS CPS GIF XTK E3D plotting and analysing routines works with the following elements 2D spectra average spectrum slice and object The last selected element of these four types is stored in memory and therefore any analysing fitting routine would refer to this current in use element E3D incorporates two different kind of buffers to stored previously used elements Slices are automatically saved in a circular buffer with 8 slots Average spectra and objects are interactively stored in a buff
28. onstant value for the nearby continuum It requires the same parameter than draw raw for the resulting plot plus the initial guess values for the fitting including for each parameter Intensity peak central wavelength sigma of the gaussian function and the continuum value the value e g Ig the range of valid values e g D Ig and a flag indicating if to fit this values or not 1 for fitting It also requires the desired reduces x and a flag indicating of to plot or not the results 0 for not plotting e flux spax spax index Returns the flux of the spaxel defined by spax index in the currently in use slice e guess single line Guess the initial parameters to use fit single line It returns a tcl list including Ig Wo sigma and Continuum e import cube fitsfile Imports a 3D datacube fitsfile into E3D currently available grey rainbow heat iraf aips 16 E3D v1 3 import_map fitsfile Imports a 2D image fitsfile into E3D The image is considered as a single spectral index 3D cube import_rss rss_fitsfile positiontable Imports a 3D data in the RSS format into E3D It requires a 2D spectral image the RSS image rss_fitsfile and an ASCII file containing the E3D position table positiontable import_spectra fitsfile Imports a 2D spectral image into E3D It considers the data to be a slit spectra with an slit width of dpix See set_grid intensity i j Returns the intensity of 3D spectra of the jth
29. oo AUR X UE Bele oe OR S G 3 2 Thespaxelinspector ota ecs ll ll s s 3 3 The spectral inspector 22 e SR oss 4 The E3D Tcl TK routines 4 1 The BSD Tcl TK FOULWIeS 43 bu eo eee ee Le eR Be ls ORE e ses es 4 2 Anotated list of commands over the E3D enviroment 2 4 3 Examples of E3D Tcl Tk scripts 2 o9 sov b Rom BEG dE s eG ae 3 4 3 1 Extract a single spectrum of an Euro3D cube 4 4 3 2 Extract a single slice of an Euro3D cube 2 0084 4 3 8 Extract a single slice of an Euro3D cube 2 22 5 Connecting E3D with external packages 5 1 Interaction through files coea op er na ls 5 LI E3D through IDL s oria ta porie ox ORE ER Eso AE S 5 1 2 E3D through Python sy eek th AT EE eu YER vi This page was intentionally left blank E3D v1 3 User Guide 1 1 Introduction 1 1 Purpose and scope The Euro3D Research Training Network RTN was put forward with the intention to promote inte gral field spectroscopy IFS or 3D spectroscopy and to help making it a common user technique In order to accomplish this one of the major tasks was identified as the need of providing standard software tools for the visualization and analysis of datacubes These tools should be general enough to be entirely independent of the origin of data i e 3D instrument Previously a heterogenous col lection of instrument specific data formats and software tools e g XOASIS proprietary
30. ot the spectra as a RSS an average spectrum plot a plot of the different spectra as single spectrum plots and a combination of the above methods d Interpolation Menu to configure the interpolation options of E3D The interpolation has been included on E3D to build 2D images of the maps on the spaxel inspector from the spaxel representation and or generate datacubes from the Euro3D formatted data Five different interpolation routines are included Cubic Spline default Linear Delaunay Nearest Neighbour NN Inverse Distance kth Inverse Weight Nearest Neighbour NN IDW and 3NN Linear Weight 3rd Linear Weight Nearest Neighbour NNL All of these routines need an output pixel size in arcsecs of the interpolated map some of then require an additional Grid parameter The Grid parameter has different meanings for the On export datacubes are resampled onto a new grid so that this function also works for complex datacubes of e g fiber bundles If the grid options were not changed since loading the file the grid should be identical to the input sampling but depending on the interpolation method to be selected under Configuration in the main window some spaxels on the edges might not be defined 8 E3D v1 3 different routines While for the Cubic Spline is not necessary for the Linear Delaunay and the NN methods it means resolution of the triangulation values 10 work fine and for the Nearest Neightbour it refers to the
31. paxels i spax in the filename as a fits outtype 0 or an ASCII outtype 1 table save spectra sel i spax Stores the list of selected spaxels i spax in the memory as the currently selected spaxels set first last first last Defines the range of spectra to be plotted in the raw stacked spectra representation of the data see draw raw The range is defined between the spaxel number first and the spaxel number last set flag spec flag spec Defines the kind of statistics used to define the average spectrum from a list of selected spectra flag spec 0 for mean flag_spec 1 for 2o cleaping set grid grid func grid opt pixel size Defines the algorithm to be used for the maps interpolation from the list included in E3D grid func 1 Cubical Spiline CSA default 2 Linear Delaunay 3 Natural Neighbour NN 4 kth Inverse Weight Nearest Neighbour NN IDW and 5 3th Linear Weight Nearest Neighbour NNL The grid opt is a parameter needed for each function that has no use for the 1 2 and 5 For 3 defines the acurracy of the slope and it should be a very low number and for 4 defines the last neighbour to take into acount The pixel scale of the interpolated map is defined by pixel size in the units of the position table e g arcsec set type spec rep type Defines the type of spectral representation for the different routines that plots spectra plot spectra and plot spectra mem The different representations are
32. plot Map Spax Shape Similar to Map but overplotting the pattern and shape of spaxels by plotting open polygons 3 Select This menu comprises different options related with the spaxels selection a b e Clear Clean the current list of selected spaxels Plot Spectra Plot the spectra corresponding to the selected spaxels in the spectral in spector This can be also done by clicking with the right mouse button over the main image area of the spaxel inspector Plot Flux Profile Plot the fluxes of the current slice corresponding to the selected spax els in the spectral inspector as a 2D plot It performs a simple fitting to a single gaussian plus a continuum This option is convinient to determine the seeing of an observation the extension of an object or the distance between two different peaks Create object It saves the currently selected list of spaxels into a buffer We have defined as object to this selected list of spaxels E3D stored a maximun of 10 objects that are listed in the left size information panel To load a previously created object just click on the corresponding object on the list These objects can be saved as a separated Euro3D formatted file using the Save object option on the File menu Reverse object It reverses the list of selected spaxels selecting the non selected and de selecting the selected This option is useful for creating an spectra of the sky In this case the pseudo slit selection ha
33. plot previous selections by clicking with the right mouse button on the corresponding small image area The active buffer will be marked with a red envelope The spaxel inspector allows you to select different spaxels to a perform a basic statistic analysis of the intensity corresponding to spaxels in the currently selected slice b visualize the intensity of each one in a 2D plot and c visualize the corresponding spectra in the spectral inspector There are differnt methods to select spaxels User Guide NJ Spaxel Inspector CC EI Max o Fle Shape Select Tools dose Min E Bright 0 77 El Contra 0 65 mz wi 01234 W2 ozs SPAX ID 1219 FLUX 23375877 x Feo Y rz mm N SPAXELS 0 MEAN 0 0 SIGMA 0 0 Objects Figure 2 Snapshot of the spaxel inspector of the E3D GUI Single spaxel selection We select a single spaxel by moving through the image while keeping clicked the middle mouse button The spectrum corresponding to this spaxel will be automati cally send to the spectral inspector To remove spaxels from the selection hold the d key while selecting them again Multiple selection by spaxel to spaxel selection This selection is included by default and can be modified in the Configuration menu of the main window It is possible to select a single spaxel by keeping clicked the left mouse button an moving through the image The corresponding spaxel
34. s a better physical meaning User Guide 11 Spectra Inspector Max 151177734 File Spectra Fitting Wavelength 5005 84 Mn ft Bright 065 GNE Contra ie GNI wi 5283 82 we 518462 Zoom Release Spectra n A Ui jJ Z Figure 3 Snapshot of the spectral inspector of the E3D GUI 4 Tools A miscellaneus of useful tools including a Blink Allows to blink between different slices previously selected and included in the small buffers For that click over the Blink button and then select the different selections by clicking over the corresponding small frames Once you have completed the selection click again on the Blink button to start the blinking To stop it click again on the button b Arithmetics It pop ups a menu for performing basic arithmetic between the buffered slices add subtract divide and multiply The buffers are ordered from 1 to 8 from top to botton and from left to right In order to perform an arithmetic operation the menu ask for the number of three slices the two operators and the output slice and the operation to perform 5 Close Close this window A zooming capability has been included in the spaxel inspector In order to zoom over a certain area press the z key while over the image The mouse pointer will transform into a rectangle which defines the zooming area Pressing again z E3D will create a new map with similar characteris
35. se two menu items only work for emission lines of very high S N For all other purposes please use line fitting routines in other environments a Fit Single Emission Line It performs fitting to a model that comprises a single gaus sian function plus continuum over the last selected average spectrum This simple pro cedure allows to measure the line flux the FWHM and the continuum level Figure 3a shows a snapshot of the output of this routine Full Automatic Kinematic Analysis It performs a Kinematic analysis by a single line fitting over all the spectra in the cube It determines the emission line flux distribution the velocity map and dispersion and the continuum level All output maps are sent to the Spaxel inspector in this order and displayed in the small windows right click on them to get the full map of the results This simple procedure allows to get a rough estimate of the kinematic structure of the data 4 Close Close this window User Guide 13 Spectra Inspector Max 1001 177734 Fle Spectra Fitting Wavelength 0 173283 ose ZEE o 54 55 66 FWHM 6 52 WI 5520403 we 586408 Zoom Release Spectra Figure 4 Snapshot of the output of the Single Line Fitting on the spectral inspector 4 The E3D Tcl TK routines As we explained before E3D includes a Tcl Tk interpreter tk e3d that incorporates the E3D routines to Tcl Tk The interpreter can be invoked t
36. the average spectrum as a FITS and ASCII table It is also possible to save the plotted image as a Postscript or a GIF file 2 Spectra It allow to handle with the average spectrum created from the average of the selected spectra E3D allows to save 10 different average spectra in a buffer Spectra that are listed in the information pannel on the left size of the spectral inspector when created There different option in this menu a Save Spectrum Clicking this button E3D saves the currently average spectrum in the next available buffer It is possible to re plot this spectrum by clicking in the list included in the left information panel Single Multiple Plot Allows to select a single spectrum from the list or multiple spectra With this second option the different spectra will be overplotted in the image area with different colors each one It can be used to visually compare different spectra Clear Multiple Selection Clean the list of selected spectrum when the Multiple Plot option is selected Artithmetic It allows to perform basic arithmetic operations between spectra like Add Subtract Divide and Multiply Sky Subtraction using this item one can subtract a spectrum from all spectra in the data cube To do that select a spectrum from the list on the right after activating this menu item 3 Fitting T his menu include simple fitting routines for a quick analysis of the emission lines in the spectra Warning The
37. tics than the currently defined but zoomed over the spatial region defined by the rectangle E3D keeps a record of the zoomed area for any following created map To restore the default plotting size press the u key 3 3 The spectral inspector The spectral inspector allows to visualize and analyze spectra It comprises an image area an information panel left and a toolbar The spectra plotted in the image area are sent to the spectral inspector by a direct selection of one or more spaxels in the main window or by an spaxels selection in the spaxels inspector These spectra could be plotted with different representations selected in the Configuration menu on the main window see above Once plotted it is possible to select a 12 E3D v1 3 certain wavelength range or move throw the wavelengths in a similar way that in the main window when the spectral selection is selected i e by clicking with the left mouse button once or twice selecting a range an sending it to the spaxel inspector by clicking the right mouse button or moving through the wavelength while clicking the central mouse button The information panel contains the same information than the same panel for the other two windows plus an expecific entry for buffered spectra that willbe explained below The toolbar contains the following options 1 File It contains different I O options It allows to save the currently selected spectra as a FITS spectral image and
38. um txt 01 create env euro3d null 02 euro3d load file e3d file fits 03 set selected temp 04 lappend selected temp 100 05 euro3d save spec table spectrum txt Flux 1 selected temp 06 exit 4 3 2 Extract a single slice of an Euro3D cube The following scripts extracts a single slice corresponding to the spectral pixel number 1 from the Euro3D file e3d file fits and save it as an ASCII table in the file slice txt 01 create env euro3d null 02 euro3d load file e3d file fits 03 euro3d create slice 0110 04 euro3d save slice 1 slice txt Flux 1 05 close 06 exit 4 3 3 Extract a single slice of an Euro3D cube 01 create env euro3d null 02 euro3d load file e3d file fits 03 set id ps euro3d open device file ps CPS 04 euro3d plot spaxels 1 0 100 0 id ps 100 300 heat 0 60 711102 05 euro3d close device id ps 06 exit 5 Connecting E3D with external packages In this section we describe how to interact with E3D using external packages This is done using E3D Tk Tcl routines written to special files Additionally it is possible to access E3D with IDL and Python routines Two different sets of examples created by S bastien Foucaud for these are included with the E3D distribution 5 1 Interaction through files E3D can understand direct commands calls see REF and scripting files see REF Using this method it is easy to interact with E3D once knowing the nomenclature of E3D tcl tk routines REF We have
39. utput e3d 5 1 1 E3D through IDL In the scripts directory of the E3D installation you can find three files containing three IDL procedures e e3d display filename data in file e3d_display pro Loads an E3D file filename into the visualization tool and display the row stacked spectra image on it It gives you back an array containing the basic common information of the E3D file number of pixels on each spectra number of spaxels starting wavelength final wavelength wavelength increase per pixel number of groups maximun and minimun value within the data e e3d read spec nspec spectrum in file e3d read spec pro Reads the spectrum npsec from a previous loaded E3D file and save its result in the array spectrum e e3d read slice ii i2 data slice in file e3d read slice pro Creates a broad band SLICE from the wavelenght index ii to the wavelength index i2 and save it in the matrix slice It requires the data from the file output of the e3d display routine as an input parameter slice is a 4xNSPAXELS matrix that contains in each row the identification of the spaxel the x and y position of the spaxel and the flux associated with this spaxel This flux is the average of the fluxes through the spectra from the wavelength index i1 to i2 User Guide 23 5 1 2 E3D through Python In the scripts directory of the E3D installation you can find a Python library e3d py containing the following functions e e3d display filename mi
40. will be added to the selection list and marked as hashed Multiple selection by selecting circular areas This selection can be defined in the Configura tion menu of the main window defining a radius of selection We select the spaxels within a distance of this radius to the actual position of the mouse when moving through the image keeping clicked the left mouse button These spaxels will be included into the selection list and marked as hashed Multiple selection by pseudo slit definition This mode is available by pressing the s key Then it is possible to define a pseudo slit by clicking with the left mouse button on a certain position of the slice marking an starting point for the pseudo slice and by a second click marking the ending point and selecting the spaxels along the pseudo slit Pressing again the s key we return to the spaxel to spaxel selection mode A basic statistic of the flux on the selected spaxels is shown in the information panel The spectra 10 E3D v1 3 of the corresponding selected spaxels is seen in the spectral inspector by clicking on the right mouse button Pressing the v key we see the flux profile of the selected spaxels in the spectral inspector Both the spectra and the fluxes are shown in the order of selection of the spaxels The left size information panel contains similar entries than the same panel in the main window min max bright contrast and currently selected wavelength range It consta
41. yntax of the program is any2Euro3D if input file fits of output file e3d pf position table txt nb spec 999 where 999 is the number of spectra in the rows of the input file and should correspond to the number of spectra in the input file and all filenames have to include the path to the file unless they are in the current directory Options to import export a slit spectra assuming an aperture of dpix and to export a wave length cut of the RSS have also been included The Quit menu item can be used to exit the E3D tool 2 Spaxels Menu to handle the Spaxel inspector It allows to open this inspector Open change the kind of mouse selection in the main window Select and to plot the map of the current spectral selection in the spaxel inspector Plot 3 Spectra Menu to handle the Spectra inspector It allows to open this inspector Open change the kind of mouse selection in the main window Select and to plot the RSS of the selected spaxels in the spectral inspector Plot 4 Configuration This menu includes different submenus to change the configuration of the pro gram a Colormap Menu to change the color palette among the different included on E3D b Scale Menu to change the image scaling among the different included on E3D Default Logarithm Square Root Square and Linear c Spectral Representation Menu to change the representation of the spectra on the spec tral inspector It is possible to pl
Download Pdf Manuals
Related Search