Creating a Spectrum File Using the HESSI GUI

From RHESSI Wiki

(Difference between revisions)
Jump to: navigation, search
(Creating a Count Rate Spectrum File)
(Creating a RHESSI Spectra and Writing an Output File)
 
(18 intermediate revisions not shown)
Line 1: Line 1:
== Creating A Spectrum File with the HESSI GUI ==
== Creating A Spectrum File with the HESSI GUI ==
===Introduction===
===Introduction===
-
This writeup gives an example of how to create a RHESSI Spectrum file suitable for use in OSPEX analysis using the HESSI GUI. This is usually the first step doing spectroscopy using RHESSI data.
+
 
-
See [http://hesperia.gsfc.nasa.gov/~dennis/OSPEX/The_Basics/index.htm Ospex - The Basics] for an older version of the HESSI GUI Documentation. If you have already created a spectrum file go to [[OSPEX Documentation]] for a tutorial on fitting an interval.
+
[[Category:Software]]
 +
This writeup gives an example of how to create a RHESSI Spectrum file suitable for use in OSPEX analysis using the HESSI GUI. This is usually the first step when doing spectroscopy using RHESSI data.
 +
See [http://hesperia.gsfc.nasa.gov/~dennis/OSPEX/The_Basics/index.htm OSPEX - The Basics] for an older version of the HESSI GUI Documentation. A spectrum file and spectrometer response matrix (SRM) file can also be created for the front segment of each detector using the ssw routine for creating [http://beauty.nascom.nasa.gov/~zarro/php/ssw_print.php?file=$SSW/hessi/idl/spectra/hsi_spectrum_sep_det_files.pro separate detector files]. Examples of using this routine are in the header of the file. Command line instructions for creating the spectrum and SRM file are also given (indented in green in the document). For a complete list of all available control and information parameters see the [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/params/hsi_params_spectrum.htm spectrum parameters list]. If you have already created a spectrum file go to the [[OSPEX GUI Users Guide|OSPEX GUI User Guide]] for a tutorial on fitting an interval.
===Creating a Count Rate Spectrum File===
===Creating a Count Rate Spectrum File===
Start the HESSI GUI at the sswidl command line by typing:
Start the HESSI GUI at the sswidl command line by typing:
-
      <code>IDL>hessi </code>
+
'''<code>hessi </code>'''
The HESSI GUI start screen will appear. Select the 'File' drop down menu. The GUI should now appear as below.
The HESSI GUI start screen will appear. Select the 'File' drop down menu. The GUI should now appear as below.
[[Image:Hessi_gui_start.jpg|center|thumb|600px|The Hessi GUI start screen with File drop down menu]]
[[Image:Hessi_gui_start.jpg|center|thumb|600px|The Hessi GUI start screen with File drop down menu]]
-
From the file drop down menu choose the 'Select Observation Time Interval...' option. The 'Observation Time Interval Selection' GUI will pop up.
+
From the file drop down menu choose the '''Select Observation Time Interval...''' option. The 'Observation Time Interval Selection' GUI will pop up.
[[Image:obs_time_interval.jpg|center|thumb|600px|Pop up GUI to set time over which to create the spectrum file]]
[[Image:obs_time_interval.jpg|center|thumb|600px|Pop up GUI to set time over which to create the spectrum file]]
-
We can set the start and end times we would like to use by simply entering times in this widget or selecting 'Start' and entering times in the popup menu, then doing this again for the end time. Once we have selected our times we can plot the observing summary for the flare. In this example we have selected the flare on 21Apr2002 starting at 00:20:00 and continuing until 01:40:00. We can plot the observing summary in the main window by selecting the 'Plot Observing Summary Data' button. The observing summary should appear as below:  
+
We can set the start and end times we would like to use by entering times in this widget or selecting 'Start' and entering times in the resulting pop up menu, then doing this again for the end time. Once we have selected our times we can plot the observing summary for the flare. In this example we have selected the flare on 21Apr2002 starting at 00:20:00 and continuing until 01:40:00.  
 +
 
 +
We can plot the observing summary in the main window by selecting the 'Plot Observing Summary Data' button. The observing summary should appear as below:  
[[Image:obs_summary.jpg|center|thumb|600px|The observing Summary for the 21Apr2002 flare]]
[[Image:obs_summary.jpg|center|thumb|600px|The observing Summary for the 21Apr2002 flare]]
 +
 +
 +
::<span style="color:#009000">To setup the HESSI observing summary object and spectrum object from the command line:
 +
:::<span style="color:#009000">'''obs_obj = hsi_obs_summary()'''
 +
:::<span style="color:#009000">'''sp_obj = hsi_spectrum()'''
 +
::<span style="color:#009000">The RHESSI Command Line Snippets document contains additional information on manipulating the [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/software/rhessi_snippets.htm#Observing%20Summary Observing Summary Object ]  and the [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/software/rhessi_snippets.htm#Spectrum Spectrum Object]  from the command line.
 +
 +
::<span style="color:#009000">To set the observation time interval from the command line:
 +
:::<span style="color:#009000">'''obs_obj-> set, obs_time_interval= [' 21-Apr-2002 00:20:00.000', ' 21-Apr-2002 01:40:00.000']'''
 +
:::<span style="color:#009000">'''sp_obj-> set, obs_time_interval= [' 21-Apr-2002 00:20:00.000', ' 21-Apr-2002 01:40:00.000']'''
 +
::<span style="color:#009000">This sets the observation time in both the observing summary and spectrum objects.
 +
 +
::<span style="color:#009000">To plot the observing summary as a function of time from the command line:
 +
:::<span style="color:#009000">'''obs_obj-> plotman, /ylog'''
This is the standard time history for the flare of interest on 21 April 2002. Note that it is the summed counting rate of all the front and rear detector segments in counts s-1 detector-1.  The detailed markings in this plot are described in detail in Kim Tolbert's write up on [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/guides/obs_summ_plots.htm RHESSI Quicklook Light Curves]. The various changes in count rate with time in the different energy ranges are described in Brian Dennis' write up on [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/guides/lightcurve_artifacts.htm Artifacts in RHESSI Light Curves].
This is the standard time history for the flare of interest on 21 April 2002. Note that it is the summed counting rate of all the front and rear detector segments in counts s-1 detector-1.  The detailed markings in this plot are described in detail in Kim Tolbert's write up on [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/guides/obs_summ_plots.htm RHESSI Quicklook Light Curves]. The various changes in count rate with time in the different energy ranges are described in Brian Dennis' write up on [http://hesperia.gsfc.nasa.gov/ssw/hessi/doc/guides/lightcurve_artifacts.htm Artifacts in RHESSI Light Curves].
This count rate plot gives us very important information on the impulsive phase of the flare of interest. We see, for example, that RHESSI came out of nighttime at about 00:33 UT as indicated by the vertical blue dashed line but more accurately, by the rapid increase in the 3 - 6 and 6 - 12 keV count rates. This indicates that a flare was already going on at this time. Images show that it was at a different location than the flare of interest that began at about 00:39 UT. (Note that right clicking on the plot gives you the time at the cursor.) The horizontal purple line at the top of the plot labeled A0 indicates that all attenuators were out of the detector fields of view at this time. The counting rate at all energies up to 25 keV rose very rapidly until at about 00:48 UT the thin attenuators moved into the detector fields of view (as indicated by the purple line dropping to the A1 level); the rates below 25 keV dropped precipitously at this time. Thereafter, every 4 minutes, the thin attenuators were removed for 1-minute intervals to test the low energy rate from the flare. At about 01:30 UT, the thick attenuators were added to the thin attenuators in the detector fields of view (the A3 state as indicated on the purple line) and the rates up to 50 keV dropped precipitously.  Finally, at abut 01:33 UT, RHESSI went into night and the rates again fell to their non-solar background levels. Note that the rates up to 300 keV continued to climb as RHESSI entered the South Atlantic Anomaly (SAA) as indicated by the orange line marked with an "S" at the top of the plot. No data is recorded during passages through the most intense parts of the SAA to preserve space in the on-board memory.
This count rate plot gives us very important information on the impulsive phase of the flare of interest. We see, for example, that RHESSI came out of nighttime at about 00:33 UT as indicated by the vertical blue dashed line but more accurately, by the rapid increase in the 3 - 6 and 6 - 12 keV count rates. This indicates that a flare was already going on at this time. Images show that it was at a different location than the flare of interest that began at about 00:39 UT. (Note that right clicking on the plot gives you the time at the cursor.) The horizontal purple line at the top of the plot labeled A0 indicates that all attenuators were out of the detector fields of view at this time. The counting rate at all energies up to 25 keV rose very rapidly until at about 00:48 UT the thin attenuators moved into the detector fields of view (as indicated by the purple line dropping to the A1 level); the rates below 25 keV dropped precipitously at this time. Thereafter, every 4 minutes, the thin attenuators were removed for 1-minute intervals to test the low energy rate from the flare. At about 01:30 UT, the thick attenuators were added to the thin attenuators in the detector fields of view (the A3 state as indicated on the purple line) and the rates up to 50 keV dropped precipitously.  Finally, at abut 01:33 UT, RHESSI went into night and the rates again fell to their non-solar background levels. Note that the rates up to 300 keV continued to climb as RHESSI entered the South Atlantic Anomaly (SAA) as indicated by the orange line marked with an "S" at the top of the plot. No data is recorded during passages through the most intense parts of the SAA to preserve space in the on-board memory.
-
Once we have identified the flare for which we would like to create a spectrum file select the Set Obs Time and Close button at the lower left corner of the Observation Time Interval Selection GUI. To create the spectrum files access to the RHESSI data is necessary. In order to access the data, make sure you are online, then from the IDL command line type the following:
+
Once we have identified the flare for which we would like to create a spectrum file select the 'Set Obs Time and Close' button at the lower left corner of the Observation Time Interval Selection GUI. To create the spectrum files access to the RHESSI data is necessary. In order to access the data, make sure you are online, then from the IDL command line type the following:
-
<code>IDL>search_network, /enable</code>
+
'''<code>search_network, /enable</code>'''
-
When trying to create your spectrum file IDL will now try to automatically download all necessary data from an available RHESSI archive. The files are copied to a local directory specified by the user during setup of X-ray package in ssw.
+
When trying to create your spectrum file IDL will now try to automatically download all necessary data from an available RHESSI archive. The files are copied to a local directory specified by the user during setup of the X-ray package in the setup.hessi_env file.
-
To begin creating a spectrum file under the File drop down menu select '''Retrieve/Process Data ->''', from the menu that appears to the side of this select '''Spectrum...'''. The following GUI should appear:
+
To begin creating a spectrum file, under the File drop down menu select '''Retrieve/Process Data ->''', from the menu that appears to the side of this select '''Spectrum...'''. The following GUI should appear:
[[Image:Spectra.jpg|center|thumb|600px|Spectra GUI for creating RHESSI Spectrum files.]]
[[Image:Spectra.jpg|center|thumb|600px|Spectra GUI for creating RHESSI Spectrum files.]]
Line 33: Line 51:
Using this GUI we can set the the parameters for our spectrum file.
Using this GUI we can set the the parameters for our spectrum file.
-
The time set in the the Observation Time Interval GUI is already transferred to the Spectra GUI. We are allowed to specify a different time or select a Spectrum Time Interval directly below, which is different (though contained by the observation time interval).
+
The time set in the the Observation Time Interval GUI is transferred to the Spectra GUI. This time can be changed or a subset of it can be chosen as the Spectrum Time Interval in the portion of the GUI just below the Observation Time Interval.
===Setting Energy Bins===
===Setting Energy Bins===
-
Next we must choose the energy bins for our spectrum. In the Spectra GUI there are two options associated with selecting energy bins. We can select energy bins based on binning codes. Selecting a binning code automatically defines the energy bins used to create the spectrum file by a predetermined schema. The show binning codes button displays a listing of all available schema. The Define Bins Manually... button allows the user to set energy bins to any scheme they choose. The following GUI appears when the button is selected:
+
Next we must choose the energy bins for our spectrum. In the Spectra GUI there are two options associated with selecting energy bins. We can select energy bins based on binning codes. Selecting a binning code automatically defines the energy bins used to create the spectrum file by a predetermined schema. The show binning codes button displays a listing of all available schema.  
 +
The '''Define Bins Manually...''' button allows the user to set energy bins to any scheme they choose. The following GUI appears when the button is selected:
[[Image:Energy_intervals.jpg|center|thumb|600px|The Select Energy Intervals GUI allows the user to specify energy bins for creating a RHESSI spectrum file.]]
[[Image:Energy_intervals.jpg|center|thumb|600px|The Select Energy Intervals GUI allows the user to specify energy bins for creating a RHESSI spectrum file.]]
-
There are several options for available for selecting energy bins. The top two panels allow the user to edit a list of intervals by doing things such as deleting a current interval or adding a new interval to a preexisting list, defining the intervals graphically, or reading them from a text file. In most cases the easiest way to define intervals is using the bottom panel, Define Intervals Manually.  
+
There are several options for available for selecting energy bins. The top panels allow the user to edit a list of intervals by doing things such as deleting a current interval or adding a new interval to a preexisting list, defining the intervals graphically, or reading them from a text file. A very precise way to define intervals is using the bottom panel, 'Define Intervals Manually'.  
For instance a set of energy bins from 3keV to 300keV  with different size bins for different energy ranges can be defined as follows:
For instance a set of energy bins from 3keV to 300keV  with different size bins for different energy ranges can be defined as follows:
Line 59: Line 78:
**To the right of this choose 'Add to list'. The list of energy bands should now contain 1/3kev bands from 3.0keV to 15kev, 1keV bands from 15keV to 100keV, and 5kev bands from 100keV to 300keV
**To the right of this choose 'Add to list'. The list of energy bands should now contain 1/3kev bands from 3.0keV to 15kev, 1keV bands from 15keV to 100keV, and 5kev bands from 100keV to 300keV
*Select 'Accept' at the bottom right of the GUI. The energy bins are now set as defined and we are back at the 'Spectra' GUI
*Select 'Accept' at the bottom right of the GUI. The energy bins are now set as defined and we are back at the 'Spectra' GUI
 +
 +
 +
 +
::<span style="color:#009000">To set the energy bins from the command line in the spectrum object:
 +
:::<span style="color:#009000">'''sp_obj->set, sp_energy_binning = [[findgen(36)*.3333 + 3.0],[findgen(85) + 15.0],[findgen(41)*5.0 + 100.0]]'''
 +
::<span style="color:#009000">This requires some knowledge of manipulating arrays in IDL as we set up three arrays for our different size energy bins and concatenate them to cover the entire energy range from 3keV to 300keV.
===Setting Time Bins===
===Setting Time Bins===
Line 68: Line 93:
Once we have entered 4.0 next to D(s) select the 'Replace List' button to right. The drop down list at the top of the GUI should now show a series of 4sec time intervals starting at the beginning of the Observation Time Interval and ending at the end time. Select the 'Accept' button at the bottom left of the GUI. The time bins are set and we are back at the 'Spectra' GUI.
Once we have entered 4.0 next to D(s) select the 'Replace List' button to right. The drop down list at the top of the GUI should now show a series of 4sec time intervals starting at the beginning of the Observation Time Interval and ending at the end time. Select the 'Accept' button at the bottom left of the GUI. The time bins are set and we are back at the 'Spectra' GUI.
 +
 +
 +
 +
::<span style="color:#009000">To set the time bins in the spectrum object from the command line:
 +
:::<span style="color:#009000">'''sp_obj -> set, sp_time_interval = 4.0'''
 +
::<span style="color:#009000">This uses the observation interval set earlier and breaks it up into bins of the specified size (4sec).
===Selecting Detectors===
===Selecting Detectors===
Line 82: Line 113:
*Analysis Related Issues  
*Analysis Related Issues  
**We should consider the features of the spectrum we are interested in, and what energy ranges and resolution would best allow us to view them. For instance we want to select a detector that has good resolution down to ~6keV to view the Fe-Ni line feature at 6.7keV
**We should consider the features of the spectrum we are interested in, and what energy ranges and resolution would best allow us to view them. For instance we want to select a detector that has good resolution down to ~6keV to view the Fe-Ni line feature at 6.7keV
-
**In cases where we will need to use model components such as [[Drm mod - Pseudo function for fine tuning RHESSI DRM parameters|drm_mod]] or [[Pileup mod - Pseudo function for correcting pileup|pileup_mod]] we should only create single detector files since that is a requirement of these model components
+
**In cases where we will need to use model components such as [[Drm mod - Pseudo function for fine tuning RHESSI DRM parameters|drm_mod]] or [[Pileup mod - Pseudo function for correcting pileup|pileup_mod]] we should only create single detector files since that is a requirement for using these model components
-
To select our detectors select the 'Change' button in the 'Collimators and Detector Front/Rear Segments Selected' section of the GUI. A list of all collimators with a check box for the front and rear segment of each will appear. In this case we would like to create a spectrum file for the front segment of detector four. First choose the 'Disable All' button on the upper right of the GUI. All check boxes should be cleared. Simply select the check box for 4F at this point. Note the 'Sum Detectors' button on the right of GUI. When multiple detectors are selected this will allow the display of the spectra created to be viewed as the sum of all selected detectors. Now select the 'Accept' button. We have selected our detectors are back at the main 'Spectra' GUI.
+
To select our detectors select the 'Change' button in the 'Collimators and Detector Front/Rear Segments Selected' section of the GUI. A list of all collimators with a check box for the front and rear segment of each will appear. In this case we would like to create a spectrum file for the front segment of detector four. First choose the 'Disable All' button on the upper right of the GUI. All check boxes should be cleared. Select the check box for 4F at this point. Note the 'Sum Detectors' button on the right of GUI. When multiple detectors are selected this will allow the display of the spectra created to be viewed as the sum of all selected detectors. Now select the 'Accept' button. We have selected our detectors are back at the main 'Spectra' GUI.
 +
 
 +
::<span style="color:#009000">To select detectors for use in creating the spectrum object:
 +
:::<span style="color:#009000">'''sp_obj -> set, seg_index_mask= [0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]'''
 +
::<span style="color:#009000">Note the seg_index_mask sets which detectors and segments are used. The first nine entries are for the front segments, detectors 1 through 9, the second nine for the rear segments detectors 1 through 9. In this case detector 4F was selected.
===Spectral Units & Pulse Pileup, Decimation and XY Offset===  
===Spectral Units & Pulse Pileup, Decimation and XY Offset===  
Line 92: Line 127:
The last panel of the GUI allows to user to toggle between three options when creating the spectrum file. In order they are:
The last panel of the GUI allows to user to toggle between three options when creating the spectrum file. In order they are:
*The Pileup Correction - This can be toggled on or off. With the current analysis setup this is no longer used. In cases were the count rate is not high it is not necessary. In cases where pileup does occur it is accounted for during spectral analysis using OSPEX by the [[Pileup mod - Pseudo function for correcting pileup|pileup_mod]] component. Make sure this is not selected
*The Pileup Correction - This can be toggled on or off. With the current analysis setup this is no longer used. In cases were the count rate is not high it is not necessary. In cases where pileup does occur it is accounted for during spectral analysis using OSPEX by the [[Pileup mod - Pseudo function for correcting pileup|pileup_mod]] component. Make sure this is not selected
-
*The Decimation Correction - This should be selected in almost every case. The decimation correction is then implemented when creating the count flux spectra, accounting for the loss of photons below the upper threshold energies
+
*The Decimation Correction - This should be selected in almost every case. The decimation correction is then implemented when creating the count flux spectra, accounting for the loss of photons below the upper threshold energies when count rates are high, as specified in the decimation algorithm.
*The XY Offset from the sun center can be chosen in two ways. In most cases it can be read automatically from the flare catalog. If this dose not have sufficient accuracy for your analysis the 'Get XY Offset from flare catalog' option can be unchecked and the position entered manually in the X and Y boxes below this in arcseconds from the Sun center
*The XY Offset from the sun center can be chosen in two ways. In most cases it can be read automatically from the flare catalog. If this dose not have sufficient accuracy for your analysis the 'Get XY Offset from flare catalog' option can be unchecked and the position entered manually in the X and Y boxes below this in arcseconds from the Sun center
Once these selections are done select 'Accept' at the bottom. we are back at the 'Spectra' GUI.
Once these selections are done select 'Accept' at the bottom. we are back at the 'Spectra' GUI.
 +
 +
::<span style="color:#009000">These parameters can be set in the spectrum object as follows:
 +
:::<span style="color:#009000">'''sp_obj-> set, pileup_correct = 0''' Turns the pileup correction off
 +
:::<span style="color:#009000">'''sp_obj-> set, decimation_corect = 1''' Turns decimation correction on for the front segments
 +
:::<span style="color:#009000">'''sp_obj-> set, use_flare_xyoffset = 1''' Uses the XY Offset from the flare catalog
 +
::<span style="color:#009000">Note that the settings used above are the default settings for these control parameters.
===Creating a RHESSI Spectra and Writing an Output File===
===Creating a RHESSI Spectra and Writing an Output File===
-
We are now ready to create a RHESSI spectrum. In this case it will be for the flare on 21Apr2002 from 00:20:00UT to 01:40:00UT, using detector 4F, with our bins set as above. To create the spectrum select the 'Plot Spectrum' button in the lower left of the Spectra GUI. Depending on the count rate, number of energy bins, and number of time bins you should shortly see a RHESSI spectrum.
+
We are now ready to create a RHESSI spectrum and SRM file. In this case it will be for the flare on 21Apr2002 from 00:20:00UT to 01:40:00UT, using detector 4F, with our bins set as above. To create the spectrum select the 'Plot Spectrum' button in the lower left of the Spectra GUI. Depending on the count rate, number of energy bins, and number of time bins you should shortly see a RHESSI spectrum.
[[Image:Spectra_energy_time.jpg|center|thumb|600px|The RHESSI Spectrum as a function of energy (top panel). The RHESSI spectrum as a function of time (bottom panel). Both are for a single detector (4F) with other parameters specified in the HESSI Spectra GUI.]]
[[Image:Spectra_energy_time.jpg|center|thumb|600px|The RHESSI Spectrum as a function of energy (top panel). The RHESSI spectrum as a function of time (bottom panel). Both are for a single detector (4F) with other parameters specified in the HESSI Spectra GUI.]]
Line 104: Line 145:
The RHESSI spectrum should appear as above, the spectrum is accumulated as a function of energy using the 'Plot Spectrum' button. The 'Plot Time History' button will display it as a function of time.
The RHESSI spectrum should appear as above, the spectrum is accumulated as a function of energy using the 'Plot Spectrum' button. The 'Plot Time History' button will display it as a function of time.
-
Now we are ready to write the output file. The files are written as .fits files which are readable by OSPEX. Select the 'Write Output File...' button at the lower right of the 'Spectra' GUI. A GUI appears with a drop down menu listing the various options for writing the Spectrum Matrix Response (SRM) file. This file accounts for detector and attenuator effects when converting from the count flux spectrum to the photon flux spectrum. Every RHESSI spectrum file should have any accompanying SRM file. In most cases we will want to select 'Full calculation of diagonal, off diagonal terms', as this gives the most accurate transformation of the spectrum from count flux to photon flux. The other two options give increasingly simpler approximations of the SRM matrix and should only be used if time or computing power is limited.
+
::<span style="color:#009000">From the command line we accumulate and plot the data in  a plotman window as follows:
-
Once we have made and accepted our selection we can name our SRM file and place it in a directory, then do the same with the RHESSI spectrum file.  
+
:::<span style="color:#009000">'''<code>sp_obj->set, sp_data_unit = 'flux'</code>'''
 +
:::<span style="color:#009000">'''<code>sp_obj->plotman</code>'''
 +
:::<span style="color:#009000">'''<code>sp_obj->plotman, /pl_time, /dim1_sum</code>'''
 +
::<span style="color:#009000">The first line sets the units to return our data. The second creates and plots the spectrum as a function of energy. This usually will take some time the first time it is done. The last plots the spectrum as a function of time with the count flux for all energies summed.
-
Our files are saved and we are now ready to analyze the data as described in [[OSPEX Documentation]].  
+
Now we are ready to write the output file. The files are written as .fits files which are readable by OSPEX. Select the 'Write Output File...' button at the lower right of the 'Spectra' GUI. A GUI appears with a drop down menu listing the various options for writing the Spectrum Matrix Response (SRM) file. This file accounts for detector and attenuator effects when converting from the count flux spectrum to the photon flux spectrum. Every RHESSI spectrum file should have any accompanying SRM file. In most cases we will want to select 'Full calculation of diagonal, off diagonal terms', as this gives the most accurate transformation of the spectrum from count flux to photon flux. The other two options give increasingly simpler approximations of the SRM matrix and should only be used if time or computing power is limited. The following widget appears:
 +
[[File:Write spec file.jpg|center|thumb|300px|The widget for writing a RHESSI fits file and SRM file. In its current setup it will automatically name both files, including the date and time selected in the name, create a full SRM file (the preferred option), and place them in your current working directory]]
 +
   
 +
Once we have made and accepted our selection we can name our SRM file and place it in a directory, then do the same with the RHESSI spectrum file. This is not necessary if we select the option to automatically name the files (recommended).
 +
::<span style="color:#009000">From the command line we can write the file as follows:
 +
:::<span style="color:#009000">'''sp_obj -> filewrite, /buildsrm, all_simplify = 0'''
 +
::<span style="color:#009000">Note that this creates a full version of the SRM and automatically names and saves the srm .fits file and the spectrum .fits file in your current working directory. There are other keywords that can be used with filewrite as well such as  /namedialog to use the widget for naming output files or the files can be named explicitly using srmfile = 'xxx.fits' and specfile = 'xxx.fits'
 +
Our files are saved and we are now ready to analyze the data as described in the [[OSPEX GUI Users Guide|OSPEX GUI User Guide]]. 
-
[STILL UNDER CONSTRUCTION]
 
-
[[Category:Software]]
+
Contact [mailto:andy.gopie@nasa.gov Andy Gopie] with any questions or requests for additions

Latest revision as of 22:11, 15 December 2010

Contents

Creating A Spectrum File with the HESSI GUI

Introduction

This writeup gives an example of how to create a RHESSI Spectrum file suitable for use in OSPEX analysis using the HESSI GUI. This is usually the first step when doing spectroscopy using RHESSI data. See OSPEX - The Basics for an older version of the HESSI GUI Documentation. A spectrum file and spectrometer response matrix (SRM) file can also be created for the front segment of each detector using the ssw routine for creating separate detector files. Examples of using this routine are in the header of the file. Command line instructions for creating the spectrum and SRM file are also given (indented in green in the document). For a complete list of all available control and information parameters see the spectrum parameters list. If you have already created a spectrum file go to the OSPEX GUI User Guide for a tutorial on fitting an interval.

Creating a Count Rate Spectrum File

Start the HESSI GUI at the sswidl command line by typing:

hessi

The HESSI GUI start screen will appear. Select the 'File' drop down menu. The GUI should now appear as below.

The Hessi GUI start screen with File drop down menu

From the file drop down menu choose the Select Observation Time Interval... option. The 'Observation Time Interval Selection' GUI will pop up.

Pop up GUI to set time over which to create the spectrum file

We can set the start and end times we would like to use by entering times in this widget or selecting 'Start' and entering times in the resulting pop up menu, then doing this again for the end time. Once we have selected our times we can plot the observing summary for the flare. In this example we have selected the flare on 21Apr2002 starting at 00:20:00 and continuing until 01:40:00.

We can plot the observing summary in the main window by selecting the 'Plot Observing Summary Data' button. The observing summary should appear as below:

The observing Summary for the 21Apr2002 flare


To setup the HESSI observing summary object and spectrum object from the command line:
obs_obj = hsi_obs_summary()
sp_obj = hsi_spectrum()
The RHESSI Command Line Snippets document contains additional information on manipulating the Observing Summary Object and the Spectrum Object from the command line.
To set the observation time interval from the command line:
obs_obj-> set, obs_time_interval= [' 21-Apr-2002 00:20:00.000', ' 21-Apr-2002 01:40:00.000']
sp_obj-> set, obs_time_interval= [' 21-Apr-2002 00:20:00.000', ' 21-Apr-2002 01:40:00.000']
This sets the observation time in both the observing summary and spectrum objects.
To plot the observing summary as a function of time from the command line:
obs_obj-> plotman, /ylog

This is the standard time history for the flare of interest on 21 April 2002. Note that it is the summed counting rate of all the front and rear detector segments in counts s-1 detector-1. The detailed markings in this plot are described in detail in Kim Tolbert's write up on RHESSI Quicklook Light Curves. The various changes in count rate with time in the different energy ranges are described in Brian Dennis' write up on Artifacts in RHESSI Light Curves. This count rate plot gives us very important information on the impulsive phase of the flare of interest. We see, for example, that RHESSI came out of nighttime at about 00:33 UT as indicated by the vertical blue dashed line but more accurately, by the rapid increase in the 3 - 6 and 6 - 12 keV count rates. This indicates that a flare was already going on at this time. Images show that it was at a different location than the flare of interest that began at about 00:39 UT. (Note that right clicking on the plot gives you the time at the cursor.) The horizontal purple line at the top of the plot labeled A0 indicates that all attenuators were out of the detector fields of view at this time. The counting rate at all energies up to 25 keV rose very rapidly until at about 00:48 UT the thin attenuators moved into the detector fields of view (as indicated by the purple line dropping to the A1 level); the rates below 25 keV dropped precipitously at this time. Thereafter, every 4 minutes, the thin attenuators were removed for 1-minute intervals to test the low energy rate from the flare. At about 01:30 UT, the thick attenuators were added to the thin attenuators in the detector fields of view (the A3 state as indicated on the purple line) and the rates up to 50 keV dropped precipitously. Finally, at abut 01:33 UT, RHESSI went into night and the rates again fell to their non-solar background levels. Note that the rates up to 300 keV continued to climb as RHESSI entered the South Atlantic Anomaly (SAA) as indicated by the orange line marked with an "S" at the top of the plot. No data is recorded during passages through the most intense parts of the SAA to preserve space in the on-board memory.

Once we have identified the flare for which we would like to create a spectrum file select the 'Set Obs Time and Close' button at the lower left corner of the Observation Time Interval Selection GUI. To create the spectrum files access to the RHESSI data is necessary. In order to access the data, make sure you are online, then from the IDL command line type the following:

search_network, /enable

When trying to create your spectrum file IDL will now try to automatically download all necessary data from an available RHESSI archive. The files are copied to a local directory specified by the user during setup of the X-ray package in the setup.hessi_env file.

To begin creating a spectrum file, under the File drop down menu select Retrieve/Process Data ->, from the menu that appears to the side of this select Spectrum.... The following GUI should appear:

Spectra GUI for creating RHESSI Spectrum files.

Using this GUI we can set the the parameters for our spectrum file.

The time set in the the Observation Time Interval GUI is transferred to the Spectra GUI. This time can be changed or a subset of it can be chosen as the Spectrum Time Interval in the portion of the GUI just below the Observation Time Interval.

Setting Energy Bins

Next we must choose the energy bins for our spectrum. In the Spectra GUI there are two options associated with selecting energy bins. We can select energy bins based on binning codes. Selecting a binning code automatically defines the energy bins used to create the spectrum file by a predetermined schema. The show binning codes button displays a listing of all available schema. The Define Bins Manually... button allows the user to set energy bins to any scheme they choose. The following GUI appears when the button is selected:

The Select Energy Intervals GUI allows the user to specify energy bins for creating a RHESSI spectrum file.

There are several options for available for selecting energy bins. The top panels allow the user to edit a list of intervals by doing things such as deleting a current interval or adding a new interval to a preexisting list, defining the intervals graphically, or reading them from a text file. A very precise way to define intervals is using the bottom panel, 'Define Intervals Manually'.

For instance a set of energy bins from 3keV to 300keV with different size bins for different energy ranges can be defined as follows:


To set the energy bins from the command line in the spectrum object:
sp_obj->set, sp_energy_binning = [[findgen(36)*.3333 + 3.0],[findgen(85) + 15.0],[findgen(41)*5.0 + 100.0]]
This requires some knowledge of manipulating arrays in IDL as we set up three arrays for our different size energy bins and concatenate them to cover the entire energy range from 3keV to 300keV.

Setting Time Bins

Next we will set the time bins for the spectrum file. The simplest way to do this is to select the 'Define Bins Manually...' button in the Time Bins section of the Spectra GUI. The GUI that appears is similar to 'Select Energy Intervals' GUI, analogously titled 'Select Time Intervals'. The start and end times shown in the bottom third of the GUI below 'Define Intervals Manually below' should be the same as the Observation Times you set earlier. In most cases we want our time bins to be equal for the entire length of time for which we will create our spectra so we simply need to select the duration of our time bins. Select 'Divide this time range into intervals of length D'. Now next to the D(s) below this we can enter the time of each bin. RHESSI has a spin rotation of approximately 4s. In most cases we will want to create our spectra with bins of this size for the following reasons:

Once we have entered 4.0 next to D(s) select the 'Replace List' button to right. The drop down list at the top of the GUI should now show a series of 4sec time intervals starting at the beginning of the Observation Time Interval and ending at the end time. Select the 'Accept' button at the bottom left of the GUI. The time bins are set and we are back at the 'Spectra' GUI.


To set the time bins in the spectrum object from the command line:
sp_obj -> set, sp_time_interval = 4.0
This uses the observation interval set earlier and breaks it up into bins of the specified size (4sec).

Selecting Detectors

When selecting which detectors we will use to create a spectrum file there are a list of things to consider, some having to do with the detector performance, some with the actual event we are looking at, and some with how we are planning to analyze it. Things we should consider are as follows:

To select our detectors select the 'Change' button in the 'Collimators and Detector Front/Rear Segments Selected' section of the GUI. A list of all collimators with a check box for the front and rear segment of each will appear. In this case we would like to create a spectrum file for the front segment of detector four. First choose the 'Disable All' button on the upper right of the GUI. All check boxes should be cleared. Select the check box for 4F at this point. Note the 'Sum Detectors' button on the right of GUI. When multiple detectors are selected this will allow the display of the spectra created to be viewed as the sum of all selected detectors. Now select the 'Accept' button. We have selected our detectors are back at the main 'Spectra' GUI.

To select detectors for use in creating the spectrum object:
sp_obj -> set, seg_index_mask= [0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
Note the seg_index_mask sets which detectors and segments are used. The first nine entries are for the front segments, detectors 1 through 9, the second nine for the rear segments detectors 1 through 9. In this case detector 4F was selected.

Spectral Units & Pulse Pileup, Decimation and XY Offset

Next we must select the units we want our spectra in. In most cases we want to check the count flux option this will display our data in units of counts*cm-2sec-1keV-1. The result will also be corrected for detector dead time and decimation effects. In this same section of the GUI there is 'Change Flags' button on the right. Selecting this will display a menu of options for various properties that can be displayed when the spectrum file is created in the HESSI GUI main window. These can be chosen by the user according to their preferences. They are explained in RHESSI Quicklook Light Curves document.

The last panel of the GUI allows to user to toggle between three options when creating the spectrum file. In order they are:

Once these selections are done select 'Accept' at the bottom. we are back at the 'Spectra' GUI.

These parameters can be set in the spectrum object as follows:
sp_obj-> set, pileup_correct = 0 Turns the pileup correction off
sp_obj-> set, decimation_corect = 1 Turns decimation correction on for the front segments
sp_obj-> set, use_flare_xyoffset = 1 Uses the XY Offset from the flare catalog
Note that the settings used above are the default settings for these control parameters.

Creating a RHESSI Spectra and Writing an Output File

We are now ready to create a RHESSI spectrum and SRM file. In this case it will be for the flare on 21Apr2002 from 00:20:00UT to 01:40:00UT, using detector 4F, with our bins set as above. To create the spectrum select the 'Plot Spectrum' button in the lower left of the Spectra GUI. Depending on the count rate, number of energy bins, and number of time bins you should shortly see a RHESSI spectrum.

The RHESSI Spectrum as a function of energy (top panel). The RHESSI spectrum as a function of time (bottom panel). Both are for a single detector (4F) with other parameters specified in the HESSI Spectra GUI.

The RHESSI spectrum should appear as above, the spectrum is accumulated as a function of energy using the 'Plot Spectrum' button. The 'Plot Time History' button will display it as a function of time.

From the command line we accumulate and plot the data in a plotman window as follows:
sp_obj->set, sp_data_unit = 'flux'
sp_obj->plotman
sp_obj->plotman, /pl_time, /dim1_sum
The first line sets the units to return our data. The second creates and plots the spectrum as a function of energy. This usually will take some time the first time it is done. The last plots the spectrum as a function of time with the count flux for all energies summed.

Now we are ready to write the output file. The files are written as .fits files which are readable by OSPEX. Select the 'Write Output File...' button at the lower right of the 'Spectra' GUI. A GUI appears with a drop down menu listing the various options for writing the Spectrum Matrix Response (SRM) file. This file accounts for detector and attenuator effects when converting from the count flux spectrum to the photon flux spectrum. Every RHESSI spectrum file should have any accompanying SRM file. In most cases we will want to select 'Full calculation of diagonal, off diagonal terms', as this gives the most accurate transformation of the spectrum from count flux to photon flux. The other two options give increasingly simpler approximations of the SRM matrix and should only be used if time or computing power is limited. The following widget appears:

The widget for writing a RHESSI fits file and SRM file. In its current setup it will automatically name both files, including the date and time selected in the name, create a full SRM file (the preferred option), and place them in your current working directory

Once we have made and accepted our selection we can name our SRM file and place it in a directory, then do the same with the RHESSI spectrum file. This is not necessary if we select the option to automatically name the files (recommended).


From the command line we can write the file as follows:
sp_obj -> filewrite, /buildsrm, all_simplify = 0
Note that this creates a full version of the SRM and automatically names and saves the srm .fits file and the spectrum .fits file in your current working directory. There are other keywords that can be used with filewrite as well such as /namedialog to use the widget for naming output files or the files can be named explicitly using srmfile = 'xxx.fits' and specfile = 'xxx.fits'

Our files are saved and we are now ready to analyze the data as described in the OSPEX GUI User Guide.


Contact Andy Gopie with any questions or requests for additions

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox