;+ ; NAME: ; GAPNAN ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 661, Greenbelt, MD 20770 ; Craig.Markwardt@nasa.gov ; ; PURPOSE: ; Insert NANs in time series gaps to facilitate plotting ; ; MAJOR TOPICS: ; Time series ; ; CALLING SEQUENCE: ; GAPNAN, TT, Y1, [Y2,] [Y3,] [Y4,] [Y5], MAXGAP=, GTI= ; ; DESCRIPTION: ; This procedure is an covenience procedure for plotting time series ; which may have gaps. In other words, a time series where there ; will be time segments of data, and periods of no data which are ; considered "gaps." Sometimes it is desireable to plot the data ; with lines connecting the data, but no lines across gaps. ; ; GAPNAN will insert NAN values in time series between gaps. ; Because an IDL line plot will not connect points with NAN values ; between them, inserting a NAN value is an effective way of ; suppressing connecting lines between gaps. ; ; The user can specify gaps in one of two ways, using either the ; MAXGAP or the GTI keyword. The user must specify one of these ; keywords, but not both. ; ; The user can specify the maximum allowable gap size between time ; series samples using the MAXGAP keyword. If the time step between ; samples is larger than MAXGAP then a gap is declared. (This ; functionality uses the Markwardt library routine GTISEG.) ; ; The GTI keyword explicitly designates "good" time intervals. The ; user should pass a 2xn array using the GTI keyword, which indicate ; the start/stop time of each good-time. If the time samples cross ; between good time intervals (or if a time sample is noth within a ; good interval at all), then a gap is declared. (This ; functionality uses the Markwardt library routine GTIWHERE.) ; ; The values Y1, Y2, etc. are the dependent variables. Up to five ; dependent variables can be adjusted in one call. ; ; INPUTS: ; TIME - time variable, used to find gaps. Upon return, TIME will ; be modified in-place. Whereever gaps occur, a new time ; value will be inserted with the value of NAN. ; ; OPTIONAL INPUTS: ; Y1, Y2, Y3, Y4, Y5 - the optional dependent variable. Must have ; the same number of elements as TIME. Wherever NANs were ; inserted in the TIME array, NANs will also be inserted at ; the corresponding positions of Y1, Y2, etc. Upon return, ; these parameters will be modified in-place. The user may ; pass up to five dependent variables in one call. ; ; INPUT KEYWORD PARAMETERS: ; MAXGAP - maximum gap size between segments, in the same units as ; the TIME variable. The user must specify either MAXGAP ; or GTI, but not both. ; ; GTI - a 2xN array, in the same units as the TIME variable, ; indicating "good" time intervals. The user must specify ; either MAXGAP or GTI, but not both. ; ; EXAMPLE: ; ;; Sample data with gap between 3 and 10 ; tt = [1,2,3, 10, 11, 12d] ; yy = [1,1,1, 2, 2, 2d ] ; gapnan, tt, yy maxgap=5 ; ;; Note that a NaN is inserted between 3 and 10, since the actual gap of ; ;; 7 is larger than the maximum of 5. ; ; ; ;; Sample data with gap between 3 and 10 ; tt = [1,2,3, 10, 11, 12d] ; yy = [1,1,1, 2, 2, 2d ] ; ; ;; Good times from 0.5-2.5 and 10.5-13.0 ; gti = [[0.5,2.5], [10.5,13]] ; gapnan, tt, yy, gti=gti ; ; ;; Note that a Nan is inserted between 2 and 3 because the good ; ;; interval stops at 2.5; a Nan is inserted between 3 and 10, and ; ;; 10 and 11 because neither 3 nor 10 are within a good interval. ; ; ; MODIFICATION HISTORY: ; Written and documented, 2010-04-27 CM ; Added MAXGAP and GTI keywords, 2010-11-13 CM ; Square bracket array notation, 2011-12-21 CM ; Bug fix for more than one input array (was ignored), 2012-02-20 CM ; Bug fix when input GTI is set; defend against array bounds error; ; add USAGE message, 2013-03-16 CM ; ;-