;+ ; NAME: ; GTISEG ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Convert a list of times to a set of Good Time Intervals (GTIs) ; ; CALLING SEQUENCE: ; GTI = GTISEG(TIMES, COUNT=COUNT, INDICES=INDICES, $ ; MAXGAP=MAXGAP, MINGTI=MINGTI) ; ; DESCRIPTION: ; ; The function GTISEG accepts an array of times and converts ; adjacent data into good time intervals (GTIs). ; ; Elements of the array are clustered into intervals based on the ; gaps between times. If the gaps are small enough then the times ; are grouped into a single interval. If a gap exceeds MAXGAP, then ; an interruption occurs and at least two intervals are formed. ; Thus, the keyword parameter MAXGAP essentially determines how many ; and where the intervals will be formed. ; ; If the time samples are regularly spaced -- aside from gaps -- ; then MAXGAP should be set to a number slightly larger than the ; spacing to prevent roundoff errors. By default MAXGAP is set to ; the difference between the first and second samples. ; ; For GTISEG, the samples do not need to be regularly spaced, but ; they *must* be given in ascending order. Arrays can be sorted ; with the SORT function. The primary difference between GTISEG and ; MASK2GTI is that MASK2GTI assumes the time samples are regularly ; spaced while GTISEG does not. Also, MASK2GTI allows intervals to ; be enlarged or shrunk. ; ; It should be noted that this function is not constrained to ; operation only on time arrays. It should work on any ; one-dimensional quantity with intervals. ; ; INPUTS: ; ; TIME - an array of times in ascending order. ; ; ; KEYWORDS: ; ; MAXGAP - a scalar, the maximum gap between time samples before a ; new interval is created. Samples with gaps smaller than ; this value are grouped into a single GTI. ; Default: TIME(1) - TIME(0) ; ; MINGTI - the smallest possible GTI. Any interval smaller than ; MINGTI is discarded. ; Default: 0 (all intervals are accepted) ; ; COUNT - upon return, the number of resulting intervals. A value ; of zero indicates no good time intervals. ; ; INDICES - upon return, a 2xCOUNT array of integers which give the ; indices of samples which lie within each interval. The ; times TIME(INDICES(0,i) : INDICES(1,i)) fall within the ; ith interval. ; ; RETURNS: ; ; A new GTI array containing the enlarged or shrunken intervals. ; The array is 2xCOUNT where COUNT is the number of resulting ; intervals. GTI(*,i) represents the start and stop times of ; interval number i. The intervals are non-overlapping and ; time-ordered. ; ; If COUNT is zero then the returned array is a scalar value of ; zero, indicating no good intervals were found. ; ; SEE ALSO: ; ; MASK2GTI, GTITRIM, GTIMERGE, GTIWHERE ; ; MODIFICATION HISTORY: ; Written, CM, 1999-2001 ; Documented, CM, Apr 2001 ; MINGTI now works as documented, in that segments *equal* to MINGTI ; are now accepted, CM, 30 Oct 2007 ; MINGTI now also affects INDICES, CM, 03 Mar 2008 ; Handle case of scalar input, CM, 2016-04-15 ; ; $Id: gtiseg.pro,v 1.8 2016/05/19 16:12:02 cmarkwar Exp $ ; ;- ; Copyright (C) 1999-2001, 2007, 2008, 2016, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;- function gtiseg, time, maxgap=maxgap, mingti=mingti, $ indices=indices, count=count, query=query if keyword_set(query) then return, 1 count = 0L if n_params() EQ 0 then begin message, 'GTI = GTISEG(TIME, [COUNT=,] [INDICES=,] [MAXGAP=,] [MINGTI=])',$ /info return, 0 endif if n_elements(maxgap) EQ 0 then maxgap = time(1) - time(0) nt = n_elements(time) tdiff = [0d] & ntseg = 0L if nt GT 1 then begin tdiff = time(1:*) - time whdiff = [-1L, where(tdiff GT maxgap(0), ntseg), nt-1] endif if (nt LE 1) OR (ntseg EQ 0) then whdiff = [-1L, nt-1] ntseg = ntseg + 1 mintdiff = min(tdiff) > 0 indices = reform(lonarr(2, ntseg), 2, ntseg, /overwrite) indices(0,*) = whdiff(0:ntseg-1)+1 indices(1,*) = whdiff(1:ntseg) tgti = reform(make_array(2, ntseg, value=time(0)*0), 2, ntseg, /overwrite) tgti(0,*) = time(indices(0,*)) tgti(1,*) = time(indices(1,*)) + mintdiff if n_elements(mingti) GT 0 then begin wh = where(tgti(1,*)-tgti(0,*) GE mingti(0), ntseg) if ntseg GT 0 then begin tgti = reform(tgti(*,wh),2,ntseg) indices = reform(indices(*,wh),2,ntseg) endif else begin tgti = -1L indices = -1L endelse endif count = ntseg return, tgti end