Is0188 b Iris

IRIS Technical Note 28: IRIS IDL data structure (and use of level 2 data)

Viggo Hansteen, version 1.1: 30 September 2013

1. Getting started

To get started install the IRIS software:

IDL> ssw_upgrade,/iris,/spawn,/loud,/passive_ftp ; install/upgrade iris

(It may also be useful to have the Hinode/EIS branch installed, but this should not be strictly necessary.)

A test to see if things are set up right is to run

IDL> iris_xfiles ; make sure you are running the version that resides in the IRIS branch

If you have level 2 IRIS data available you should be able to click on a file name and launch the iris_xcontrol widget.

2. Introduction

The IRIS level 2 software is designed to allow the user to easily read and access the data and keywords contained in IRIS level 2 fits files. It is also designed to be used by the IRIS QL software, i.e. those widgets called by xfiles. The software is built up of several objects; iris_data, iris_aux, iris_sji, iris_cal, iris_moment, etc, the most important of which is by far the iris_data object. To construct an iris_data object one first need to find a set of iris files. The function iris_files has been constructed to aid in that

IDL> f=iris_files(filter,path=path)

The default filter is ‘*.fits’, the default path is ‘./’. E.g.

IDL> f=iris_files(path='2013/09/01/20130901_075424_4003005147') 0 2013/09/01/20130901_075424_4003005147/iris_l2_20130901_075424_4003005147_SJI_1330_t000.fits 859 MB 1 2013/09/01/20130901_075424_4003005147/iris_l2_20130901_075424_4003005147_SJI_1400_t000.fits 859 MB 2 2013/09/01/20130901_075424_4003005147/iris_l2_20130901_075424_4003005147_SJI_2796_t000.fits 859 MB 3 2013/09/01/20130901_075424_4003005147/iris_l2_20130901_075424_4003005147_raster_t000_r00000.fits 15 GB

IRIS Technical Note 28: IRIS IDL data structure

1

Then IDL> d=iris_obj() or d=iris_obj(<iris level 2 file/slit jaw file(s)>)

The latter variant will call the read method, which also can be called directly after the object is created

IDL> d->read, <iris level 2 file/slit jaw file(s)>

where <iris level 2 file/slit jaw file(s)> is a string array containing the name of a level 2 raster and from zero up to 4 slit jaw image series overlapping in time with the raster. At present the level 2 raster file is assumed to be the first element in the string array, but this restriction will probably be removed soon.

Finally, there is a function that returns a fully packed i.e. raster plus slit jaw images iris_data object or a slit jaw image iris_sji object or a structure containing relevant IRIS raster data. When loading with iris_load a raster file the slit jaw images taken during the raster will also be loaded. When loading a slit jaw file, all images will be read and loaded (into an iris_sji object).

IDL> d=iris_load(<iris_raster_file> or <iris_slit_jaw_file> ,structure=structure)

3. Simple examples

