IDL Version 2 UTPLOT package October 3, 1991 ------------------------------------------------------------------------ The UTPLOT package draws Universal time tick marks and labels on plots. Time arrays passed to the UTPLOT subroutines should be in units of seconds relative to a base time selected by the user. Allowable times range between 79/1/1 and 99/12/31. The range of time on a given plot can be anywhere between 5 milliseconds and 20 years. If the user sets a start and/or end time only data between those times will be plotted; otherwise the x axis is autoscaled to the start/end of the data. The format of times written in labels differs slightly from the format used to pass times to routines. Input format contains only one colon between minutes and seconds (making the meaning of a partial string precise) while labels include an extra colon between hours and minutes (which is more acceptable for publication). Internally, the base, start, and end times selected by the user are stored in COMMON UTCOMMON,UTBASE,UTSTART,UTEND as double precision seconds since 79/1/1, 0000. The user sets these times by calling the SETUT routine with an ASCII string in the format YY/MM/DD,HHMM:SS.XXX; SETUT converts the ASCII string to seconds and stores the value in the appropriate variable in common UTCOMMON. The routines ATIME and UTPLOT_UTIME are available for converting between the ASCII and the internal representation of a time. GETUT retrieves the values of the stored base, start, and end times in either format. In the simplest use, the user calls UTPLOT,X,Y and is prompted for a base time. Additional flexibility is available in the call to UTPLOT by using additional calling parameters including all of the keywords available to PLOT. Alternatively, more flexibility is available by calling SET_UTPLOT to set the !X... plotting structure variables (tick locations, labels, etc) and then calling PLOT with any of its keywords instead of UTPLOT. Normally the variables in the !X... structure associated with the x-axis labeling are saved in a temporary location before plotting and restored after plotting so that subsequent plots are not affected. If UTPLOT is called with the /SAV option, these !X... variables will remain set so that they can be used by subsequent plots. They can be cleared by calling CLEAR_UTPLOT. -------------------------------------------------------------------------- PROCEDURES: UTHELP, [/LONG] Type summary of UTPLOT routines, or if /LONG option is specified, type complete explanation of UTPLOT package. UTPLOT, X, Y [, 'UTBASE', LABELPAR=LBL, /SAV, TICK_UNIT=TICK, MINORS=MINORS, /NOLABEL, and all keywords available to plot] Plot X vs Y with UT labels. X - X array to plot in seconds relative to base time. Y - Y array to plot. UTBASE - (Optional) ASCII string containing base time for X axis. Format for time is YY/MM/DD,HHMM:SS.XXX. If this parameter isn't present and hasn't been set yet, user is prompted for base time. LBL - 2 element vector selecting substring from publication format of ASCII time (YY/MM/DD, HH:MM:SS.XXX). For example, LBL=[11,18] would select the HH:MM:SS part of the string. SAV - If set, UTPLOT labels, tick positions, etc. in !X... system variables will remain set so that they can be used by subsequent plots (normally !x... structure is saved in temporary location before plot and restored after plot). To reset !x... structure, call CLEAR_UTPLOT. TICK - Distance in seconds between x tick positions. MINORS - Number of minor tick intervals between the x ticks. NOLABEL - If set then the start time won't be written on the plot. UTPLOT_IO, X, Y [, 'UTBASE', LABELPAR=LBL, /SAV, TICK_UNIT=TICK, MINORS=MINORS, /NOLABEL, and all keywords available to plot] Plot X vs Y semi-log with UT labels. Same arguments as UTPLOT. SET_UTPLOT, [XRANGE=X, LABELPAR=LBL, UTBASE='BASE', ERROR_RANGE=ERROR_RANGE, ERR_FORMAT=ERR_FORMAT, TICK_UNIT=TICK, MINORS=MINORS, XSTYLE=XSTYLE] Prepares IDL system variables (!X.CRANGE, !X.TICKV, !X.TICKNAME, and !X.TICKNAME) for plotting X vs Y with Universal time labels After calling SET_UTPLOT, user calls the standard IDL PLOT routine to draw the plot. SET_UTPLOT is normally called by UTPLOT, and is transparent to the user. X - X array to plot (seconds relative to base time). LBL - 2 element vector selecting substring from publication format of ASCII time (YY/MM/DD, HH:MM:SS.XXX). For example, LBL=[11,18] would select the HH:MM:SS part of the string. BASE - ASCII string containing base time for X axis. Format for time is YY/MM/DD,HHMM:SS.XXX. If this parameter isn't present and hasn't been set yet, user is prompted for base time. ERROR_RANGE - = 0/1. If set to 1, the X array is outside of the limits defined by start and end times selected by user. ERR_FORMAT - = 0/1. If set to 1, there was an error in the ASCII time format for the base time. TICK - Distance in seconds between x tick positions. MINORS - Number of minor tick intervals between the x ticks. XSTYLE - Usual meaning for PLOT. /XSTYLE forces exact x-axis range. SET_UTLABEL, IFLAG IFLAG = 0/1 means don't/do write start time label on plot. Default is 1. CLEAR_UTPLOT Restores !X... structure to value prior to using UTPLOT with /SAV option or SET_UTPLOT. SETUT, [UTBASE='UTBASE', UTSTART='UTSTART', UTEND='UTEND', ERROR=ERROR, SET_UTPLOT=SET] Set base,start, or end time in common UTCOMMON. BASE, START, or END - ASCII string in format YY/MM/DD,HHMM:SS.XXX. Partial strings are allowed. If the date is omitted, the last date passed (for base, start, or end time) is used. e.g. if '88/3/4,1230' had already been passed: '1200' means 88/3/4,1200 '01' means 88/3/4,0001 (1 minute into the day) '01:2' means 88/3/4,0001:02.000 (1 min., 2 sec into day) '1200:20.1' means 88/3/4,1200:20.100 (20.100 sec. after 12) ERROR - 0/1 indicates no error/error in converting ASCII time to double precision seconds. SET - 0/1 indicates no call/call to SET_UTPLOT. Value remembered. GETUT, [UTBASE='BASE', UTSTART='START', UTEND='END', /STRINGIT, /PRINTIT] Retrieve base, start, or end time from common UTCOMMON. BASE, START, END - keyword parameters select which time(s) to retrieve, times returned are double precision seconds relative to 79/1/1, 0000 or string if /STRINGIT is specified /STRINGIT - return times in strings with format YY/MM/DD, HHMM:SS.XXX /PRINT - print times on the terminal (prints all three if none are specified) GETUTBASE () Function to retrieve value of utbase in double precision seconds from common UTCOMMON without having to declare common. RESULT = GETUTBASE() SETUTBASE [,'UTBASE', ERROR=ERROR] Set base time. UTBASE - string in YY/MM/DD, HHMM:SS.XXX format to be converted to internal representation and stored in UTCOMMON variable UTBASE. ERROR - 0/1 indicates no error/error in converting UTSTRING SETUTSTART [,'UTSTART', ERROR=ERROR] Set start time. See SETUTBASE description. SETUTEND [,'UTEND', ERROR=ERROR] Set end time. See SETUTBASE description. ATIME (UT, [/PUB]) Function to convert time to ASCII string. UT - Time to convert to string, in double precision seconds since 79/1/1, 0000:00.000 /PUB - Resulting string will have a colon (:) between hours and minutes UTPLOT_UTIME ('UTSTRING') Function to convert ASCII string to double precision seconds since 79/1/1, 0000. If no date is entered, previous date is not 'remembered'. Result is seconds into day. UTSTRING - String containing time in form YY/MM/DD,HHMM:SS.XXX ERROR - =0/1. If set to 1, there was an error in the ASCII time string. (For a hardcopy of this information, print the file IDL_DIR:[LIB.UTPLOT]UTPLOT_LONG.TXT.)