Most functions will echo their usage if called with no arguments (if having no arguments is an error).

Functions by category:

Input events, bin curves, output curves:

Binning regions, cross-dispersion:

Ephemeris:

Time range filter:

Time conversion:

Filter light curve:

Function reference:

aglc_read_events

SYNOPSIS
   Read subset of events from grating file and from exposure file
   into a structure.

USAGE
     s = aglc_read_events( tgevt, expno_ref )

DESCRIPTION
     tgevt should be a Level 1.5 (or 2) grating events file name.
     expno_ref should be a Level 1 ``stat'' or events (unfiltered) file name.
     The returned value is a structure.  The detailed contents of the
     structure are given below in the example.  While the exposure can
     be computed from the EXPNO column of the unfiltered event file,
     use of the `stat1' file is more efficient.

EXAMPLE
isis> s = aglc_read_events( f_evt1a, f_evt0 );
% Reading files evt1a.tg, stat1.exp ...
% Read 379932 events.
% Read 110907 exposure reference records.
% Applying gti filters... 4 5 6 7 8 9
isis> print(s);
    fevt_1a = evt1a.tg
    filt_1a = NULL
    fevt_exp = stat1.exp
    filt_exp = NULL
    expno = Integer_Type[110894]
    ccd = Short_Type[110894]
    expno_1a = Integer_Type[379932]
    ccd_1a = Short_Type[379932]
    tgpart = Short_Type[379932]
    order = Short_Type[379932]
    tgd = Float_Type[379932]
    wave = Float_Type[379932]
    timedel = 3.24104
    timepixr = 0.5
    frame_exp = 3.2
    mjdref = 50814
    tstart = 7.30246e+07
    status = UInteger_Type[379932]
    time = Double_Type[110894]
    cycle = NULL

SEE ALSO
   aglc_filter,  aglc,  aglc_phased

Definitions for Event Structure Fields

• fevt_1a: File name for grating events.
• fevt_exp: File name for exposure reference (unfiltered events or ``stat1'' file)
• expno[]: Exposure number column from exposure reference file.
• ccd: CCD_ID column from exposure reference file.
• expno_1a : Exposure number column from grating event file.
• ccd_1a: CCD_ID column from grating event file.
• tgpart: TG_PART column from grating event file. (value is 1 for HEG, 2 for MEG, 0 for zero order, 99 for background)
• order: TG_M column from grating events file, giving the diffraction order.
• tgd: TG_D column from grating events file. This is the cross-dispersion coordinate in degrees.
• wave: TG_LAM column from grating events file, giving the wavelength of each event.
• timedel: TIMEDEL keyword from grating event file, needed for scaling exposure numbers to time. (See the ahelp on time.)
• timepixr: TIMEPIXR keyword from event file. (See the ahelp on time.)
• frame_exp: the exposure time per frame (EXPNO). (See the ahelp on time.)
• mjdref: Modified Julian Day reference time for Chandra observations, from the event file header.
• tstart: TSTART, from the event file header, is the observaton start time in seconds since MJDREF.
• status: Event status column, from the grating events file. (See the definition of ACIS status bits.)
• time: The TIME column from the exposure reference event file.
• cycle: unused.

aglc

SYNOPSIS
  Bin a light curve from ACIS grating events.

USAGE
 lc = aglc(tgevt, expno_ref, tbin, wmin, wmax, tg, orders[, bkg]);
 lc = aglc(          evt_struct, tbin, wmin, wmax, tg, orders[, bkg]);

DESCRIPTION
 Given an event file name (tgevt) and an exposure reference file
 (unfiltered events or ``stat1'') name (expno_ref), bin a light curve
 for the specified time bin in seconds (tbin), wavelength ranges
 specified by wmin, wmax, in Angstroms.  If wmin and wmax are arrays,
 then they must be the same length and represent low-high pairs of
 wavelength regions.  The argument, tg, is a scalar or array of
 grating names, and should be one or more of "HEG" and "MEG", or "LEG"
 (case-insensitive); only the first character is necessary.  The
 argument, "orders", should be an array of integers specifying the
 diffraction orders to bin (excluding zero).  If the last argument is
 present, then events are binned from the background region instead of
 the source region.

 In the second form, an event structure as returned by
 aglc_read_events is used instead of two file names.  This is
 more efficient for multiple calls, since it avoids multiple file
 reads.

 The two files required in the first form are the grating coordinates
 event file, probably filtered of bad events; i.e., typically the file
 from which a spectrum would be binned ("Level 1.5" or "Level 2").
 The second file, the exposure reference file, should be unfiltered
 events or the ``stat1'' file.  It is used to count the exposed frames
 to determine the exposure; any event - cosmic ray, bad pixel, photon
 - will suffice to mark a frame.  Use of the ``stat1'' file is more
 efficient, since it has only one entry for each unique frame.

 Standard binning regions are applied for source and background
 events.   They may be changed with aglc_set_regs.

 The return value is a structure of the form
    time = Double_Type[]
    time_min = Double_Type[]
    time_max = Double_Type[]
    counts = UInteger_Type[]
    count_rate = Double_Type[]
    stat_err = Double_Type[]
    exposure = Double_Type[]
    timezero = Double_Type
    mjdref = Integer_Type
    revidx1a = Array_Type[]
    revidx = Array_Type[]

 The times are in seconds since timezero.  Timezero is the number of
 seconds since 1998.0, which is also the reference MJD.

 The count_rate is per second, and is equivalent to counts/exposure.
 The exposure is computed properly for event selections spanning
 multiple CCDs with possibly different GTI tables.

 The reverse indices, revidx1a, are returned by the histogram
 function; for each bin of the light curve they point to
 the items in the event list which have been binned.  This facilitates
 subsequent operations on events in specific bins, especially when
 selected on non-time criteria. (see aglc_filter).

 "revidx" is like revidx1a, but for the exposure record event list.


EXAMPLE
  Compute the light curve for the sum of Ne X 12A and O VIII 19A:

  wlo = [12.1, 18.8];
  whi = [12.2, 19.1];
  g = ["H", "M"];
  o = [-1,1]
  c = aglc( "evt2.fits", "evt1.fits", 1000, wlo, whi, g, o );
  hplot(c.time_min, c.time_max, c.counts);

SEE ALSO
 aglc_read_events, aglc_filter, aglc_set_regs

Definitions for Light Curve Structure Fields

• time: event time, bin center, since timezero.
• time_min: lower edge of time bin, seconds since timezero.
• time_max: upper edge of time bin, seconds since timezero.
• counts: counts per time bin.
• count_rate: Counts per second ( counts / exposure ).
• stat_err: Statistical error ( sqrt(counts) ).
• exposure: Exposure per bin, averaged over all chips included, in seconds.
• timezero: reference time, in seconds since MJDREF.
• mjdref: Modified Julian Day reference point of Chandra data (from event header)
• revidx1a: reverse index array for the grating events.
• revidx: reverse index array for the exposure reference events.

aglc_set_status_filter

SYNOPSIS
   Set a flag to specify if the grating events should be filtered on
   STATUS=0.  By default, the status filter is zero, meaning all good
   events.  Different status bit fields qualify attributes of "bad"
   pixels.  If, for some reason, the grating events have not been
   filtered on status, but should be, then setting this flag causes
   all events with non-zero status to be ignored.

USAGE
  aglc_set_status_filter( flag );

DESCRIPTION
  If flag=1, then ignore events with non-zero status.
  If flag=0, then accept all events.

EXAMPLE
  if (length( where( s.status !=0 ) ) > 0 ) aglc_set_status_filter(1);

SEE ALSO
   aglc,  aglc_phased

aglc_set_regs

SYNOPSIS
  Set the spatial binning regions (cross-dispersion) for the source
  and backgrounds on both sides, and compute the background scaling
  factors.

USAGE
  aglc_set_regs( s_min, s_max, b_lo_min, b_lo_max, b_hi_min, b_hi_max );

DESCRIPTION

  Limits are given in cross-dispersion coordinates, tg_d, in units of
  degrees.

  s_min = source minumum tg_d.  The center of the source region is defined
          as tg_d = 0.

  s_max = source region maximum tg_d.
  b_lo_min = background minimum, on the "low" side (tg_d < 0).
  b_lo_max = background maxmimum, on the "low" side (tg_d < 0).
  b_hi_min = background minimum, on the "high" side (tg_d < 0).
  b_hi_max = background maxmimum, on the "high" side (tg_d < 0).

  The limits follow the constraint that

     b_lo_min < b_lo_max <= s_min < s_max <= b_hi_min < b_hi_max.

  Default values are the same as the default spectral extraction
  regions of tgextract:

	s_min    = -6.6e-04   [ deg ]
	s_max    =  6.6e-04   [ deg ]
	b_lo_min = -6.0e-03   [ deg ]
	b_lo_max =  s_min     [ deg ]
	b_hi_min =  s_max     [ deg ]
	b_hi_max =  6.0e-03   [ deg ]

EXAMPLE

  aglc_set_regs( -7.e-4, 7.e-4, -6.6e-3, -8.e-4, 8.e-4, 6.6e-3 ) ;

SEE ALSO
  aglc_reset_regs, aglc_get_regs

aglc_reset_regs

SYNOPSIS
  Reset the source and background binning regions (in cross-dispersion
  direction) to their defaults.  Calculate and store background scale
  factors.

USAGE
  aglc_reset_regs;

DESCRIPTION
  Reset to defaults.

EXAMPLE
  print( aglc_get_regs );   % Are they as desired? if not...
  aglc_reset_regs;

SEE ALSO
  aglc_set_regs, aglc_get_regs

aglc_get_regs

SYNOPSIS
  Retrieve stored source and background regions (cross-dispersion
  limits), and associated BACKSCAL values.

USAGE
  r = aglc_get_regs;

DESCRIPTION
  Retrieves a structure containing the stored values used for binning
  light curves for source or background.

EXAMPLE
  isis> print(aglc_get_regs);
      s_min = -0.00066
      s_max = 0.00066
      backscale = NULL
      src_backscale = 1
      bkg_backscale = 8.09091
      b_lo_min = -0.006
      b_lo_max = -0.00066
      b_hi_min = 0.00066
      b_hi_max = 0.006


SEE ALSO
  aglc_set_regs, aglc_reset_regs

aglc_filter

SYNOPSIS
   Apply a time or phase filter specified to the event structures.

USAGE
   s = aglc_filter( c_struct, ev_struct, c_bin_list );

DESCRIPTION
   Given an index list, c_bin_list, derived from a light or phase
   curve histogram, use the reverse histogram indices in the curve
   structure, c_struct, and filter the events to include only the
   events binned into the index list.  Return a new event structure,
   s, suitable for input to aglc() or aglc_phased().

   The input c_struct is as returned by aglc() or aglc_phased().  The reverse
   indices are saved by the histogram functions and keep lists of all
   indices contributing to a bin value.

   The input ev_struct is an event structure as returned by
   aglc_read_events().

EXAMPLE
  s = aglc_read_events( fevt_1a, fevt );
  ephem = [ 2452506.4328, 0.27831149 ] ;
  p = aglc_phased( s, [0.0, 1.0, 0.02], ephem, 1.7, 25, ["H","M"], [-1,1] );

  % Select events from a phase range and filter:
  s_new = aglc_filter( p, s, where(p.phase_min > 0.5) );

SEE ALSO
  aglc_read_events, aglc, aglc_phased

aglc_phased

SYNOPSIS
   Bin a phased light curve.

USAGE
    pc = aglc_phased(tgevt, expno_ref, phase_info, ephem, wmin, wmax, tg, orders[, bkg]);
    pc = aglc_phased(          evt_struct, phase_info, ephem, wmin, wmax, tg, orders[, bkg]);

DESCRIPTION

 Arguments are similar to those in aglc, with the exception of
 phase_info and ephem.  For other arguments, see aglc.

 phase_info  = a 3-element array giving the phase minimum, maximum,
	       and bin size desired for the resultant phased light
	       curve.

 ephem = a two-element array giving the JD of zero phase (NOT MJD!)
          and the period in days.

EXAMPLE
  s = aglc_read_events( fevt_1a, fevt );
  ephem = [ 2452506.4328, 0.27831149 ] ;
  p = aglc_phased( s, [0.0, 1.0, 0.02], ephem, 1.7, 25, ["H","M"], [-1,1] );

SEE ALSO
    aglc, aglc_filter, aglc_read_events;

Definitions for Phase Curve Structure Fields

1. phase: Value of phase at the bin center.
2. phase_min: Value of phase at the low edge of the bin.
3. phase_max: Value of phase at the high edge of the bin.
4. epoch: Epoch of the ephemeris, in Julian Days ({NOT MJD!}).
5. period: Period of the ephemeris, in days.

aglc_get_ephem

SYNOPSIS
  Retrieve a stored ephemeris, the last one used.

USAGE
  (jd0, pd) = aglc_get_ephem;

DESCRIPTION
   jd0 will be the Julian day of zero phase.
   pd  will be the period in days.

EXAMPLE
  (j,p) = aglc_get_ephem;


SEE ALSO
  aglc_pr_ephem, aglc_phased

aglc_pr_ephem

SYNOPSIS
  Print the stored ephemeris used in the last phase-curve binning.

USAGE
  aglc_pr_ephem

DESCRIPTION
  Retrieves the ephemeris stored by aglc_phased and prints to
  terminal.

EXAMPLE
  isis> aglc_pr_ephem;
  Epoch[JD] = 2443604.591400, Period[day] =   0.267817

SEE ALSO
   aglc_get_ephem, aglc_phased

aglc_set_trange

SYNOPSIS
    Set a simple time range filter to be applied to a light curve
    before extracting a phase-binned curve. This is useful for
    excluding flares, which seem to predominantly occur at the
    beginning or end of an observation.

USAGE
     aglc_set_trange( tmin, tmax );


DESCRIPTION
     tmin,tmax are relative times in seconds, since the start of the
     observation.   The interval, tmin-tmax, specifies the times of
     interest to be included in phase binning.
     If tmax=NULL, means to the end of the observation.

EXAMPLE
    aglc_set_trange( 0, 2000 );   % first 2ks will be included in phase binning.
    aglc_set_trange( 5000, NULL)  % from 5ks to the end will be selected.

SEE ALSO
  aglc_get_trange, aglc_pr_trange

aglc_get_trange

SYNOPSIS
   Retrieve the time filter which will be applied in phase-binning.

USAGE
 (tmin, tmax) = aglc_get_trange;

DESCRIPTION
     tmin,tmax are relative times in seconds, since the start of the
     observation.

EXAMPLE
 (tmin, tmax) = aglc_get_trange;

SEE ALSO
  aglc_set_trange, aglc_pr_trange;

aglc_pr_trange

SYNOPSIS
  Print to the terminal the current time filter.

USAGE
  aglc_pr_trange;

DESCRIPTION
  Prints the min and max time filter used in binning phase curves.

EXAMPLE
  aglc_pr_trange;
  tmin = 0, tmax = NULL [sec since timezero]

SEE ALSO
  aglc_set_trange, aglc_get_trange;

aglc_tobs_to_jd

SYNOPSIS
  Convert Chandra obervation times, given in seconds since MJDREF, to
  Julian day.

USAGE
  jd = aglc_tobs_to_jd( t_obs, mjdref );

DESCRIPTION
  t_obs is a scalar or array of Chandra times in seconds since MJDREF.
  mjdref is the Modified Julian Day reference, found in Chandra
  headers, or in the aglc event structure.

EXAMPLE
    ()=printf("%12.4f\n", aglc_tobs_to_jd( s.tstart, s.mjdref )) ;
    2451659.6919

SEE ALSO
  aglc_jd_to_rotnum, aglc_jd_to_phase, aglc_tobs_to_phase, aglc_read_events

aglc_jd_to_rotnum

SYNOPSIS
  Convert Julian days to rotation number.

USAGE:
    rotation_number = aglc_jd_to_rotnum( t_jd, hjd_epoch, period_days );

DESCRIPTION
    rotation_number = number of full cycles plus fractional phase,
                      given an ephemeris.
    t_jd        = times, in Julian day numbers.
    hjd_epoch   = epoch of zero-phase, in HJD
    period_days = period, in days.

EXAMPLE
   isis> c = aglc( s, 2000, 1.7, 25, ["h", "m"], [-1,1] );
   isis> yrange(0); xrange(0);
   isis> jd = aglc_tobs_to_jd( c.time, s.mjdref );
   isis> r = aglc_jd_to_rotnum( jd, jd0, pd );
   isis> plot( r-min(r), c.count_rate );


SEE ALSO
   aglc_tobs_to_jd, aglc_jd_to_phase, aglc_tobs_to_phase, aglc_phased, aglc

aglc_jd_to_phase

SYNOPSIS
    Convert a list of times to phase, given an ephemeris.

USAGE:
   phase = aglc_jd_to_phase( t_jd, hjd_epoch, days_period );

DESCRIPTION
    phase       = rotation_number modulo 1;
                  fractional phase, given an ephemeris.

    t_jd        = times, in Julian day numbers.
    hjd_epoch   = epoch of zero-phase, in HJD
    period_days = period, in days.

    This can be useful for plotting multple cycles without binning on
    phase.

    This is functionally equivalent to  aglc_jd_to_rotnum() mod 1.

EXAMPLE
   isis> c = aglc( s, 2000, 1.7, 25, ["h", "m"], [-1,1] );
   isis> yrange(0); xrange(0);
   isis> jd = aglc_tobs_to_jd( c.time, s.mjdref );
   isis> r = aglc_jd_to_rotnum( jd, jd0, pd );
   isis> plot( r-min(r), c.count_rate );
   isis> p = aglc_jd_to_phase(  jd, jd0, pd );
   isis> connect_points(0); pointstyle(4);
   isis> plot( p, c.count_rate);

SEE ALSO
   aglc_jd_to_rotnum, aglc_tobs_to_phase, aglc, aglc_phased

aglc_tobs_to_phase

SYNOPSIS
  Convert Chandra observation times to phase, given an ephemeris.

USAGE
  phase = aglc_tobs_to_phase( tobs, mjdref, ephem );

DESCRIPTION
  phase  =  phase for given times and stored ephemeris.
  tobs   =  observed times, in seconds since mjdref
  mjdref =  Reference MJD (from Chandra header or aglc event  structure)
  ephem  =  Two-element array specifying ephemeris.
            ephem[0] = Epoch JD of phase 0.00.
            ephem[1] = Period in days.

EXAMPLE
 ephem = [ 2452506.4328, 0.27831149 ] ;
  p = aglc_tobs_to_phase( c.time, s.mjdref, ephem ) ;

SEE ALSO
  aglc_jd_to_rotnum, aglc_jd_to_phase,
  aglc_tobs_to_jd,  aglc_read_events, aglc, aglc_phased

aglc_write_curve

SYNOPSIS
       Write a light or phase curve to a FITS bintable file

USAGE
	aglc_write_curve( outfile, hdr_ref_file, curve_struct [, history_string ] );" );


DESCRIPTION
    outfile = name of output file (String_Type).
    hdr_ref_file =  Reference file for copying of header info (String_Type).
    curve_struct =  The light or phase curve structure, as created by
                    aglc() or aglc_phased().
    history_string = arbitrary note (String_Type).

EXAMPLE

    c = aglc( s, 2000, 1.7, 25, ["h", "m"], [-1,1] );
    aglc_write_curve( "Myfile.lc", s.fevt_1a, c, "HEG, MEG, -1, 1, 1.7-25A" );

SEE ALSO
  aglc, aglc_phased