NAME

prefilter - Derive attitude and orbit related quantities.

USAGE

prefilter

DESCRIPTION

prefilter derives attitude and orbit related quantities based on pointing and position information.

prefilter takes as both an orbit and attitude file for the observatory. Several formats are supported.

prefilter combines this information into a single output file, commonly known as a "filter file," which can be used for observatory-related data screening. Many useful orbit- and pointing-related quantities are recorded in the output. The outputs of prefilter are meant to be mission-generic, that is, useful for screening of data from many observatories.

Since the inputs to prefilter are of a highly technical nature, it is expected that prefilter itself will mostly be run by higher-level observatory pipeline tasks developed by observatory software developers. However there is nothing stopping any science analyst from using this task, as long as the proper inputs and settings are used.

Observatories with other mission-specific screening criteria can either create a separate filter file or append columns to the output of prefilter.

The following documentation describes the inputs and outputs of the prefilter task.

PREFILTER INPUTS

Prefilter requires several inputs to function separately.

  1. Orbit file. The observatory orbit file must be provided (task parameter orbname), for vehicles orbiting the earth. The orbit file may be one of several formats. Orbit data will be interpolated to the desired time sampling.
  2. Attitude file. The orbservatory pointing (attitude) file must be provided (task parameter attname). The attitude file must be a FITS file of the format used by the "coordfits" library. Generally, there must be a TIME column, as well as a column named QPARAM, which is a 4-vector column containing quaternion data. Quaternions are unit-normalized and QPARAM(4) is the scalar part. A special notation attname=QUAT(0,0,0,1) can be used when pointing is not important. The numbers may specify any unit quaternion.
  3. Instrument alignment. If the spacecraft or instrument is not co-aligned with the attitude provided in the attitude file, an alignment file, also known as a teldef file, can be provided (task parameter alignfile). This is a FITS file with primary header only, than specifies a matrix transformation between the attitude and instrument coordinate systems.
  4. Leap second file. By default, uses the HEASoft refdata leap second data (task parameter leapname).
  5. Orbital rigidity file. Used by the COR_ASCA calculator for magnetic cut-off rigidity (task parameter rigname). By default, uses the HEASoft refdata rigidity map.

TIME

Prefilter computes the desired quantities on a regularly sampled time grid. The users specifies task parameters start, stop and interval, all in seconds of mission elapsed time, and the task uses that information to construct uniformly sampled time grid.

For mission times, prefilter uses the missepoch task parameter to specify the mission epoch as a UTC data and time. All mission elapsed times are in seconds from that epoch.

Note that while the mission epoch is in UTC, the start and end parameters are expressed in the time system of the attitude file. The time system and related keywords (TIMESYS, TIMEUNIT, MJDREF*, ...) are copied from the input attitude file to the output.

For output TIME column takes values <start> + k * <interval>. The output TIME_ADJ column takes values TIME + offset where offset is controlled by the <timeadj> parameter. timeadj allows a time correction to be applied to the TIME values. The TIME value is used unchanged when looking up TIME in the attitude file, but for other output columns, TIME_ADJ is used. The time adjustment may be particularly important when calculating position and several other output columns are dependent on position.

While the intent is to create an output with regularly sampled TIME-stamps, it is possible for the output to not be regularly sampled. If input attitude samples are missing for a given time range, then no output row will be created. In most cases this is the desirable behavior, especially for observatories with multiple disjoint snapshots of a target in a single observation. In that case entries will only appear in the output file during the snapshots and not at other times.

OUTPUT COLUMNS

The user can select which columns are computed using the task parameter "columns." Since there are many typically-desired columns prefilter allows some "short-cut" names which select more than one column name at once.

Note that the default when using columns="ALL" is equivalent to using columns available in prefilter version 3, even if more columns are available in later versions. This is to preserve compatibility with existing users of prefilter which may rely on specific columns being present.

It is also possible to mix a shortcut with extra column names, or to exclude certain column names using -COLNAME syntax. For example, this expression,

       columns="ALLV3 MAGUNIT"
will start with the selection of "ALLV3" and then add the MAGUNIT column to the column selection. This expression,
       columns="ALLV3 -TIME_ADJ MAGUNIT"
