SOLMON IDL Object Tutorial

Paul Higgins (ARG/TCD), Peter Gallagher (ARG/TCD)



IDL objects in SolarSoft allow one to easily and efficiently analyze extensive data sets with a few simple commands. An object is a dynamic data consruct, which includes a number of methods (functions and procedures) to operate. Objects use the -> operator to call their methods. The object it self is merely a means to dynamically manage data and settings. The object's methods do all of the work.


This IDL object may be used to download, read into IDL, plot, print out or make a movie of data supported by the Solar Monitor website. Like other objects, the SOLMON object uses sockets to retrieve data. The SOLMON data is provided by Solar Monitor. The object has been tested on IDL version 6.3.


Get Started


The SOLMON object should have its own committed directory which should contain the files in this ZIP file. The object automatically copies files into the local directory as needed.

IDL


Start by creating the SOLMON object.

IDL> solmon = obj_new( 'solmon' )

Set the SOLMON instrument.

IDL> solmon -> set, instrument = 'eit'

List a day's worth of files.

IDL> flist = solmon -> list( timerange = '10-june-2007' )

IDL> help,flist

< Expression > STRING = Array[11]

Copy the files to the local directory.

IDL> solmon -> copy,filelist=flist

Read the files into the SOLMON object.

IDL> solmon -> read,filelist=flist

Plot the first file in the series.

IDL> solmon -> plot,filelist=flist[0]


Use PLOTMAN to plot the file.

IDL> solmon -> plotman,filelist=flist[0]


Create a movie of the files listed.

IDL> solmon -> movie,filelist=flist


Clean up the object and reallocate all memory.

IDL> obj_destroy,solmon


An alternative sample session could be as follows:

Initiate a new SOLMON object:
IDL> solmon = obj_new( 'solmon' )

Set the time: IDL> solmon -> set, time = '2-Jun-2007 16:00'

This will find the SOLMON image taken closest to the set time.

Now get the data.
IDL> image = solmon -> getdata()

The SOLMON object searches the remote archive and downloads the data using IDL sockets.
The data can then be plotted:
IDL> solmon -> plot


or IDL> solmon -> plot, xrange = [ -400, 0 ], yrange = [ -400, 0 ]


or IDL> solmon -> plot, center = [ -200, 200 ], fov = 7



Now check control parameters:
IDL> print, solmon -> get( /time )

or IDL> print, solmon -> get( /center )

or IDL> print, solmon -> get( /obs )

Scroll down for more examples.

Method Specifics


List


Description: Returns a list of full-path file names from the specified time range.
Syntax: IDL> flist = solmon -> list( timerange=timerange )
Keywords: timerange

timerange: A string array of one or two elements, using the syntax, 'day-month-year', which specifies the time stamps of the desired data files.

Copy


Description: Copies the listed files to the local directory.
Syntax: IDL-> solmon -> copy, filelist=filelist
Keywords: filelist

filelist: A string array contaning the full-path file names of the desired data files.

Read


Description: Loads the specified files into the SOLMON object.
Syntax: IDL> solmon -> read, filelist=filelist
Keywords: filelist, timerange

Plot


Description: Plots the desired data file.
Syntax: IDL> solmon -> plot, filelist=filelist
Keywords: filelist, timerange, (any plot_map keyword), /latest

plot_map keywords: xrange, yrange, contour, overlay, smooth_width, border, fov, grid_spacing, center, tail, log_scale, notitle, title, lcolor, window, noaxes, nolabels, xsize, ysize, new, levels, missing, dmin, dmax, top, quiet, square_scale, trans, positive_only, negative_only, dimensions, offset, bottom, ctyle, cthick, date_only, nodate, last_scale, composite, interlace, average, ncolors, drange, limb_plot, roll, rcenter, truncate, duration, bthick, bcolor, drotate, multi, noerase, clabel, margin, status, xshift, yshift
/latest: Plots SOLMON's latest available data.

Latest


Description: Reads the latest available data into the SOLMON object.
Syntax: IDL> solmon -> latest
Keywords: N/A

Plotman


Description: Calls the PLOTMAN object to plot the desired data.
Syntax: IDL> solmon -> plotman, filelist=filelist
Keywords: Same as PLOT.

Movie


Description: Calls the XMOVIE widget, and animates the desired data files.
Syntax: IDL> solmon -> movie, filelist=filelist
Keywords: filelist,timerange.

Set


Description: Sets the specified object property.
Syntax: IDL> solmon -> set, timerange=timerange
Keywords: timerange, instrument, filter, use_config, (any plot_map keyword).

instrument: Sets the SOLMON data instrument to analyze. The currently supported instruments are listed below.
filter: Sets the desired instrument filter. Some of SOLMON's instruments take images using various filters. All of the filters are listed in their respective instrument below.


Get


Description: Retrieves the specified object property.
Syntax: IDL> property = solmon -> get( /timerange )
Keywords: /timerange, /instrument, /filter, /obs, /ut, /header, /(any plot_map keyword).

