Some Tohban-Useful IDL routines

Note that all of this assumes that you are logged on to one of the RHESSI machines here at SSL with SSW available.

Hsi_qlook_packet_rate

This object is part of the RHESSI quicklook data, and contains the packet rate in packets/second for the different App_ids. This is useful in finding data gaps for the different types of data. Note that the RHESSI data comes from the ground station in two types of file VC1 (for instrumental stuff) and VC3 (science).

obj = hsi_qlook_packet_rate(obs_time_interval = ['6-aug-2002 00:00', '7-aug-2002 00:00'])
data = obj -> getdata()

To Plot:

obj -> plot, app_id = 100

plots app_id = 100 (event packets). Here is a list of the different app_ids commonly seen in the data:

1:  State-of-Health (from VC1 files)
100: Events from detectors, this is "science data" containing photons for the detectors with times.
101: Fast Rate packets, these are usually turned off
102: Monitor rate data
152: Monitor rates from VC1 files (typically monitor rates come with VC3)
154: PMTRAS data (Unlike the RAS-SAS data, this comes in VC1 files)
200, 201, 210, 211, 212, 213, 214, 215, 220, 230, 231, 240, 250, 251, 252,
 253, 254, 255, 260, 261, 270, 272, 273, 274, 280, 290, 291: ADP (Aspect Data) packets.

You can also get the packet_rate for a given app_id using the IDL routine HSI_NPAK_HISTOGRAM: This does not use the qlook packet rate, but reads directly from Level 0 data, so it is somewhat slower.

 NAME:
       HSI_NPAK_HISTOGRAM
 PURPOSE: 
       returns, and optionally plots packet rate
 CALLING SEQUENCE: 
       histo=hsi_npak_histogram(time_range, tim_arr, app_id=app_id, $
            plot=plot, dt=dt, sum=sum, all=all)
 INPUTS:
       time_range=the time range desired, it is a good idea to be
       sure that the time_range is an integral multiple of the value
       of dt used, (dt default is 300 sec -- 5 minutes)
 OUTPUTS:
       histo=a histogram of the packet rate for the given app_id for
       the input time range, UNITS=packets/minute
       tim_arr= a time array for plotting, tim_arr is the center time
       for the bins of the histogram
 KEYWORDS: 
       app_id= the app_id for the packet, the default is app_id=100
       this can be a vector, although it's not a good idea for too
       many app_ids to be passed in if /plot is set
       dt= bin size for histogram in seconds, the default is 300
       seconds, see also the above comment for time_range
       plot= if set, will plot the histograms, on the screen and in a
       postscript file
       'hsi_npak_histogram_yyyymmdd_hhmmss_yyyymmdd_hhmmss.ps ' where
       the dates refer to the start and end times
       all= if set, use all app_ids, and sum them
       sum= if set, produce 1 histogram with the sum of the
       histograms for the input app_ids
       adp= if set, use all of the valid aspect app_ids
       tbl = output the packet table

How to Access the SOH data

There is now an IDL routine to make it a bit easier to get information from the vc1 packets. This should work for getting read and write pointers, etc. It's called hsi_any_sohdata, here's an example:

 data=hsi_any_sohdata(['6-aug-2002 08:00', '6-aug-2002 09:00'],$
                      time_array=tim_arr, soh_label='ISC_SSR')

This will return the SSR fill level for the given time range, with a time array (seconds from 1-jan-1979). You can get different data by passing in the appropriate name using the soh_label keyword.,

The labels are listed on the App_id=1 packet map. Go to: http://hessi.ssl.berkeley.edu/hessidata/metadata/hsi_1day_sohdata/app0001.html.

To plot, set the plot kewyword


data=hsi_any_sohdata(['6-aug-2002 08:00', '6-aug-2002 09:00'],$
                      time_array=tim_arr, soh_label='TSSCURWRTPTR', /plot)

This will plot the write pointer position as a function of time.

If you're hessiops, you need to be on sunny, and you need to source ~/setup_ssw, then call sswidl to start up IDL before you can do this.

The stored SOH data in the vc1 files typically appears about 10-20 minutes after the end of a given pass (for BGS or WLP passes, anyway). It doesn't go directly to the data archive, until the Quicklook data is finished processing. If for some reason you cannot get the data, be sure that the environmental variable HSI_DATA_USER is set to /disks/sunny/home/raid_queue in your setup.hessi_env file. Or in SSWIDL do:

set_logenv, 'HSI_DATA_USER', '/disks/sunny/home/raid_queue'
temp = hessi_data_paths(/reset)

If you're not at SSL, then you'll need to wait until the data shows up in your local archive.

The Hsi_obs_summ_flag Object

This object is part of the Rhessi quicklook data, and contains all sorts of information:

obs_summ_flag_obj = hsi_obs_summ_flag(obs_time_interval = '6-aug-2002 '+['8:00', '9:00'])
flag_data = obs_summ_flag_obj -> getdata()
saa_flag = obs_summ_flag_obj -> get(flag_name = 'saa_flag')

