========================================================================
 Proposed changes in D4 FITS file format
   December 20th, 2007
   Masaharu Hirayama
   James Peachey
------------------------------------------------------------------------
1) Ephemerides extensions

Current design:

  A D4 FITS file has two extensions for ephemerides, one for pulsars'
  spin parameters and the other for binary orbital parameters for DD
  model.

    SPIN_PARAMETERS     RA, Dec, f0, f1, f2
    ORBITAL_PARAMETERS  Parameters for DD model

Proposed design:

  A D4 FITS file can have as more than two extensions for ephemerides,
  each of which contains parameters for a certain ephemeris type. An
  ephemeris type can be a representation of pulsars' spin parameters,
  and a set of parameters for a certain binary orbital model. There
  are a few ways to organize multiple ephemeris types in separate
  extensions in this design.

  [Baseline]
  An extension name (EXTNAME) specifies which kind of parameters it
  contains, pulsars' spin parameters or binary orbital parameters, and
  a new header keyword (EPHTYPE) indicates what type of representation
  of ephemeris it contains, e.g., frequency-domain or period-domain
  for pulsars' spin parameters, and a name of binary model for binary
  orbital parameters.

    EXTNAME = SPIN_PARAMETERS
    EPHTYPE = FREQ, PER, FREQ3, FREQ4, ...

    EXTNAME = ORBITAL_PARAMETERS
    EPHTYPE = DD, ELL1, ...

  [Alternative 1]
  Same as the baseline, but with a number at the end of each extension
  name (EXTNAME).

    EXTNAME = SPIN_PARAMETERS1, SPIN_PARAMETERS2, ...
    EPHTYPE = FREQ, PER, FREQ3, FREQ4, ...

    EXTNAME = ORBITAL_PARAMETERS1, ORBITAL_PARAMETERS2, ...
    EPHTYPE = DD, ELL1, ...

    Pros: All extensions has different names in a single FITS file.

    Cons: Extension names can conflict with each other when two FITS
          files are combined with FTOOLS or something equivalent.

  [Alternative 2]
  Similar to the baseline, but EXTNAME and EPHTYPE are concatenated
  and assigned to an extension name (EXTNAME).

    SPIN_PARAMETERS_FREQ   RA, Dec, f0, f1, f2
    SPIN_PARAMETERS_PER    RA, Dec, p0, p1, p2
    SPIN_PARAMETERS_FREQ3  RA, Dec, f0, f1, f2, f3
    SPIN_PARAMETERS_FREQ4  RA, Dec, f0, f1, f2, f4
    ...
    ORBITAL_PARAMETERS_DD    Parameters for DD model
    ORBITAL_PARAMETERS_ELL1  Parameters for ELL1 model
    ...

    Pros: All extensions has different names in a single FITS file.
          There is no new header keyword introduce. As a result, it is
          easier to browse a D4 FITS file with FTOOLS, such as fv.

    Cons: Extension names need to be parsed. It is computationally
          less straightforward to find all extensions that contain
          ephemeris data.

------------------------------------------------------------------------
2) Special event extension

  Add new extension that designates time intervals during which
  pulsar's spin ephemerides are not reliable.  It may contain a time
  interval when a pulsar is glitching, exhibiting a large timing noise
  which prevents a timing solution from accurately modeling timing
  behavior of pulsation.

  EXTNAME = <TDB>
  Candidate: SPECIAL_EVENTS, GLITCH, BTI (Bad Time Interval).

  Columns: PSRNAME, SINCE, and UNTIL.
    PSRNAME: pulsar name
    SINCE: integer MJD of the beginning of a special event
    UNTIL: integer MJD of the end of a special event
    EVENT_TYPE: character string indicating a type of event, such as
                "GLITCH" and "NOISY".
    OBSERVER_CODE: character string indicating an observer (same as
                   the ones in spin and orbital parameter extensions).

  Note: Need to determine whether or not the beginning and the end of
        an interval may need a fractional part of its MJD.

------------------------------------------------------------------------
3) Special event handling in event files

  Remove (or select) events during a glitch and/or a ephemeris gap
  with gtselect before running a pulsar tool. Need a GTI creator tool
  that reads ephemerides extensions and a special event extension and
  outputs an GTI extension in the FITS format.

  Use of GTI's gives a natural connection between a temporal analysis
  and a spectral analysis, e.g., existing tools can handle exposure
  computations for photons selected by pulsar ephemeris data.  A GTI
  creator tool can be used to check whether an event file is covered
  by ephemerides in a D4 FITS file.

  A technical difficulty is that it needs to treat times in a D4 FITS
  file as barycentric times and convert them back to original photon
  arrival times as mission elapsed times, in order to match them with
  event times in TIME column of an event file.

  [Alternative]
  Add new column, EPH_QUALITY, that indicates whether the photon is
  covered by a reliable ephemeris or not. It takes an integer number,
  which means:

    -2: the event time is not covered by a spin ephemeris,
        and falls in a special event interval.

    -1: the event time is covered by a spin ephemeris,
        but falls in a special event interval.

     0: ephemeris quality not assigned yet.

     1: the event time is not covered by a spin ephemeris,
        but does not fall in a special event interval, either.

     2: the event time is covered by a spin ephemeris,
        and does not fall in a special event interval.

    Pros: Event selections can be applied with any combination of
          EPH_QUALITY column values.

    Cons: Need a separate tool for exposure computation after event
          selections are made based on EPH_QUALITY column values.

========================================================================