will start with the selection of "ALLV3", exclude TIME_ADJ and add MAGUNIT. If the first column name begins with an exclusion, such as this,
       columns="-TIME_ADJ"
then it is assumed that the baseline selection is "ALLV3", and then TIME_ADJ is excluded from that selection.

Please note that any short-cut name must appear first in the list and you cannot use the "-" exclusion syntax on short-cut names.

Below is a more detailed description of columns.

Please see prefilter implementation notes for specific implementation information about how the output columns are computed.

Basic Columns (ALL,ALLV3)

    Name             Format[Units](Range)      Comment
   TIME               1D [s]               seconds since mission epoch
   POSITION           3E [km]              ECI position of satellite [X,Y,Z]
   VELOCITY           3E [km/s]            ECI velocity of satellite [X,Y,Z]
   QUATERNION         4E                   attitude quaternion
   PNTUNIT            3E                   pointing unit vector
   TIME_ADJ           1D [s]               adjusted seconds since mission epoch

These are the basic columns containing the interpolated spacecraft position, velocity, and pointing direction.

TIME is measured in seconds since the mission epoch.

POSITION is measured in km, in earth-centered inertial coordinates (also known as GCI). VELOCITY is measured in km/s in the same coordinate system.

QUATERNION is the interpolated observatory attitude quaternion.

TIME_ADJ is an "adjusted" timestamp. See the documentation for the task parameter "timeadj" below for more information.

Celestial pointing direction (ALL,ALLV3)

    Name             Format[Units](Range)      Comment
   RA                 1E [deg]             pointing axis right ascension
   DEC                1E [deg]             pointing axis declination
   ROLL               1E [deg]             pointing axis roll

The RA, DEC and ROLL columns are the spacecraft pointing referred to the celestial sphere. They are the standard astronomical right ascension, declination, measured in degrees. The roll angle is the observatory roll angle in degrees.

Spacecraft Derived Location (ALL,ALLV3)

    Name             Format[Units](Range)      Comment
   POLAR              3E [rad, rad, km]    geodetic radius lat lon
   SAT_LAT            1E [deg]             sub-satellite point latitude
   SAT_LON            1E [deg]             sub-satellite point longitude
   SAT_ALT            1E [km]              distance from earth center

SAT_LAT and SAT_LON are the spacecraft geodetic latitude and longitude, measured in degrees. SAT_ALT is the spacecraft altitude above the mean earth surface, in km.

POLAR is the [lat,lon,radius] 3-vector.

Derived Pointing (ALL,ALLV3)

    Name             Format[Units](Range)      Comment
   ELV                1E [deg]             angle between pointing and earth limb
   BR_EARTH           1E [deg]             angle between pointing and bright earth
   SUNSHINE           1I                   1=in sunshine; 0=not
   FOV_FLAG           1I                   0=sky; 1=dark earth; 2=bright earth
   SUN_ANGLE          1E [deg]             angle between pointing and sun vector
   MOON_ANGLE         1E [deg]             angle between pointing and moon vector
   RAM_ANGLE          1E [deg]             angle between pointing and velocity vector
   ANG_DIST           1E [deg]             angular distance of pointing from nominal

These columns provide derived pointing information.

ELV is the elevation of the pointing direction above the earth's mean limb, in degrees. BR_EARTH is the angle between the pointing direction and the sunlight-illuminated bright earth, in degrees, or 200 if the bright earth is not visible. FOV_FLAG indicates whether sky, dark earth or bright earth are visible at the spacecraft pointing direction.

SUNSHINE indicates if the spacecraft is experiencing orbit day (1) or night (0).

SUN_ANGLE and MOON_ANGLE are the angular distances between the pointing direction and the sun and moon, respectively, in degrees. RAM_ANGLE is the angular distance between the pointing direction and the spacecraft velocity vector, in degrees.

ANG_DIST is the angular distance between the pointing direction and the "nominal" direction given by task parameters ranom and decnom. If ranom and decnom are the target location, then ANG_DIST is the angular distance from the target.

Additional Derived Pointing (ALLV4)

   ZENITH_ANGLE       1E [deg]             angle between pointing and zenith
   EAST_ANGLE         1E [deg]             angle between pointing and East
   NORTH_ANGLE        1E [deg]             angle between pointing and North
   BEARING_ANGLE      1E [deg]             bearing of pointing (North=0 East=90)
   LOCAL_TIME         1E [deg]             spacecraft apparent solar time (180 deg=noon)