This returns a byte array with the SAA flag, set to 1 for SAA periods. If you want a plot, use the plot method.

obs_summ_flag_obj -> plot, flag_name = 'ATTENUATOR_STATE'

This will put up a plot of the attenuator state for the given time interval.

The different data flags are as follows (as of 22-Jun-2012):

                ['SAA_FLAG', $ ;1 for SAA, from orbit data
                 'ECLIPSE_FLAG', $ ;1 for Eclipse, 0 for sunlight, from orbit data
                 'FLARE_FLAG', $ ;1 for flare
                 'IDPU_CONTROL', $ ;IDPU version control number
                 'CRYOCOOLER_POWER', $ ;average for 4 sec interval
                 'COLD_PLATE_TEMP', $ ;average for 4 sec interval
                 'FRONT_RATIO_1225', $ ;Front counts /(front+rear), flare diagnostic, 12 to 25 keV
                 'COLD_PLATE_SUPPLY', $ ;percent on for 4 sec interval
                 'HV28_SUPPLY', $ ;percent on for 4 sec interval
                 'ACTUATOR_SUPPLY', $ ;percent on for 4 sec interval
                 'FAST_HOUSEKEEPING', $ ;percent on for 4 sec interval
                 'SC_TRANSMITTER', $ ;(may affect detector 8), percent on for 4 sec interval
                 'SC_IN_SUNLIGHT', $ ;percent on for 4 sec interval, from packets
                 'SSR_STATE', $ ;0-8 SSR fill level, average for 4 sec interval
                 'ATTENUATOR_STATE', $ ;0,1,2,3, average for 4 sec interval
                 'FRONT_RATIO', $ ;Front counts /(front+rear), flare diagnostic
                 'POSSIBLE_FLARE', $ ;set to 1 for an event which sows up in front detectors, but no position
                 'GAP_FLAG', $ ;1 if no count rate data
                 'DECIMATION_ENERGY', $ ;energy channel upper limit for decimation
                 'DECIMATION_WEIGHT', $ ;decimation multiplier true_rate=weight*obs_rate
                 'MAX_DET_VS_TOT', $ ;fraction of counts in 1 detector,to rule out 1 detector flares
                 'NMZ_FLAG', $ ;Set to 1 if in North High-latitude Magnetic Zone
                 'SMZ_FLAG', $ ;Set to 1 if in South High-latitude Magnetic Zone
                 'AAZ_FLAG', $ ;Set to 1 if in the Atmospheric Absorption Zone
                 'PARTICLE_FLAG', $ ;Set to 1 for a Particle Event
                 'REAR_DEC_CHAN/128', $ ;Channel (divided by 128) below which rear decimation is set
		 'PARTSTORM', $ ;Particle flag used for onboard determination for rear decimation 
		 'HLAT', $ ;High Latitude flag used for onboard determination for rear decimation 
		 'ECLIPSE_EXT', $ ;Eclipse flag used for onboard determination for rear decimation
		 'FRONTS_OFF', $ ;Set to 1 if front dectectors are turned off
		 'BAD_PACKETS'] ;Set to 1 if bad packets are present in this 4 second interval

See The documentation for the RHESSI Quicklook data for more useful objects. Note that these flags are mostly gotten from VC3 packets, so that this information may be a 1 or even 2 days behind the SOH data.

HSI_GET_ORBIT_INFO

This routine returns a string array containing the orbit, eclipse, SAA and Magnetic zone data for the input time range:


data = hsi_get_orbit_info('24-aug-2002 '+['0:00', '8:00'], /list)

Returns:

TIMES IN SUNLIGHT: 
2002-08-24T00:00:00.000Z -- 2002-08-24T00:58:27.000Z
2002-08-24T01:28:24.000Z -- 2002-08-24T02:34:52.000Z
2002-08-24T03:04:46.000Z -- 2002-08-24T04:11:17.000Z
2002-08-24T04:41:08.000Z -- 2002-08-24T05:47:42.000Z
2002-08-24T06:17:30.000Z -- 2002-08-24T07:24:07.000Z
2002-08-24T07:53:53.000Z -- 2002-08-24T09:00:32.000Z
TIMES IN SAA:  NONE
TIMES IN AAZ: 
2002-08-24T00:58:03.000Z -- 2002-08-24T00:58:35.000Z
2002-08-24T01:28:16.000Z -- 2002-08-24T01:28:48.000Z
2002-08-24T02:34:28.000Z -- 2002-08-24T02:35:00.000Z
2002-08-24T03:04:38.000Z -- 2002-08-24T03:05:10.000Z
2002-08-24T04:10:52.000Z -- 2002-08-24T04:11:25.000Z
2002-08-24T04:41:01.000Z -- 2002-08-24T04:41:33.000Z
2002-08-24T05:47:17.000Z -- 2002-08-24T05:47:50.000Z
2002-08-24T06:17:23.000Z -- 2002-08-24T06:17:55.000Z
2002-08-24T07:23:42.000Z -- 2002-08-24T07:24:15.000Z
2002-08-24T07:53:45.000Z -- 2002-08-24T07:54:17.000Z
TIMES IN NMZ: 
2002-08-24T01:07:37.000Z -- 2002-08-24T01:17:11.000Z
2002-08-24T02:43:50.000Z -- 2002-08-24T02:59:00.000Z
2002-08-24T04:20:06.000Z -- 2002-08-24T04:40:51.000Z
2002-08-24T05:56:19.000Z -- 2002-08-24T06:23:38.000Z
2002-08-24T07:32:33.000Z -- 2002-08-24T08:00:00.000Z
TIMES IN SMZ: 
2002-08-24T00:22:06.000Z -- 2002-08-24T00:37:44.000Z
2002-08-24T01:58:18.000Z -- 2002-08-24T02:19:59.000Z
2002-08-24T03:34:34.000Z -- 2002-08-24T03:59:37.000Z
2002-08-24T05:10:47.000Z -- 2002-08-24T05:35:51.000Z
2002-08-24T06:47:01.000Z -- 2002-08-24T07:12:06.000Z

