GTIWHERE Name
GTIWHERE
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Locate a list of times within a Good Time Interval (GTI) array
Calling Sequence
WH = GTIWHERE(TIME, GTI, COUNT=, INTERVALS=, /INVERT, /INCLUDE)
Description
The function GTIWHERE is an efficient method to determine which
good time interval (GTI) a particular time sample falls into, if
any. The user passes an array of one or more times in the TIME
parameter, and GTIWHERE determines which of these times are in a
good interval. The INTERVALS keyword returns an identification of
which interval the time fell into.
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.
The definition of "inside" a good-time interval is
TIME GE GTI(0,i) AND TIME LT GTI(1,i) (INCLUDE=0)
TIME GE GTI(0,i) AND TIME LE GTI(1,i) (INCLUDE=1)
where GTI(*,i) is the i'th interval.
When using /INVERT, the definition of "outside" a bad-time
interval is
TIME LT GTI(0,i) OR TIME GE GTI(1,i) (INCLUDE=0)
TIME LT GTI(0,i) OR TIME GT GTI(1,i) (INCLUDE=0)
Inputs
TIME - an array of times, in no particular order.
GTI - a 2xNINTERVAL array where NINTERVAL is the number of
intervals. GTI(*,i) represents the start and stop times of
interval number i. The intervals must be non-overlapping
and time-ordered (use GTITRIM to achieve this).
A scalar value of zero indicates that the GTI is empty, ie,
there are no good intervals.
Keywords
COUNT - upon return, the number of resulting intervals. A value
of zero indicates no good time intervals.
INTERVALS - upon return, an array of integers specifying the
interval number each time falls into. The number of
elements of INTERVALS is COUNT (ie, there is one
INTERVAL for each returned index).
INCLUDE - if set then the endpoints are considered closed at both
ends; by convention the endpoints are normally treated
as closed at the left and open at the right.
INVERT - if set, the array GTI is treated as a "bad" time
interval. Only times *outside* of the GTI are selected.
In this case there are NGTI+1 possible intervals, where
NGTI is the number of time intervals passed in GTI. The
indices returned in the INTERVALS keyword start from the
"left."
Returns
An array of integer indices indicating which elements of TIME are
within the "good" intervals. The number of selected elements is
COUNT. If COUNT is zero, then a scalar value of -1L is returned,
indicating no selected values.
See Also
GTISEG, GTIMERGE, GTIENLARGE
Modification History
Written, CM, 1997-2001
Documented, CM, Apr 2001
Added usage message, CM, 2006 Aug 18
Handle the case if /INVERT and /INCLUDE, which changes the
boundary conditions slightly, CM, 2007 Dec 15
Handle case of empty input GTI and /INVERT; also handle
INVERT in case where MIN(TIME) touches MIN(GTI), CM, 2008 Jul 08
Return -1L for no interval found, instead of 0L, CM, 2011 Jan 05