# Presentation: 674041

## Reading and Writing FITS Files

- General tools:
- In IDL:
- fits_info – Summarizes FITS file primary data and extensions
- Example:  fits_info, 'hsi_spectrum_20020421_004040.fits'
- mrdfits – Reads an extension in a FITS file
- Calling sequence: data = mrdfits(file, ext, header)
- Example:  data = mrdfits('hsi_spectrum_20020421_004040.fits‘, 0, header)
- headfits – Reads  header from an extension of a FITS file
- Example:  header = headfits('hsi_spectrum_20020421_004040.fits', exten=1)
- mwrfits – Writes an extension in a FITS file
- FITS object – Under construction
- $SSW/gen/fits directory contains many IDL tools to read/write FITS files
- _[Astronomy Library at GSFC documentation ](http://idlastro.gsfc.nasa.gov/fitsio.html)_on SSW FITS I/O
- _[FV](http://heasarc.gsfc.nasa.gov/docs/software/ftools/fv/)_ tool from HEASARC at GSFC
- Free software tool you can download
- Graphical interface for examining FITS files easily
- Allows for plotting of rows/columns in FITS files

## IDL> fits_info,'hsi_spectrum_20020421_004040.fits

- hsi_spectrum_20020421_004040.fits has 3 extensions
- Primary header: 26 records
- No data
- Extension 1 -- 'RATE    '           /
-                Header : 67 records
-                Binary Table ( 792 820 )
- Extension 2 -- 'ENEBAND '           /Extension name
-                Header : 52 records
-                Binary Table ( 970 1 )
- Extension 3 -- 'HESSI Spectral Object Parameters' /
-                Header : 300 records
-                Binary Table ( 173821 1 )

## IDL> data = mrdfits('hsi_spectrum_20020421_004040.fits', 1, header)

- MRDFITS: Binary table.  5 columns by  820 rows.
- IDL> help,data
- DATA            STRUCT    = -> <Anonymous> Array[820]
- IDL> help,data,/st
- ** Structure <3c6dce0>, 5 tags, length=800, data length=792, refs=1:
-    RATE            FLOAT     Array[97]
-    ERROR           FLOAT     Array[97]
-    LIVETIME        FLOAT          0.910374
-    TIME            DOUBLE           52385.028
-    TIMEDEL         FLOAT      4.62963e-005
- IDL> help, header
- HEADER          STRING    = Array[67]
- IDL> prstr, header

## XTENSION= 'BINTABLE'           /Written by IDL:  Mon Jul 12 10:42:49 2004       

- BITPIX  =                    8 /
- NAXIS   =                    2 /
- NAXIS1  =                  792 /Number of bytes per row
- NAXIS2  =                  820 /Number of rows
- PCOUNT  =                    0 /Random parameter count
- GCOUNT  =                    1 /Group count
- TFIELDS =                    5 /Number of columns
- COMMENT
- COMMENT  *** End of mandatory fields ***
- COMMENT
- DATE    = '2004-07-12'         /
- ORIGIN  = 'HESSI   '           /High Energy Solar Spectroscopic Imager
- OBSERVER= 'unknown '           /Usually the name of the user who generated file
- TELESCOP= 'HESSI   '           /High Energy Solar Spectroscopic Imager
- OBJECT  = 'Sun     '           /
- DATE_OBS= '2002-04-21T00:40:40.000' /
- DATE_END= '2002-04-21T01:35:20.000' /
- GEOAREA =              356.310 /
- DETUSED = 'SEGMENTS: 1F|2F|3F|4F|5F|6F|7F|8F|9F' /
- SUMFLAG =                    1 /Spectra  summed over detectors
- SUMCOINC=                    0 /
- COINCIDE=                    0 /Anti-coincident spectra
- RESPFILE= 'hsi_srm_20020421_004040.fits' /
- TIMESYS = 'MJD     '           /
- TIMEUNIT= 'd       '           /
- MJDREF  = '        '           /Undefined for HESSI.
- TIMEZERI=                52385 /
- TIMEZERF=          0.028240741 /
- ...
- ...

## New FITS object 

- Use is similar to RHESSI objects
- Use SET, GET, GETDATA to read FITS file
- Under construction – basics are available now, more methods will be added
- Example:
- o = fitsread( filename = 'test_cube_small.fits' )
- print,  o->getstatus()
- print, o-> getfield( extension =  1,  'cbe_det_eff$$avg' )
- o->set,  extension =  1
- print,  o->get( /extension )
- print, o->getdata(  /header )
- data = o->getdata()
- obj_destroy, o

## RHESSI Spectrum FITS files

- GUI:
- In the Spectrum Widget, set up your parameters, press the ‘Write Output File’ Button.  You’ll see this widget:
- CLI:
- Create and set parameters in a spectrum object and call filewrite method.  Options to filewrite are:
- /buildsrm – If set, write an SRM file in addition to the spectrum file
- /autoname – If set, autoname FITS files based on time of data
- all_simplify = 0, 1, 2, or 3. Specifies type of SRM to calculate:
- 0 =  full matrix
- 1 = off diagonal terms are an approximation
- 2 = diagonal terms only
- 3 = diagonal terms only and all are set to 1
- srmfile = name of SRM FITS file to write
- specfile = name of spectrum FITS file to write
- Example:  o -> filewrite, /buildsrm, /autoname, all_simplify=2

## RHESSI Spectrum FITS Files (cont)

- Spectrum and SRM FITS files are used as input to OSPEX and SPEX to proceed with spectroscopy analysis
- Detectors must be summed (sum_flag set to 1 in object) in FITS files for use in OSPEX, SPEX
- To analyze separate detectors, write a separate file for each detector (for now)
- Energy bins must be defined in terms of keV, not channel numbers, for use in OSPEX, SPEX
- SRM file will contain SRM for all attenuator states during spectrum time interval
- OSPEX will automatically choose the correct one for each fit time interval
- SPEX will only use first one (corresponding to attenuator state at start of spectrum time interval)
- Use hsi_break_srm to break up the SRM file into separate SRM files for each attenuator state for use in SPEX.
- No mechanism for using a FITS file to create a spectrum object currently

## IDL> fits_info,'hsi_srm_20020421_004040.fits'

- hsi_srm_20020421_004040.fits has 5 extensions
- Primary header: 12 records
- No data
- Extension 1 -- 'SPECRESP MATRIX'    /Extension name
-                Header : 61 records
-                Binary Table ( 402 107 )
- Extension 2 -- 'EBOUNDS '           /Extension name
-                Header : 49 records
-                Binary Table ( 1164 1 )
- Extension 3 -- 'SRM Object Parameters' /
-                Header : 95 records
-                Binary Table ( 2093 1 )
- Extension 4 -- 'SPECRESP MATRIX'    /Extension name
-                Header : 61 records
-                Binary Table ( 402 107 )
- Extension 5 -- 'SPECRESP MATRIX'    /Extension name
-                Header : 61 records
-                Binary Table ( 402 107 )

## IDL> srm1 = mrdfits('hsi_srm_20020421_004040.fits', 1, header1)

- MRDFITS: Binary table.  6 columns by  107 rows.
- IDL> help,srm1
- SRM             STRUCT    = -> <Anonymous> Array[107]
- IDL> help,srm1,/st
- ** Structure <3247e80>, 6 tags, length=404, data length=402, refs=1:
-    ENERG_LO        FLOAT           3.00000
-    ENERG_HI        FLOAT           4.00000
-    N_GRP           INT              1
-    F_CHAN          INT              0
-    N_CHAN          INT             97
-    MATRIX          FLOAT     Array[97]
- IDL> print,fxpar(header1, 'FILTER')
-            0
- IDL> srm4 = mrdfits('hsi_srm_20020421_004040.fits', 4, header4)
- MRDFITS: Binary table.  6 columns by  107 rows.
- IDL> print,fxpar(header4, 'FILTER')
-            1
- IDL> srm5 = mrdfits('hsi_srm_20020421_004040.fits', 5, header5)
- MRDFITS: Binary table.  6 columns by  107 rows.
- IDL> print,fxpar(header5, 'FILTER')
-            3

## RHESSI Image FITS files with GUI

- GUI:
- Writing Image FITS file
-   In the Image widget, select option to create FITS file when generating image
-   Select any RHESSI image panel in the GUI, and click File /Export Data / Write Fits file
- Reading Image FITS file
-   Click File / Import FITS file

## RHESSI Image FITS files with CLI

- Writing Image FITS Files
- Create an image object, set parameters, and call fitswrite method
- Example:  o -> fitswrite, fitsfile=‘xxx.fits’
- Currently for single images only, image cube requires use of hsi_multi_image object
- Reading Image FITS Files
- hsi_image_fitsread – returns image data, object, info/control parameters, plots images.  Many options.
- Example:  image = hsi_image_fitsread()
- hsi_fits2map – reads image file and creates an array of _[map structures](http://orpheus.nascom.nasa.gov/~zarro/idl/maps.html)_
- Example:  hsi_fits2map, fitsfile, map
- However:
-   New and improved image object software will be online very soon
-   New hsi_image will handle single image and image cube
-   New hsi_image will read data either from telemetry files or from an image FITS file

## OSPEX FITS Files

- OSPEX stores results of analysis in FITS files
- OSPEX GUI:
- Click File / Save Fit Results / In FITS file to write FITS file
- Click File / Import Fit Results to read FITS file
- OSPEX CLI:
- Use savefit method to write FITS file
- Example:  ospex_obj -> savefit
- Use restorefit method to restore import results in FITS file into OSPEX object
- Example:  ospex_obj -> restorefit
- Use spex_read_fit_results to read FITS file into structure
- Example:  structure = spex_read_fit_results(file)