The CDF plotting routines available here underlie the CDAWeb software; they are supplied here in a package of IDL functions and procedures called CDAWlib.
Many functions exist in CDAWlib. We do not specifically call them all out here but they are all internally documented. The software has been tested but is not guaranteed to be bug free. We will try to address problems that you may find. There are two options for getting and running the software:
IDL> restore, 'spdfcdas.sav'
> setenv DISPLAY [Ethernet address]:0
IDL>@compile_cdaweb compile the CDAWlib software (not needed when using IDL save file)
IDL>@compile_IDLmakecdf compile IDLmakecdf (not needed when using IDL save file)
The function READ_MYCDF reads from one to many variables from one to many CDF files, and returns all data and metadata for these variables in a single structure of the form:
structure_name.variable_name.attribute_name.valueThe substructure for each variable will have three fields in addition to any fields holding any metadata information. These three fields are: VARNAME, which holds the name of the variable in a case-sensitive fashion, CDFTYPE, which holds the type of the CDF variable, and DAT, which holds the actual data values.
When reading more than one CDF, metadata and non-record-varying variables are only read from the first CDF, only record-varying data is read from all CDFs.
If an error occurs while reading the CDF(s), a -1 is returned
Result = READ_MYCDF(varnames, cdfnames) ; to read specific variables
Result = READ_MYCDF('',/all, cdfnames) ; to read ALL variables
A string or string array containing the names of the variables to be read from the CDF file(s). If specifying the variable names in a single string, then the names should be separated by a comma. NOTE: CDF is case sensitive, so the given variable names must be an exact match.
A string or string array containing the names of the CDF file(s) to be read (the CDFs need to be from one data type and in monotonical order). If specifying the CDF filenames in a single string, then the names should be separated by a comma. NOTE: If reading a file outside your current directory, then the full filename, including directory/path information, must be provided. All path and file information is case-sensitive.
This keyword has three valid values: 0 - meaning ignore, 1 - meaning read all variables (use this option if you don't know the names of the variables contained in your CDF file, and 2 - meaning read all variables with VAR_TYPE = "data" and their supporting variables).
If this keyword is set, then the .DAT field will be replaced with a field called .HANDLE. The value of this field is a handle_id where the data is located. Using this keyword can result in a performance improvement.
Set this keyword to keep from disabling obnoxious warning messages from IDL's CDF file access routines.
String of the form '1996/01/02 12:00:00' or a DOUBLE CDF_EPOCH time that is the desired start time of the data. Data is read between this TSTART value and the TSTOP value. Default is the start time of the earliest data.
String of the form '1996/01/02 12:00:00' or a DOUBLE CDF_EPOCH time that is the desired stop time of the plots. Data is read between the TSTART value and this TSTOP value. Default is the stop time of the latest data.
Set this keyword to turn on some progress messages.
a=strarr(2) a='i8_k0_mag_19951008_v01.cdf' a='i8_k0_mag_19951013_v01.cdf' b=read_mycdf('RMS,RMS_p',a) help,/struct,b ** Structure < 4006fca8 >, 4 tags, length=296936, refs=1: RMS STRUCT -> < Anonymous > Array(1) RMS_P STRUCT -> < Anonymous > Array(1) EPOCH STRUCT -> < Anonymous > Array(1) CARTESIAN STRUCT -> < Anonymous > Array(1) help,/struct,b.RMS ** Structure < 400cd808 >, 32 tags, length=147488, refs=2: VARNAME STRING 'RMS' TITLE STRING 'IMP-8 Magnetic Field' PROJECT STRING 'ISTP>International Solar-Terrestrial Physics' DISCIPLINE STRING 'Space Physics>Magnetospheric Science' SOURCE_NAME STRING 'IMP-8>Interplanetary Monitoring Platform 8' DESCRIPTOR STRING 'MAG>Magnetic Field Investigation' DATA_TYPE STRING 'K0>Key Parameter' DATA_VERSION STRING '1' TEXT STRING Array(15) MODS STRING Array(19) ADID_REF STRING 'NSSD0094' LOGICAL_FILE_ID STRING 'I8_K0_MAG_19951008_V01' FIELDNAM STRING 'Components of RMS of B (GSE)' VALIDMIN FLOAT Array(3) VALIDMAX FLOAT Array(3) SCALEMIN FLOAT Array(3) SCALEMAX FLOAT Array(3) UNITS STRING 'nT' UNIT_PTR STRING '' LABLAXIS STRING '' LABL_PTR_1 STRING Array(3) MONOTON STRING '' FORMAT STRING 'F7.3' FORM_PTR STRING '' FILLVAL FLOAT -1.00000e+31 CATDESC STRING '' VAR_TYPE STRING 'data' DICT_KEY STRING '' DEPEND_0 STRING 'Epoch' DEPEND_1 STRING 'cartesian' CDFTYPE STRING 'CDF_REAL4' DAT FLOAT Array(3, 12206)
Important Note: In plotting each variable, PLOTMASTER looks for the associated attribute, DISPLAY_TYPE, and uses the value to determine how to plot the variable. If the attribute is not present, then PLOTMASTER uses a set of rules to determine how to plot the variable. For simple scalar variables the rules work well, but for complex dimensional variables the rules break down. For ISTP CDF data, we strongly recommend the use of our master CDFs (containing only the metadata - variable names and attributes) to be read along with the data. PLOTMASTER will then read the metadata out of the master CDF (PLOTMASTER reads the metadata only out of the first CDF of each type) and use that metadata for all decision making.
Recommendation: When plotting variables use the /auto keyword (this turns on autoscaling)!
This function accepts from 1 to 10 structures of the type returned by READ_MYCDF, determines the plot type for each variable in each of the structures, and plots it. Returns a 0 if plotting was successful, and a -1 if unsuccessful.
Result = PLOTMASTER(astruct1,[astruct2...astruct10], /keyword)
A structure returned by the READ_MYCDF function. This structure, if the call to read_mycdf was sucessful, will contain many elements useful in plotting and listing the data, as well as the data itself. Please refer to the description of READ_MYCDF.
The width of the plot (in pixels). Default for GIF file is 640, default for x-windows is 90% of the screen resolution.
The height of each panel (in pixels). Default is 100 pixels.
String of the form '1996/01/02 12:00:00' or a DOUBLE CDF_EPOCH time that is the desired start time of the plots. Data is clipped or padded to conform to this time. Default is the start time of the earliest data.
String of the form '1996/01/02 12:00:00' or a DOUBLE CDF_EPOCH time that is the desired stop time of the plots. Data is clipped or padded to conform to this time. Default is the stop time of the latest data.
Set to send plot(s) to a gif file (must be using IDL 5.3 for the gif option), ie. /GIF or GIF=1L. If set a file will be produced in the current working directory (see OUTDIR keyword), using the following naming conventions: Spacecraft_instrument_pid_# (see the PID keyword for customization). If GIF is not set then the plot(s) will be put into an x-window.
May be used to customize part of the name of a gif file. The value of PID may be either a number or a string and will be inserted in the gif file name as follows: Spacecraft_instrument_pid_#.gif. If GIF is not set then the plot(s) will be put into an x-window and this keyword is ignored.
This keyword names the output directory where a gif file will be placed. If GIF is set but OUTDIR is not, then the gif file will be put in the user's current working directory.
Set this keyword to use autoscaling instead of the variables SCALEMIN and SCALEMAX attribute values. The scales will be set to the min and max values of the data, after fill values have been filtered from the data (see also NONOISE keyword). If the user wishes to modify variable scale values for plotting purposes, you may do so by changing the appropriate data structure values, ie. struct.variable.scalemin = 0.0. Please use great care in modifying the data structures values since they will greatly influence what your plots or listings may look like.
Set this keyword to ATTEMPT to force all time series and spectrograms to be plotted into a single x-window or GIF file. Default is to plot each structure in its own x-window/GIF file. PLOTMASTER may override this keyword if the plots cannot fit into the limited space of an x-window.
Set this keyword to force the margin on the right side of time series plots to be 100 pixels. This is the same margin used for spectrograms for the color bar. By default, PLOTMASTER will examine the data, and if ANY spectrograms will be produced, then it will align the margins properly. This keyword is only necessary for use in the CDAWeb system.
Set this keyword to have spectrogram plotted using the POLYFILL method. This method is slower but more accurate than TV (used in the QUICK method).
Set this keyword to have spectrogram data reduced prior to plotting. This will increase plotting speed significantly.
Set this keyword to have spectrograms plotted using the TV method. This method is very fast, but will produce inaccurate spectrograms if scales are non-linear or if fill data or data gaps are present in the data.
Set this keyword to filter out values outside of 3-sigma from the mean. This keyword is applied to timeseries and images plots only at this time.
Set this to change the "thumbnail" size of each image when plotting a series of images. The default is 50w x 62h. 12 pixels is added to the height to allow for the time stamps under each image. So, if you specify a thumsize of 70 pixels, each will actually be 70x82.
Used to indicate the frame number within a series of images. If you specify FRAME = 2, then plotmaster will produce a "full size" version of the 3rd image in a sequence of images .
Set this keyword to turn on some progress messages.
; plot_VLF.pro ; ;name of cdf to plot (start with Master CDF) a=strarr(2) a='/home/xfiles/kessel/vlfcdf/hk_h0_vlf_00000000_v01.cdf' a='/home/xfiles/kessel/vlfcdf/hk_h0_vlf_19740816_v01.cdf' ; list of variables I want to read from the skeleton table. Only need some of ; them and only the "data" varaibles. read_myCDF gets all of the associated ; variables. x = ['b_spd','e_spd','BAVE','pos_mag','pos_GSM','activity_index'] buf1 = read_myCDF(x, a, /DEBUG) ;you could type "help, /struct, buf1" to see what was read... ;** Structure <401d0808>, 10 tags, length=11424, refs=1: ; B_SPD STRUCT ->
Array ; E_SPD STRUCT -> Array ; BAVE STRUCT -> Array ; POS_MAG STRUCT -> Array ; POS_GSM STRUCT -> Array ; ACTIVITY_INDEX STRUCT -> Array ; EPOCH STRUCT -> Array ; E_FREQ STRUCT -> Array ; B_FREQ STRUCT -> Array ; LABEL_MAG_POS STRUCT -> Array ;pick and choose plots to make. if don't use /GIF, then an x plot is made status=plotmaster(buf1,xsize=500,/AUTO) status=plotmaster(buf1,xsize=500,/GIF,OUTDIR='/home/xfiles/kessel/vlfgif/',/AUTO) ; if plotting smaller than whole file define tstart and tstop. plotmaster ; can use either Epoch style or single real*8 number tstart = '1974/08/15 20:00:00' tstop = '1974/08/16 08:00:00' start = encode_cdfepoch(tstart) stop = encode_cdfepoch(tstop) status=plotmaster(buf1,xsize=500,/AUTO,TSTART=tstart, TSTOP=tstop) status=plotmaster(buf1,xsize=500,/AUTO,TSTART=start, TSTOP=stop,$ /GIF,OUTDIR='/home/xfiles/kessel/vlfgif/') end
Result = LIST_mystruct(astruct,NOGATT=nogatt,NOVATT=novatt,NORV=norv,$ NONRV=nonrv,NO2DRV=no2drv,FILENAME=filename,$ TSTART=TSTART,TSTOP=TSTOP,MAXRECS=maxrecs)
A structure returned by the READ_MYCDF function. This structure,if the call to read_mycdf was sucessful, will contain many elements useful in plotting and listing the data, as well as the data itself. Please refer to the description of READ_MYCDF.
Global attributes output: =0 (print), =1 (no print)
Variable attributes output: =0 (print), =1 (no print)
Record varying output: =0 (print), =1 (no print)
Non record varying output: =0 (print), =1 (no print)
2D record varying output: =0 (print), =1 (no print)
Maximum records listed.
cnames = 'example.cdf' vnames ='' a=read_mycdf(vnames, /all, cnames)
status=LIST_mystruct(a,TSTART=start, TSTOP=stop, /NOVATT)
buf1 = read_master_cdf(master_cdf,out_cdf)
RESULT = write_data_to_cdf(out_cdf, buf1)
A string containing the name of the master CDF. NOTE: If reading a file outside your current directory, then the full filename, including directory/path information, must be provided. If running on a UNIX system, remember that all path and file information is case-sensitive.
A string containing the name of the CDF file to be output. If specifying the CDF filenames in a single string, then the names should be separated by a comma. NOTE: If reading a file outside your current directory, then the full filename, including directory/path information, must be provided. If running on a UNIX system, remember that all path and file information is case-sensitive.
An IDL structure holding the names and dimensions of the variables associated with the Master CDF.
Set this keyword to turn on some progress messages.
; write_vlf.pro ; Notes: remove the cdf file if it exists ;$rm hk_h0_vlf_19741027_v01.cdf ; compile idl module before running this procedure ;.run IDLmakecdf.pro (not needed when using the spdfcdas.sav file) ;instead just restore the save file, e.g. restore, 'spdfcdas.sav' ; ; day 300 for 1974 is October 27 idl_saveset = 'hk_vlf_74300.idl' out_cdf = 'hk_h0_vlf_19741027_v01.cdf' ; read in master cdf skeleton, specify output CDF buf1 = read_master_cdf('hk_h0_vlf_00000000_v01.cdf',$ out_cdf) restore, idl_saveset ;you could type "help, /struct, arec" to see what was read... ;** Structure <400502c8>, 11 tags, length=136, refs=1: ; EPOCH DOUBLE 6.2319283e+13 ; SPDE FLOAT Array ; SPDB FLOAT Array ; BAVE FLOAT 58.0411 ; RE FLOAT 12.0038 ; MLAT FLOAT 55.0457 ; MLT FLOAT 6.07035 ; XGSM FLOAT -2.80766 ; YGSM FLOAT -6.87608 ; ZGSM FLOAT 9.43012 ; determine the number of records num_rec = n_elements(arec.epoch) :set up arrays Epoch = double(num_rec) espd = fltarr(16,num_rec) bspd = fltarr(16,num_rec) bave = fltarr(num_rec) pos_mag = fltarr(3,num_rec) pos_gsm = fltarr(3,num_rec) ; copy values out of idl save set Epoch = arec.EPOCH espd = arec.spde bspd = arec.spdb bave = arec.BAVE pos_mag(0,*) = arec.RE pos_mag(1,*) = arec.MLAT pos_mag(2,*) = arec.MLT pos_gsm(0,*) = arec.XGSM pos_gsm(1,*) = arec.YGSM pos_gsm(2,*) = arec.ZGSM ;check for zeros in espd, bspd, bave and set to fill value fillvalue = -1e31 i = where(espd ge 0) if i ne -1 then espd[i] = fillvalue i = where(bspd ge 0) if i ne -1 then bspd[i] = fillvalue i = where(bave eq 0) if i ne -1 then bave[i] = fillvalue ; copy processed data to buf1 *buf1.Epoch.data = epoch *buf1.E_SPD.data = espd *buf1.B_SPD.data = bspd *buf1.BAVE.data = bave *buf1.pos_mag.data = pos_mag *buf1.pos_GSM.data = pos_gsm ; write output CDF file stat2 = write_data_to_cdf(out_cdf, buf1) end