;+ ; NAME: ; GTI2MASK ; ; ; AUTHOR: ; Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 ; craigm@lheamail.gsfc.nasa.gov ; ; PURPOSE: ; Convert Good Time Interval (GTI) to evenly sampled mask array ; ; CALLING SEQUENCE: ; MASK = GTI2MASK(GTI, [TIME, TLIMITS=, TIMEDEL=, NTBINS=, ; GOOD=, BAD=, /FILL, /INVERT]) ; ; DESCRIPTION: ; ; The function GTI2MASK converts an existing valid Good Time ; Interval (GTI) array to a mask array. By definition a GTI ; indicates an array of intervals which are not on an evenly sampled ; array. This routine either accepts a time grid from the user, or ; the grid must be described by the TLIMITS and TIMEDEL keywords. ; ; The output mask array describes whether each grid point lies ; within a good interval or not. There is full control over the ; values of the good and bad values. ; ; This routine is the inverse of MASK2GTI. ; ; 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: ; ; GTI - a 2xNINTERVAL array where NINTERVAL is the number of ; intervals. GTI(*,i) represent 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. ; ; TIME - optional time array that specifies the time grid for the ; mask array. If TIME is not specified then the user must ; give the TLIMITS and TIMEDEL keywords to fully describe the ; grid spacing. The TIME array is overwritten if the FILL ; keyword is used. ; ; KEYWORDS: ; ; TLIMITS - a 2-element array giving the start and stop limits over ; which the mask array is to be generated. The TLIMITS ; and TIMEDEL keywords are required if the TIME parameter ; is not given. ; ; TIMEDEL - a scalar specifying the interval between grid points. ; The TLIMITS and TIMEDEL keywords are required if the ; TIME parameter is not given. ; ; NTBINS - upon return, this keyword contains the number of time ; samples created. ; ; GOOD - the value of "good" in the output mask array. ; Default: 1b ; ; BAD - the value of "bad" in the output mask array. ; Default: 0b ; ; INVERT - if set, the array GTI is treated as a "bad" time ; interval, ie, the GOOD and BAD values are swapped. ; ; FILL - if set, the array TIME is filled with values determined ; from the TLIMITS and TIMEDEL keyword. ; ; RETURNS: ; ; A mask array, either sampled at the points specified by TIME, or ; by the grid specified by TLIMITS and TIMEDEL. The "good" value ; indicates that the point lies within the good interval, while a ; "bad" value indicates the point was outside. ; ; SEE ALSO: ; ; MASK2GTI, GTITRIM, GTIMERGE ; ; MODIFICATION HISTORY: ; Written, CM, 1997-2001 ; Documented, CM, Apr 2001 ; Add internal OVERLAP and MINFRACEXP keywords, CM, 03 Feb 2007 ; Refine and simplify the OVERLAP processing, CM, 14 Feb 2007 ; Handle case of /OVERLAP when there is no intersection, CM, 22 Aug 2007 ; Use VALUE_LOCATE for performance (in non-OVERLAP case), CM, 04 May 2008 ; Defend against array having one element, CM 2013-04-29 ; ; $Id: gti2mask.pro,v 1.8 2013/04/29 22:42:17 cmarkwar Exp $ ; ;- ; Copyright (C) 1997-2001, 2007, 2008, 2013, 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. ;-