IDL Software for Analyzing Spectrograms and Time Series

A.Csillaghy (UAS NW Switzerland) and D. M. Zarro (EER/GSFC)

2004-Apr-21


CONTENTS


1. INTRODUCTION

1.1 Creating a Spectrogram Object
1.2 Plotting a Spectrogram Object
1.3 Plotting Spectrogram Objects on Different Color Scales
1.4 Plotting Spectrogram Objects with Line Plots

2. OPERATIONS WITH SPECTROGRAM OBJECTS
2.1 Background subtraction

3. APPLYING SPECTROGRAM OBJECTS TO SOLAR OBSERVATIONS
3.1 Creating a RHESSI Spectrogram Object
3.2 Creating a PHOENIX spectrogram Object

4. OVERLAYING SPECTROGRAM OBJECTS


1. INTRODUCTION

This document intentionally "replicates" the document describing  the Map software. The intent is to be able to work with spectrograms in the same way as we already work with maps. In fact, this document was partly developed before the software was developed. The examples below were used as test cases for the software.

In its simplest form, an IDL Spectrogram object is a structure that contains a two-dimensional (2-d) spectrogram data with accompanying time and energy axis coordinates. The latter parameters are defined as properties of the spectrogram and are unique for each spectrogram (although they can be shared between spectrograms). Defined in this manner, an arbitrary spectrogram can be manipulated or transformed in a manner that is independent of its origin.

With the advent of version 5, IDL has been enhanced to support object-oriented programming (OOP). What this means in practical terms is that structures that once could only contain data variables as tags, can also have additional fields that are actually functions (or procedures) that operate on the data themselves. These structure functions are called methods. In the context of OOP, spectrograms with such methods are known as objects. The document below uses methods to access information in the object -- this syntactically differs slightly from the map software.

This memo describes how to create and use spectrogram objects for processing time/spectral information from solar observations. We will use sample spectrograms obtained from the RHESSI mission and the PHOENIX solar radio spectrometer of ETH Zurich. Although we discuss solar examples, the techniques  are applicable to any two-dimensional dataset with time-series and spectrum information..The  IDL spectrograms software is incorporated into the SolarSoft system - a set of integrated software libraries, databases, and system utilities which provide a "common" programming and data analysis environment for Solar and Heliospheric Physics.

1.1 Creating a Spectrogram Object

The low-level function for creating a spectrogram object is make_spectrogram(). In this example, a 256x256 array is created with findgen and converted to a spectrogram variable: 

IDL> sp_data=findgen(256,256) 
IDL> sp=make_spectrogram(sp_data)
IDL> sp->help
** Structure <2015d90>, 3 tags, length=262144, data length=262144, refs=1:
   SPECTROGRAM     FLOAT     Array[256, 256]
   TIME_AXIS       FLOAT     Array[256]
   SPECTRUM_AXIS   FLOAT     Array[256]
The resulting spectrogram is an anonymous structure with the following tag definitions:

The above tag definitions can also be defined as parameters or keywords in make_spectrogram. For example, a spectrogram with a time_axis starting at '2003/12/27 9:14' with time resolution of 0.1 seconds and  a regular frequency range of  300 to 1000 could be defined as follows: 

IDL> sp_data=findgen(256,256) 
IDL> time_axis = findgen( 256 )*0.1 + anytim( '2003/12/27 9:14' ) 
IDL> freq_axis = findgen( 256 )*(1000-300)/256. + 300
IDL> sp=make_spectrogram( sp_data, time_axis, freq_axis)
IDL> sp->help
** Structure <49060c0>, 3 tags, length=265216, data length=265216, refs=1:
   SPECTROGRAM     FLOAT     Array[256, 256]
   SPECTRUM_AXIS   FLOAT     Array[256]
   TIME_AXIS       DOUBLE    Array[256]

The tags are still the same, but the axis values are now those passed to make_spectrogram. Note that the basic spectrogram structure definition is kept intentionally simple, with data and time / spectrum axes being the main defining properties. The units of the spectrogram data are arbitrary. The time is defined in seconds from January 1, 1979.  Additional properties are added two ways:

  1. At the definition stage. For example, to include a property UNITS that specifies coordinate units for the spectrum axis: 

    IDL> sp=make_spectrogram(sp_data,time_axis, freq_axis, units='keV')
    IDL> sp->help
    ** Structure <2020a30>, 4 tags, length=40812, data length=40812, refs=1:
       SPECTROGRAM     FLOAT     Array[256, 256]
       SPECTRUM_AXIS   FLOAT     Array[256]
       TIME_AXIS       FLOAT     Array[256]
       UNITS           STRING    'keV'

  2. After the definition stage. Following the same example, but using the function set : 

    IDL> sp->set, units='keV'
    produces the same result. Multiple properties are added as multiple keywords, with the restriction that each property name is unique.