/obs: Returns the FITS file id string.
/ut: Returns the FITS file's time stamp string.
/header: Returns a string array containing the entire FITS header.

Getdata


Description: Retrieves an array containing all of the data contained in the SOLMON object.
Syntax: IDL> data = solmon -> getdata( filelist=filelist )
Keywords: timerange, filelist.

Getmap


Description: Retrieves an array of all of the data contained in the SOLMON object in the form of MAP structures.
Syntax: IDL> maparray = solmon -> getmap( headers, filenames, filelist=filelist )
Outputs: headers, filenames
Keywords: timerange, filelist.

headers: An array of all of the headers of the data contained in the SOLMON object.
filenames: An array of the file names of all of the data contained in the SOLMON object.

RestorePlot


Description: Restore plots to default settings.
Syntax: IDL> solmon -> restoreplot

Multiplot


Description: Plots multiple images in a single window.
Syntax: IDL> solmon -> multiplot, timerange=timerange
Keywords: pmulti, same as plot.

pmulti: An array with the same form as that which would be specified for !P.multi=[position,columns,rows].

Plot_Compare


Description: Plots images of several instruments and filters in a single window.
Syntax: IDL> solmon -> plot_compare, timerange=timerange, instrument=['eit','mdi','mdi'], filter=['171','igram','mag'], pmulti=[0,1,3]
Keywords: instrument, filter, pmulti, same as plot.

instrument: An array of instrument names to plot. filter: The corresponding filter names to the instruments specified. (If an instrument does not have a filter, use '' for its filter name.) pmulti: An array with the same form as that which would be specified for !P.multi=[position,columns,rows].

More Examples


IDL> solmon -> plot, /latest


IDL> solmon -> plot, grid=5



IDL> solmon -> plot, fov=10



IDL> solmon -> plot_compare, instrument=['eit', 'eit', 'eit', 'bbso'], filter=['195', '171' ,'304' ,''], pmulti=[0, 2, 2]



Configuration


SOLMON's default plot settings may be altered using the configuration file. it is also possible to add additional Solar Monitor supported instruments to the SOLMON object using this file. In order for SOLMON to use the file, open solmon_config__define.pro in an editor. In the function, solmon_config::init, change the value of *(self.use_config) to be 1.

FUNCTION solmon_config::INIT

self.use_config = ptr_new(/allocate)

;--<< CHANGE THIS VALUE TO 1 FOR THIS CONFIG FILE TO BE USED OR 0 TO TURN IT OFF. >>
*(self.use_config) = 1

return,1
end

The following is the configuration for the EIT instrument:

;--<< EIT PROPERTIES >>

if instrument eq 'eit' then begin
filter_prop={f195:['8', '195', ''], f171:['1', '171', ''],f304:['3', '304', ''], f284:['8', '284', '']}

sat_prop={explot:{log:1,grid:1,center:1}, $
plot_prop:{log:1,grid:15,center:[0,0]}, $
fspan:{url:'http://www.solarmonitor.org', $
ftype:['*','insert', '*_fd_','*.fts*'], $
path:['/data/','insert','/fits/seit']}, $
xstd:1100, ystd:1100, loadct:0, hasfilter:1, def_filt:'195', unisize:0, arch_type:2}
endif

filter_prop is a structure which holds all of the necessary configuration for each of the instrument's filters. Each field is named fFILTER. For instance for EIT's 195 filter, there is a field called f195. The first element of the field is the LOADCT color table index. The second is the filter's keyword name. The third is the path from the main URL where the filter's data is held. For EIT all of the filters are in the same place, so the path is just ''.

sat_prop is a structure which holds all of the necessary configuration for the instrument.

The explot field holds all of the PLOT_MAP keywords which will be automatically included in the plot call. For instance if the log:1 field was removed, the plotted SXI image would no longer be log-scale.

The plot_prop field initializes the values of the specified keywords.

fspan defines the public archive where the instrument's data is stored.

xstd and ystd are the largest dimensions, roughly, that an SXI image could be. This is merely to save memory when the data is loaded into the SOLMON object.

loadct is the color table index that will be used to display the data.

hasfilter tells the program whether or not the instrument has filters.

def_filt is the name of the instrument's default filter.

unisize tells whether all of the instrument's images are the same size.

arch_type specifies which archive structure the data server uses.

0: Local directory. Use this if you've already downloaded all of the data you need.
Make sure you change the URL field to '' and set the path to where ever the data is on your local drive.

1: A simple remote directory. All of the data is in a single folder at a remote URL.

2: Solar Monitor's date-based archive structure. Each day has a separate folder for data.

Instruments

XRT - X-Ray Telescope
GONG - Global Oscillation Network Group
BBSO - Big Bear Solar Observatory
SXI - Solar X-Ray Imager
EIT - Extreme ultraviolet Imaging Telescope Filters: 107, 195, 304
MDI - Michelson Doppler Imager Filters: MAGLC, IGRAM
TRACE - Transition Region and Coronal Explorer