SSW UTPLOT package 5-Feb-1997, RAS, SDAC/GSFC ------------------------------------------------------------------------ The UTPLOT package draws Universal time tick marks and labels on plots. Time arrays passed to the UTPLOT subroutines should be in a format understandable by ANYTIM.PRO. String formats with two digits for years are understood to be in the range from 1-jan-1950 to 31-dec-2049. The range of time on a given plot should be greater than 5 milliseconds and not extend beyond the two digit year range, 1950-2049. 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 absolute reference of times passed as arrays of seconds are not understood unless a reference time, UTBASE, is passed into UTPLOT or is previously set by another routine. Fully referenced times, strings, structures, and others (see ANYTIM) are understood completely and require no ancillary information. To set the range of the time axis, the TIMERANGE keyword should be used with UTPLOT, using /XSTYLE for an exact range. 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 may set 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. GETUT retrieves the values of the stored base, start, and end times in either string or seconds format. The routine ANYTIM should be used as the primary conversion routine for time formats because it can recognize all the acceptable input formats autonomously. 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. An archaic use with 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, TIMERANGE=TIMERANGE 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. TIMERANGE - Optional. This can be a two element time range to be plotted. It can be a string representation or structure. 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, TIMERANGE=TIMERANGE and all keywords available to plot] Plot X vs Y semi-log with UT labels. Same arguments as UTPLOT. UTPLOT_IO is no longer supported. Please use UTPLOT, /YTYPE 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. ************************************************************************************ TIME CONVERSION ROUTINES: ANYTIM (INPUT, /INTS, /STC, /_2XN, /EXTERNAL, /UTIME, /SECONDS, or ...) This function is the universal format converter. See ANYTIM.PRO 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. OTHER USEFUL CONVERSION ROUTINES: TJD2YMD (TJD) Converts from TJD to ANYTIM formats YMD2TJD (YMD) Converts ANYTIM formats to TJD UT_2_YYDOY (UT) Converts ANYTIM formats to YYDOY YYDOY_2_UT (YYDOY) Converts YYDOY to ANYTIM formats (For a hardcopy of this information, print the file utplot_long.txt in the utplot directory, /ssw/gen/idl/utplot.)