1.2 Plotting a Spectrogram Object

Spectrogram objects are plotted using the procedure plot . Thus, using the 2-d spectrogram created earlier, 

IDL> sp->plot, xstyle=3, ystyle=3


Fig. 1 - Image spectrogram

The procedure plot inherits all the major IDL plot keywords such as xstyle, ystyle, font, charsize, charthick, etc. It supports a large number of keywords, including the following:

The use of more advanced keywords will be demonstrated later in this tutorial.

1.3 Plotting Spectrogram Objects on Different Color Scales

The following steps demonstrate how to simultaneously plot spectrogram objects using different color tables. 

IDL> image=dist(256) 
IDL> !p.multi = [0,1,2]
IDL> o = make_spectrogram(image)                ;-- make a simple spectrogram
IDL> nc=100                             ;-- # of colors per image
IDL> loadct,3,ncolors=nc                ;-- load red table from  0:nc-1
IDL> o->plot, spectrogram,spectrogram,ncolors=nc            ;-- plot spectrogram using red table
IDL> loadct,1,bottom=nc,ncolors=nc      ;-- load blue table from nc:2*nc-1
IDL> o->plot,bottom=nc,ncolors=nc  ;-- plot using blue table

The key to plotting with separate color tables is to divide evenly the total number of available device colors. The latter is given by the system variable !d.table_size. In the above example, the total available colors is 200. Hence, the color table is split into two equal halves of nc=100 colors each. The routine loadct loads a red color table (#3) into the first 0 to nc-1 color range, and blue color table (#1) into the second nc to 2*nc-1 range. The resulting plots appear as:



Fig. 2 - Two spectrograms with different color tables

There is also another way of plotting spectrograms together, this will be discussed below.

1.4 Plotting Spectrogram Objects with line plots

You can switch from spectrogram ploting to line plots by specifying the plot_type. 
IDL> o->plot, plot_type = 1

1.5 Saving Spectrogram Objects

Sometimes you want to take a break but dont want to loose all your work. So before you go you can save the object with: 

o->save
Once you get back to work you can restore the object to the point where you were before: 
 
o->restore

You will have to create a new object if you dont have one yet.

2. OPERATIONS ON SPECTROGRAM OBJECTS

The following examples demonstrate various image processing that can be applied to spectrogram objects.

2.1 Background Subtraction in a Spectrogram Object

IDL> o->bkg_subtract

IDL> o->plot


 This will automatically determine the background in the image and subtract it. The asic idea is: you can pass a background time interval to
the spectrogram. works only for phoenix yet. needs some interaction w/ plotman

3. APPLYING SPECTROGRAM OBJECTS TO SOLAR OBSERVATIONS

This section describes the steps involved in creating spectrogram objects for various solar datasets. The routine index2map is a generally useful program for creating map objects from any dataset that is in a Yohkoh index/data format.

3.1 Creating a RHESSI Spectrogram Object

 
The function hsi_spectrogram() creates a RHESSI spectrogram object: 

IDL> o1 = hessi_spectrogram( )
IDL> o1->read, obs_time = '2003-aug-30 ' + ['13:27:45', '13:28:25'], energy_band = [3,6,12,25,50,80,160]
IDL> o1->plot

3.2 Creating a PHOENIX Spectrogram Object

The function phnx_spectrogram creates a Phoenix map object: 

IDL> o2 = phnx_spectrogram( )
IDL> o2->read, filename = '200310281100i.fit.gz'
IDL> o2->plot

this creates a phoenix spectrogram object, reads in the specified file into the object, and plots it. Instead of using files, you can also use observing time intervals:

4. OVERLAYING SPECTROGRAM OBJECTS

  Spectrogram objects are graphically overlayed  or combined by telling each others their existence.. In the following example, a RHESSI spectrogram is displayed with a  phoenix map. 

IDL>o1->plot, o2
IDL>o2->plot, o1