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.
> setenv DISPLAY [Ethernet address]:0
> idl
IDL>@compile_cdaweb compile the CDAWlib software
IDL>@compile_IDLmakecdf compile IDLmakecdf
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)
varnamesA 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.
cdfnames
A string or string array containing the names of the CDF file(s) to be read. 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.
ALLThis 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 CDFTYPE = "data" and their supporting variables).
NODATASTRUCT
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.
NOQUIET
Set this keyword to keep from disabling obnoxious warning messages from IDL's CDF file access routines.
TSTART
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.
TSTOP
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.
DEBUG
Set this keyword to turn on some progress messages.
a=strarr(2)
a(0)='i8_k0_mag_19951008_v01.cdf'
a(1)='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)
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 and XREAD_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)
astructA structure returned by the READ_MYCDF or XREAD_MYCDF functions. This structure, if the call to read_mycdf or Xread_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.
XSIZEThe width of the plot (in pixels). Default for GIF file is 640, default for x-windows is 90% of the screen resolution.
PANEL_HEIGHT
The height of each panel (in pixels). Default is 100 pixels.
TSTART
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.
TSTOP
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.
GIF
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.
PID
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.
OUTDIR
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.
AUTO
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.
COMBINE
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.
CDAWEB
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.
SLOW
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).
SMOOTH
Set this keyword to have spectrogram data reduced prior to plotting. This will increase plotting speed significantly.
QUICK
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.
NONOISE
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.
THUMBSIZE
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.
FRAME
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 .
DEBUG
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(0)='/home/xfiles/kessel/vlfcdf/hk_h0_vlf_00000000_v01.cdf' a(1)='/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[1] ; E_SPD STRUCT -> Array[1] ; BAVE STRUCT -> Array[1] ; POS_MAG STRUCT -> Array[1] ; POS_GSM STRUCT -> Array[1] ; ACTIVITY_INDEX STRUCT -> Array[1] ; EPOCH STRUCT -> Array[1] ; E_FREQ STRUCT -> Array[1] ; B_FREQ STRUCT -> Array[1] ; LABEL_MAG_POS STRUCT -> Array[1] ;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)
astructA structure returned by the READ_MYCDF or XREAD_MYCDF functions. This structure,if the call to read_mycdf or Xread_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.
NOGATTGlobal attributes output: =0 (print), =1 (no print)
NOVATT
Variable attributes output: =0 (print), =1 (no print)
NORV
Record varying output: =0 (print), =1 (no print)
NONRV
Non record varying output: =0 (print), =1 (no print)
NO2DRV
2D record varying output: =0 (print), =1 (no print)
FILENAME
Output filename.
MAXRECS
Maximum records listed.
a=xread_mycdf()
status=LIST_mystruct(a,TSTART=start, TSTOP=stop, /NOVATT)
This function provides a X-windows based interface to the function READ_MYCDF. This X-windows interface is invoked with the following
There are three different windows. The first one, a CDF file selector window, appears to the right. You are presented with a list of CDF files in the current directory. You are allowed to change your path to CDFs of interest through the second window, a path selector window. Once you select and open CDFs then the third window, a variable selector window, is invoked (shown below). This window allows you to select variables of interest for plotting. Once you have selected variables the function returns a structure identical to that of READ_MYCDF. The x-windows disappear and you are back at the IDL command line.
You can now plot the data in the structure "a" using PLOTMASTER or write your own idl plot routines to plot the data.
This function accepts no arguments at this time.
NODATASTRUCTIf 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.
DEBUG
Set this keyword to turn on some progress messages.
a=xread_mycdf()
buf1 = read_master_cdf(master_cdf,out_cdf)RESULT = write_data_to_cdf(out_cdf, buf1)
master_cdfA 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.
out_cdf
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.
buf1
An IDL structure holding the names and dimensions of the variables associated with the Master CDF.
DEBUGSet this keyword to turn on some progress messages.
; write_vlf.pro
; remove the cdf file if it exists
;$rm hk_h0_vlf_19741027_v01.cdf
; compile idl module before running this procedure
;.r IDLmakecdf.pro
;
; 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[16]
; SPDB FLOAT Array[8]
; 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[0] ne -1 then espd[i] = fillvalue
i = where(bspd ge 0)
if i[0] ne -1 then bspd[i] = fillvalue
i = where(bave eq 0)
if i[0] 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
Return to Space Physics Use of CDF
Author and Curator
Mona Kessel, mona.kessel@gsfc.nasa.gov, (301)286-6595
Tami Kovalick,
tami.kovalick@gsfc.nasa.gov, (301)286-9422
RITSS, Code 632, NASA Goddard Space Flight Center
Greenbelt, MD 20771, USA