;+ ; 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. ;- function gti2mask, gti, time, fill=fill, query=query, $ tlimits=tlimits, good=good, bad=bad, invert=invert,$ timepixr=timepixr, timedel=timedel, ntbins=nbins, $ overlap=overlap, minfracexp=minfracexp, exposure=expo if keyword_set(query) then return, 1 if keyword_set(overlap) AND n_elements(timedel) EQ 0 then begin message, 'ERROR: must specify OVERLAP and TIMEDEL together' return, 0 endif if n_elements(good) EQ 0 then good = 1b if n_elements(bad) EQ 0 then bad = 0b if n_elements(invert) EQ 0 then invert = 0 if n_elements(tlimits) LT 2 AND n_elements(gti) LT 2 then begin message, 'ERROR: could not determine TLIMITS' return, 0L endif if n_elements(minfracexp) EQ 0 then minfracexp = 0d if n_elements(tlimits) LT 2 then tlimits = [min(gti), max(gti)] if n_elements(timepixr) EQ 0 then timepixr = 0.D if n_elements(timedel) EQ 0 then timedel = 1.D nbins = long((tlimits(1) - tlimits(0))/timedel) if n_elements(time) EQ 0 OR keyword_set(fill) then $ time = dindgen(nbins)*timedel + tlimits(0) nbins = n_elements(time) if keyword_set(invert) then rep = good else rep = bad if keyword_set(invert) then new = bad else new = good mask = make_array(nbins, value=rep) if n_elements(gti) LT 2 then begin if keyword_set(overlap) then expo = dblarr(nbins) return, mask endif ngti = n_elements(gti) / 2 nt = n_elements(time) if keyword_set(overlap) then begin expo = dblarr(nbins) i0 = value_locate([time,tlimits(1)], gti(0,*)) i1 = value_locate([time,tlimits(1)], gti(1,*)) for i = 0L, ngti-1 do begin tmin = gti(0,i) tmax = gti(1,i) i0i = i0(i) i1i = i1(i) if i0i GE nt OR i1i LE -1 then goto, NEXT_GTI_1 if i0i EQ -1 then begin tmin = tlimits(0) i0i = 0 endif if i1i EQ nt then begin tmax = tlimits(1) i1i = nt-1 endif expo(i0i) = expo(i0i:i1i) + timedel expo(i0i) = expo(i0i) + (time(i0i)-tmin) expo(i1i) = expo(i1i) - (time(i1i)+timedel-tmax) NEXT_GTI_1: endfor endif else begin ;; Arghhh! One-element arrays confuse VALUE_LOCATE if n_elements(gti) EQ 2 then begin ii = (time GE gti(0)) - 1 endif else begin ii = value_locate(gti(0,*), time) endelse if n_elements(ii) EQ 1 then ii = [ii] wh = where(ii GE 0 AND time LT gti(1,ii), ct) if ct GT 0 then mask(wh) = new endelse ;; Finally determine where overlap is larger than required if keyword_set(overlap) then begin mask1 = expo GT timedel*minfracexp wh1 = where(mask1, ct1) if ct1 GT 0 then mask(wh1) = good wh1 = where(mask1 EQ 0, ct1) if ct1 GT 0 then mask(wh1) = bad endif return, mask end