;+
; 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