These columns provide enhanced pointing information, which may be useful for background estimation, and are only available if columns=ALLV4.

ZENITH_ANGLE, EAST_ANGLE and NORTH_ANGLE provide the angle between the pointing direction and the local zenith, east and north angles, respectively.

The BEARING_ANGLE quantity is the navigational bearing angle of the pointing direction. In other words, it is the azimuthal angle of the pointing direction where north is 0 degrees and east is 90 degrees.

LOCAL_TIME is the apparent solar time at the spacecraft position, expressed in degrees. At local noon (LOCAL_TIME=180) the sun and spacecraft are at the same geographic longitude position.

Earth View Quantities (ALLV4)

    Name             Format[Units](Range)      Comment
   EARTHPNT_LON       1E [deg]             earth viewed longitude
   EARTHPNT_LAT       1E [deg]             earth viewed latitude
   EARTHPNT_RANGE     1E [km]              range to viewed earth

These quantities represent information about the portion of the viewed earth within the field of view. It is the intersection beween the spacecraft pointing direction and the earth surface. These quantities are only available if columns=ALLV4.

EARTHPNT_LON and _LAT are the longitude and latitude of the viewed point on the earth's surface.

EARTHPNT_RANGE is the range from the spacecraft to the viewed point.

If the earth is not in the field of view, all of these quantities are NULL.

Geomagnetic Quantities (ALL,ALLV3)

    Name             Format[Units](Range)      Comment
   SAA                1I                   1=in SAA; 0=not
   SAA_TIME           1E [s]               time since entering/exiting SAA
   COR_ASCA           1E [GeV/c]           magnetic cut off rigidity (ASCA map)
   COR_SAX            1E [GeV/c]           magnetic cut off rigidity (IGRF map)
   MCILWAIN_L         1E                   McIlwain L parameter (SAX)

These columns specify items related to the geomagnetosphere.

SAA is a flag indicating if the spacecraft is within the South Atlantic Anomaly (SAA) or not. The SAA contour is a "hard-coded" definition as found within the Attitude library. The SAA_TIME column is the time in seconds since last exiting the SAA, or -999 if unknown. "Unknown" could mean that SAA passage occurred before the start time of the file.

COR_ASCA and COR_SAX are estimates of the geomagnetic cut-off rigidity (COR) value, in units of GeV/c. The COR_ASCA column is of limited use because it is based on a table-lookup specific to the ASCA orbit. The COR_SAX column is computed using modern geomagnetic field models based on the actual spacecraft orbit.

MCILWAIN_L is McIlwain's "L-shell" parameter. For a given spacecraft position, a magnetic field line will connect that position to the geomagnetic equator. The radial distance to that equatorial point, is the L-shell value, in untis of earth radii.

For magnetic fields, the task uses the "geomag" library, which contains the International Geomagnetic Reference Model (IGRF) magnetic field model. In December 2019, IGRF version 13 was released by IAGA, which contains a "definitive" model through the year 2015 and "provisional" trend for 2020 and beyond. As of prefilter v3.7, the spherical harmonic model has been improved from a limited degree-10 expansion to the full degree-13 data set available from the publishers, for years 2000 and onward. Differences from previous "definitive" values are expected to be less than 0.01%.

Magnetic Field Quantities (ALLV4)

    Name             Format[Units](Range)      Comment
   MAGFIELD           1E [G]               Magnetic field value
   MAGFIELD_MIN       1E [G]               Minimum magnetic field same L-shell
   MAGVECT            3E [G]               Magnetic field vector (inertial)
   MAGVECT_POL        3E [G]               Magnetic field vector (radial,north,east)
   MAG_ANGLE          1E [deg]             angle betw pointing and magnetic field vector

These quantities are calculated magnetic field values based on the IGRF, and are only available if columns=ALLV4.

MAGFIELD is the magnetic field magnitude at the spacecraft location.

MAGFIELD_MIN is the minimum magnetic field on the same L-shell as the spacecraft. This quantity is potentially useful because some trapped charge models are parameterized in terms of MCILWAIN_L and (MAGFIELD/MAGFIELD_MIN).