Note that the env variable HSI_FDF_DIR must be set to the directory with the orbit data archive: /disks/sunny/home/workdir/SatTrack

HSI_SSR_FILL_PER_ORBIT

This routine returns the difference in SSR fill for a given RHESSI orbit, it can be used with either a time input or an orbit number. E.g,

ppp = hsi_ssr_fill_per_orbit('25-aug-2002 0:00')

Returns

ORBIT NUMBER:         2993
TIME_RANGE: 2002-08-24T23:25:57.000Z -- 2002-08-25T01:02:11.000Z
SSR FILL AT START:       38.8080
SSR FILL AT END:       41.5520
SSR_DIFF:       2.74400
SUNLIGHT_FRACTION:      0.695185
SAA_FRACTION:       0.00000
MZ_FRACTION:      0.236231
GOES AVG: C1.4
GOES_FRACTION ABOVE A, B, C, M, X
     1.000     1.000     1.000     0.000     0.000
AVG ATTENUATOR_STATE:       1.00000
ATTENUATOR FRACTION IN STATES 0, 1, 3
     0.000     1.000     0.000

All of the outputs printed are available via keyword. Note that the attenuator state, and fraction of time in the given attenuator states are obtained from the obs_summ_flag object, which uses vc3 data, which lags behind the vc1 data. This is being worked on. If you know the orbit number, pass it in using the orbit_in keyword: then the time passed in is ignored, and replaced by a time for that orbit.

ppp = hsi_ssr_fill_per_orbit(orbit_in=2788)

Returns:

ORBIT NUMBER:         2788
TIME_RANGE: 2002-08-11T06:36:34.000Z -- 2002-08-11T08:12:49.000Z
SSR FILL AT START:       21.1680
SSR FILL AT END:       23.9120
SSR_DIFF:       2.74400
SUNLIGHT_FRACTION:      0.630996
SAA_FRACTION:       0.00000
MZ_FRACTION:      0.314459
GOES AVG: C1.0
GOES_FRACTION ABOVE A, B, C, M, X
     1.000     1.000     0.452     0.000     0.000
AVG ATTENUATOR_STATE:       0.00000
ATTENUATOR FRACTION IN STATES 0, 1, 3
     1.000     0.000     0.000

The ouput ppp is the change in fill level for that orbit. The fractions are the fraction of time for that orbit that was in the appropriate state, so orbit 2788 had 63.1% sunlught, no SAA, 31% high magnetic latitude. The average GOES level was C1.0; the GOES level was above A and B level the entire orbit, but only above C level for 45.2% of the orbit. The attenuator was in state 0 for the entire orbit.

Monitor Rates

Monitor rates can be accessed using the HSI_MONITOR_RATE object.

obj = hsi_monitor_rate(obs_time_interval = '6-aug-2002 '+['02:00','04:00'])
data = obj -> getdata()

IDL> help, data, /str
** Structure HSI_MONITOR_RATE_CYCLE, 8 tags, length=428, data length=428:
   TIME            FLOAT           0.00000 ;time is relative to the start of the obs_time_interval
   PARTICLE_LO     LONG      Array[8]      ;particle rate in LO energy band, 8 per time interval
   PARTICLE_HI     LONG      Array[8]      ;particle rate in HI energy band, 8 per time interval
   PREAMP_RESET    LONG      Array[18]     ;Reset rate, 18 segments
   SHAPER_VALID    LONG      Array[18]     ;Slow, 18 segments
   SHAPER_OVER_ULD LONG      Array[18]     ;ULD, 18 segments
   DELAY_LINE_VALID
                   LONG      Array[18]     ;Fast, 18 segments
   LIVE_TIME       FLOAT     Array[18]     ;Live time, 18 segments

Note that the names of the structure tags aren't quite the same as what we usually see, probably due to a misreading of the telemetry document. This is taken care of in the Plot method. To Plot:

obj -> plot, /slow

plots slow rates, /fast the fast rates, /reset the resets, /uld the ULD rates, /front for front detectors, /rear for rear, /particle for particles, /ltime for live_time.

Last modified: 22-Jun-2012, jmm