The read method fills the objects data structure, the other methods are mainly designed to retrieve information via methods name get<variablename>. The first thing Joe User would like to do is perhaps to look at the fits header. Here is a simple IDL script that shows how this can be done (the script can be found in the ‘utils’ directory of the SSW distribution.function

iris_readheader,f,struct=struct,extension=extension if n_elements(extension) eq 0 then extension=0 d=iris_obj(f) hdr=d->gethdr(extension,struct=struct) obj_destroy,d return,hdrend

The ‘gethdr’ method by default it will return the main (extension=0) fits header, but since the various IRIS line windows (regions) are stored as extensions 1....NWIN, there is a small header associated with each which may be useful. Using the ‘struct’ keyword will return the header as an idl structure instead of a as a string array. In the latter case header tags (keywords) can be accessed with the usual SSW ‘fxpar(hdr,tag)’ routines. Note that since the main header is contained in extension=0, the window headers are accessed as extension=window nr + 1.


2

In general this should be the recipe for writing small ‘one-liners’:

1. open and load the object, viz d=iris_obj()2. call the methods needed to do what you want to do3. manipulate and make the output available4. destroy the object

To actually look at the data, use

IDL> win=d->getvar(iwin,load=load,struct=struct)

to get data for window number iwin. The data is by default returned as a pointer to a location in the fits file and that access to the data therefore is through the IDL assoc mechanism. If one requires the entire window to be read into memory, a /load option should be passed to getvar:

IDL> win=d->getvar(iwin,/load,/struct)

The ‘struct’ option loads (most of the important) information into a data structure - i.e. the fits header and the window data - in case one prefers working with that instead of with the object and with object methods directly. Note that reading in data to the structure may take some time (for reasons that are a bit obscure to this author).

Other examples (of many, see below) are

IDL> exp=d->getexp(iexp,iwin=iwin) or xpos=d->getxpos(indx,iwin=iwin)

to get the exposure time for exposure number iexp or spatial index indx in window number iwin. These function return an array of exposure times or spatial positions if no parameter iexp or indx is given, and default to the default window (the first one read) if no iwin keyword is given..

A very useful procedure at this point is perhaps IDL> d->show_lines Spectral regions(windows) 0 1335.71 C II 1336 1 1349.43 Fe XII 1349 2 1351.17 1351 3 1355.60 O I 1356 4 1393.78 Si IV 1394 5 1402.77 Si IV 1403 6 2786.52 2786 7 2796.20 Mg II k 2796 8 2831.33 2831 Loaded Slit Jaw images 0 SJI_1330


3

1 SJI_1400 2 SJI_2796which gives an overview of the line(s) and SJI windows loaded into the object.

4. Level 2 to level 3 conversion

Level 3 data is a time series of rasters belonging to the same OBSID. To construct level 3 data do something like the following:

First isolate the files belonging to a given time series of rasters:

IDL> f=iris_files('*4001000010*.fits') 0 IRIS_20130507_100218_4001000010SJI_1330.fits 1 IRIS_20130507_100218_4001000010SJI_1400.fits 2 IRIS_20130507_100218_4001000010SJI_2796.fits 3 IRIS_20130507_100218_4001000010SJI_2832.fits 4 IRIS_20130507_100218_4001000010_raster_t00_r0000.fits 5 IRIS_20130507_100218_4001000010_raster_t00_r0001.fits 6 IRIS_20130507_100218_4001000010_raster_t00_r0002.fits 7 IRIS_20130507_100218_4001000010_raster_t00_r0003.fits 8 IRIS_20130507_100218_4001000010_raster_t00_r0004.fits 9 IRIS_20130507_100218_4001000010_raster_t00_r0005.fits

The raster series runs from f[4:9] while the slit jaw images run from f[0:3]. Level 3 data using (e.g.) the SJI_1400 slit jaw images as a reference cube can now be constructed via

IDL> iris_make_fits_level3,f[4:9],[0,6],/sp,sjifile=f[2]

The full calling structure of the ‘iris_make_fits_level3’ routine is

iris_make_fits_level3,file(s),iwin,all=all,sjifile=sjifile,sp=sp,wdir=wdir,tmp_size=tmp_size

where the raster files go in ‘file(s)’, the desired spectral window(s) in `iwin’ - use the ‘/all’ keyword to get all windows, and the reference slit jaw images in `sjifile’ (note that currently only one channel at a time is allowed). The ‘/sp’ option produces a (spectral,time,x,y) cube in addition to the default (x,y,spectral,time) cube. The `tmp_size’ option sets the max temporary memory size and should be set if the memory problems are encountered (i.e. if the routine uses a lot of time). The unit is GB and default is set to 12 GB. The routine will write the level 3 data on directory ‘wdir’, default is the current working directory.

5. The iris_data object

In somewhat greater detail we can see that the iris_data object contains the following variables


4

pro iris_data__define mfile=6mwin=25nsji=4wpos=create_struct(name='win_info','xs',0,'xw',0,'ys',0,'yw',0)auxinf=create_struct(name='aux_info','time',ptr_new(), $ 'pztx',ptr_new(),'pzty',ptr_new(), $ 'exptimef',ptr_new(),'exptimen',ptr_new())sjiinf=create_struct(name='sji_info','xs',0,'xw',0,'ys',0,'yw',0,'time',ptr_new(), $ 'pztx',ptr_new(),'pzty',ptr_new(), $ 'exptime',ptr_new(),'slit',ptr_new())wdstruct=create_struct(name = 'wd_def', 'line_px', intarr(2), $ 'cont_px', intarr(2))struct={iris_data, title: ' ', $ comment:'', $ filename:'', $ ver_no: 0, $ aux:ptr_new(), $ cal:ptr_new(), $ iiobslid:'',$ nwin: 0, $ regtot: intarr(mfile), $ xcen: -9999., $ ycen: -9999., $ fovx: 0.0, $ fovy: 0.0, $ file: strarr(mfile), $ nfiles: 0, $ region: strarr(mwin), $ mapping: intarr(mwin), $ line_id: strarr(mwin), $ naxis1: intarr(mwin), $ naxis2: intarr(mwin), $ naxis3: intarr(mwin), $ hdr: ptrarr(mwin),$ w: ptrarr(mwin),$ win_info:replicate({win_info},mwin), $ aux_info:replicate({aux_info},mfile), $ wd_def:replicate({wd_def}, mwin), $ sji_iiobslid:'',$ sji_id: strarr(nsji), $


5

naxis1sji: intarr(nsji), $ naxis2sji: intarr(nsji), $ naxis3sji: intarr(nsji), $ hdrsji: ptrarr(nsji),$ wsji: ptrarr(nsji),$ sji_info: replicate({sji_info},nsji)$ }end

Note that in addition to variables that describe the size, shape, position, exposure times, etc of the data, the iris_data object also contains pointers to two other objects: aux, which is a pointer to an iris_aux object, and cal which points to an iris_cal (calibration) object. These can be accessed in the usual way, if d is an iris_data object:

IDL> a=d->getaux() ; orIDL> c=d->getcal()

but are mainly used internally by the iris_data methods.

The most important methods are:

iris_data function name comment

getvar ,iwin, load=load,revnegdx=revnegdx

IRIS data for window iwin, /load for loading data into memory instead of access via assoc, reverse order of exposures if RevNegDx set

getsji,iwin SJ image for window iwin

gethdr ,iwin Fits file header for window iwin-1, iwin=0, the default, gives the main header of fits extension zero.

gethdr_sji ,iwin Fits file header for SJ window iwin, note that these are numbered so that the same window number always corresponds to the same filter

getinfo,tag,iwin Return information in header tag, optional window iwin - most header info is in header nr 0, e.g. print,d->getinfo(‘NAXIS1’,1) returns keyword naxis1 (for window iwin=0)


6


getnwin Number of data windows

getpos ,iwin Structure with window placement on detector {xs,xw,ys,yw} window iwin

get{xs,xw,ys,yw} Get start pixel or width/height of window iwin

get{xs,xw,ys,yw}_sji Get start pixel or width/height of SJ window iwin

getnslit ,iwin Number of pixels along slit

getnraster ,iwin Number of raster positions

getnexp ,iwin Number of exposures in raster

getnexp_prp, iwin Number of exposure per raster position

getntime, iwin Number of exposures in raster

getsit_and_stare,iwin True (1) if ‘sit and stare’ raster

getline_id ,iwin Return line id for window iwin

getsji_id,iwin Return line id for SJ window iwin

getwindx,input Find window number of input, e.g. if input =1334, will find the window that covers that wavelength

getlam,iwin Return wavelengths for pixels of window iwin

getlambda,region,wscale=wscale Return wavelength/pixel of region (detector, possible choices are ‘FUV’, ‘FUV1’, ‘FUV2‘, and ‘NUV’), the value of wscale (‘pixel’ or ‘AA’) decides what to return, if not given uses default (which can vary depending on value set in the aux object at the time of calling.

getdispersion,iwin,region=region Return dispersion of window iwin


7


getwscale Return default wavelength scale (‘pixel’ or ‘AA’), can be set with procedure d->setwscale,wscale

getregion,iwin,full=full Return region (detector) for window iwin. E.g. ‘FUV’,‘NUV’ setting full gives ‘FUV1’ or ‘FUV2’

getccd,region CCD size (wavelength pixels) of region, region can take values ‘FUV’, etc.

getccd_sz,region CCD size [wavelength pixels, slit height] of region which can take values ‘FUV’, etc.

get{x,y}pos,iwin=iwin Position on Sun of window iwin

getdx,istep,iwin=iwin Distance between (istep, istep+1 or all) raster exposures window iwin

get{x,y}cen, Return xcen or ycen

getfov{x,y}, iwin Return field of view size in x or y window iwin

getpzt{x,y}, iwin,indx Return pztx or pzty window iwin, raster position indx or all

getpztx_sji,iwin,indx=indx Return pztx or pzty for SJ image window iwin, raster position indx or all

getexp,iexp,iwin=iwin Return exposure time (ms) exposure iexp window iwin

getexp_sji,iexp,iwin=iwin Return exposure time (ms) exposure iexp window iwin

gettime,iwin,indx Return time (unit is currently ms, should be?) window iwin, exposure indx or all

gettime_sji,iwin,indx Return time (unit is currently ms, should be?) SJ image window iwin, exposure indx or all

{x,y}scale_sji,lwin solar coordinates of {x,y}-axis on SJ image


8

6. The iris_sji object

This object is in many ways similar to the iris_data object, but is designed to give quick access to the level 2 slit jaw images, i.e. if one wants to make/view a movie of images. The quickest way to make a sji object is

IDL> d=iris_sji() ; orIDL> d=iris_sji(<sji_filename(s)>)

in the former case a slit jaw file can be read into the object with

IDL> d->read, <slit jaw file(s)>

The read method fills the following object structure with data.

pro iris_sji__define mfile=4mwin=25wpos=create_struct(name='win_info','xs',0,'xw',0,'ys',0,'yw',0)sjiinf=create_struct(name='sji_info','xs',0,'xw',0,'ys',0,'yw',0,'time',ptr_new(), $ 'pztx',ptr_new(),'pzty',ptr_new(), $ 'exptime',ptr_new(),'slit',ptr_new())struct={iris_sji, title: ' ', $ comment:'', $ ver_no: 0, $ aux:ptr_new(), $ cal:ptr_new(), $ date: '2012-12-31', $ nwin: 0, $ regtot: intarr(mfile), $ obsid: strarr(mfile), $ fdbid: strarr(mfile), $ crsid: strarr(mfile), $ xcen: -9999., $ ycen: -9999., $ file: strarr(mfile), $ nfiles: 0, $ lwin: intarr(mfile), $ region: strarr(mfile), $ sji_id: strarr(mfile), $ naxis1: intarr(mfile), $


9

naxis2: intarr(mfile), $ naxis3: intarr(mfile), $ hdr: ptrarr(mfile),$ w: ptrarr(mfile),$ sji_info: replicate({sji_info},mfile),$ nuv_sz:[0.,0.], $ fuv_sz:[0.,0.] $ }end

Again, the structure can be accessed through various get<variablename> methods, many with the same names as for the iris_data structure. There is also a ximovie method that allows one to view the slit jaw images as a movie.

iris_sji function/procedure comment

ximovie, iwin open ximovie widget with slit jaw images from window iwin, e.g. d->ximovie,iwin

getvar,iwin IRIS Slit Jaw image data for window iwin

gethdr,iwin FITS file header for window iwin

getinfo,tag,iwin Return information in header tag, window iwin, e.g. print,d->getinfo(‘NAXIS1’,0) returns keyword naxis1 one for window iwin

getnwin Return number of slit jaw channels in object

lwin_read Return intarr(4) with elements set to 1 if that channel is read, set to 0 if not read

getpos,iwin Return position of slit jaw image on CCD window iwin

get{xs,xw,ys,yw},iwin Get start pixel or width/height of window iwin

getnslit,iwin Number of pixels in y-direction (ie along slit)

get{nraster,nexp,ntime},iwin Number of slit jaw image exposures

getsji_id,iwin Return ID of window iwin


10

iris_sji function/procedure comment

getresx,iwin Return resolution of image in x-direction

getresy Return resolution of image in y-direction

getexp,iexp,iwin=iwin Exposure time image iexp window iwin

getpzt{x,y},iwin,indx=indx Return pztx or pzty for SJ image window iwin, raster position indx or all

gettime,iwin,indx Return time (unit is currently ms, should be?) SJ image window iwin, exposure indx or all

get{x,y}pos,iwin Return pztx or pzty for SJ image window iwin, raster position indx or all

get{x,y}cen Return xcen or ycen

getfov{x,y},iwin Return field of view size in x or y window iwin

{x,y}scale solar coordinates of {x,y}-axes

7. The iris_cal object

The iris cal(ibration) object is designed to keep all relevant information pertaining to the IRIS instrument in one, easily maintained, place with methods to access them. Some of these numbers are derived “by word of mouth” from LMSAL staff. Most should be quality controlled and some should be replaced by calls to SSW IDL functions/procedures maintained by LMSAL, e.g. iris_get_response(). There is a pointer to an iris cal object in every iris_data object, so methods can always be called via the iris_data object:

IDL> result=(d->getcal())->method(parameters,keyword=keyword)

where ‘d’ is a iris_data object. For methods that are called often, it is perhaps better to write a data object method that calls the cal object. See already existing examples in the data object, e.g.:

function iris_data::getdispersion,iwin,region=region if n_params() lt 1 then begin if n_elements(region) eq 0 then begin message,'window or region not given, assuming "FUV1"',/info region='FUV1' endif


11

endif if n_elements(iwin) ne 0 then region=self->getregion(iwin,/full) disp=*self.cal->getdispersion() case region of 'FUV1': dispersion=disp.dispfuv1 'FUV2': dispersion=disp.dispfuv2 'NUV' : dispersion=disp.dispnuv endcase return,dispersionend

The iris_cal object contains the following data structure.

pro iris_cal__define nband0=4 nband=6 neff=3601 struct={iris_cal, $ title:'', $ id0:strarr(nband0), $ id:strarr(nband), $ lambda0:fltarr(nband0), $ dellambda0:fltarr(nband0), $ dellambda:fltarr(nband), $ resy:1.0,$ resx0:fltarr(nband0), $ resx:fltarr(nband), $ effective_area0:fltarr(nband0), $ arcsec2sr:1.0, $ cc:1.0,$ eperph0:fltarr(nband0), $ eperph:fltarr(nband), $ sji_slitpos:{slitpos,fuv_xs0:0,fuv_ys0:0,nuv_xs0:0,nuv_ys0:0},$ nuv_sz:[0.,0.,0.,0.], $ fuv1_sz:[0.,0.,0.,0.], $ fuv2_sz:[0.,0.,0.,0.], $ dispersion:create_struct(name='dispersion', $ 'wfuv10',1.0,$ 'wfuv20',1.0,$ 'wnuv0',1.0,$ 'dispfuv1',1.0,$ 'dispfuv2',1.0,$ 'dispnuv',1.0,$


12

'nwfuv1',1,$ 'nwfuv2',1,$ 'nwnuv',1), $ effective_area_read:0,$ effective_area:create_struct(name='effective_area', $ 'll',fltarr(neff),$ 'sgfuv',fltarr(neff),$ 'sgnuv',fltarr(neff),$ 'sjf133',fltarr(neff),$ 'sjf140',fltarr(neff),$ 'sjn279',fltarr(neff),$ 'sjn283',fltarr(neff),$ 'telccd',dblarr(neff)),$ effective_area_dir:'',$ effective_area_file:'' $ }end

iris_cal function/procedure comment

getid,ib return band (region) name (e.g. ['FUV','NUV','SJI_1330','SJI_1400','SJI_2796','SJI_2832']) of band ib

getdellambda,ib return spectral resolution of band ib

getdispersion return dispersion structure

pixels_fuv1, pixels_fuv2, pixels_nuv return number of spectral pixels in these bands

getresx,ib getresy return spatial resolution (or slit size) for band ib, spatial resolution along slt

lambda_fuv1, lambda_fuv2, lambda_nuv

return, wavelength scale of these bands

getnuv_sz, getfuv_sz, getfuv1_sz, getfuv2_sz

return 4 element array containing [start pixel x, # of pixels x, start pixel y, # of pixels y] for these CCD regions

getccd_height,region return number of pixels along slit for CCD region (‘NUV’, ‘FUV1’, etc)

getccd_sz,region return size of CCD for region ‘NUV’, ‘FUV1’, etc...


13


geteperph,ib return number of electrons per photon

enph, lambda return energy (in ergs) of photon with wavelength lambda

geteffective_area_read return 1 if effective area file has been loaded, 0 otherwise (only needed if reading local copy of effective area file)

effective_area_read,file=file,dir=dir,nonstandard=nonstandard

load effective area data into object or read effective area file ‘file’ in directory ‘dir’ if ‘nonstandard’ keyword is set

geteffective_area,ib,lambda return effective area for band ib

getarcsec2sr return size of pixels in steradians

getsji_slitpos return pixel positions of slit on CCDs

8. The iris_aux object

The iris_aux object contains mehtods and data that don’t really find a natural place anywhere else, this includes variables with axis names, menu items and the like. There is a pointer to an iris aux object in every iris_data object, so methods can always be called via the iris_data object:

IDL> result=(d->getaux())->method(parameters,keyword=keyword)

where ‘d’ is a iris_data object. For methods that are called often, it is perhaps better to write a data object method that calls the aux object or make an instance of an aux object in your idl session:

IDL> a=iris_aux()

pro iris_aux__define nitem=10 struct={iris_aux, $ aa:'',$ title:'',$ wscale:'',$ sscale:'',$ xytitle:strarr(nitem), $ variablename:'', $


14

momentnames:strarr(nitem), $ momentunits:strarr(nitem) $ }end


{set,get}wscale set or return ‘pixels’ or ‘Å’ describing set wavelength scale

{set,get}scale set or return ‘pixels’ or ‘arcsec’ describing set spatial scale

{set,get}xytitle set/get axis title for x/y/t axis


15

Is0188 b Iris

Documents

Transcript of Is0188 b Iris