MAGVECT is the magnetic field as a vector quantity, as expressed in the GCI (earth-centered inertial) coordinate system. MAGVECT_POL are the magnetic field vector components in polar coordinates. The components are (radial, north, east), respectively.

MAG_ANGLE is the angle between the magnetic field vector and the pointing direction, in units of degrees.

Positions of Bodies (ALL,ALLV3)

    Name             Format[Units](Range)      Comment
   SUN_RA             1E [deg]             RA of sun (equatorial)
   SUN_DEC            1E [deg]             Dec of sun (equatorial)
   MOON_RA            1E [deg]             RA of moon (equatorial)
   MOON_DEC           1E [deg]             Dec of moon (equatorial)
   EARTH_RA           1E [deg]             RA of earth (equatorial)
   EARTH_DEC          1E [deg]             Dec of earth (equatorial)

This group of columns describes the positions of various celestial bodies. The (RA,DEC) values are the celestial right ascension, in degress, of the body as seen from the observatory. SUN_{RA,DEC} is the position of the sun, MOON_{RA,DEC} is the position of the moon, and EARTH_{RA,DEC} is the position of the earth's center.

PARAMETERS

outname [filename]
Name of the output file. To overwrite a preexisting file with the same name, prefix the name with an exclamation point '!', or set the 'clobber' parameter = YES.
columns ALL|[space-separated-values]|@[filename]
Specifies which derived quantities to output.
orbmode TLE_TEXT2|TLE_TEXT3|TLE_FITS|atSetElement|atSetElement2|XTE
Specifies the orbit mode which controls how orbname will be processed. TLE_TEXT2 and TLE_TEXT3 corresponds to a Two-Line Element file with either two or three plain text lines per element set. TLE_FITS is a Two-Line Element file stored in FITS format. atSetElement and atSetElement2 refer to orbital element files used by the atFunctions library. XTE corresponds to an orbit ephemeris file in the format of RXTE, Chandra or NICER.
orbname [filename]
Name of the orbit file.
attname [filename]
Name of the attitude file.
alignfile [string]
Name of the coordfits alignment file or NONE.
leapname [filename]
Name of the leap second file.
rigname [filename]
Name of the atFunctions rigidity file.
start [real]
Output start time in seconds since mission epoch expressed in TIMESYS.
end [real]
Output end time in seconds since mission epoch expressed in TIMESYS.
interval [real]
Output interval [seconds].
ranom [real]
Nominal right ascension of spacecraft boresight [degrees].
decnom [real]
Nominal declination of spacecraft boresight [degrees].
attextrap [real]
Limit on attitude extrapolation [seconds].
missepoch [string]
Mission epoch in UTC specified as yyyy-dd-mmThh:mm:ss.sss.
(timeadj = DEFAULT) [string]
This parameter can be used to adjust times used for calculations. TIME_ADJ = TIME + offset where the value of offset depends on the value of the timeadj parameter. timeadj=DEFAULT (the default), allows mission-specific determination of offset. timeadj=CONST:<value> sets offset to value. timeadj=KEY:<value> sets offset to the value of a keyword from the attitude file. timeadj=LEAPS sets offset to the opposite of the number of leap seconds since missepoch to start.

Now, back to timeadj=DEFAULT. For the Swift mission, DEFAULT is treated as KEY:UTCFINIT (if that keyword is present), or LEAPS if it is not. For all other missions, DEFAULT is treated as LEAPS. Note that LEAPS is consistent with past behavior.

origin [string]
Value for FITS ORIGIN keyword.
(clobber = NO) [boolean]
If outname already exists, then "clobber = yes" will overwrite it.
(history = yes) [boolean]
If set, HISTORY keywords are written to output.
(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.

EXAMPLES

1. Execute prefilter prompting the user for parameter values.

	prefilter

2. Execute prefilter providing the attitude file name and indicating the TLE file to process on the command line.

	prefilter attname=./ATTITUDE.fits orbmode=TLE orbname=./TLE.fits

SEE ALSO

maketime task for creating GTIs from filter files
prefilter implementation notes
makefilter task (earlier version of prefilter)

LAST MODIFIED

January 2020

prefilter was originally developed for the Swift mission, but it can be used for other missions provided a coordfits style attitude file, and two line elements (or XTE-style orbit ephemeris) are available.