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
   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.

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)
   BETA_ANGLE         1E [deg]             angle between sun and orbit plane

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.

BETA_ANGLE is a purely orbital quantity, the angle between the orbital plane and the sun. This value is typically related to the durations of orbit day and orbit night, and hence solar input (i.e. possible satellite power and thermal correlations).

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. Note that SAA_TIME may be calculated more correctly (fewer "unknowns") using extrapolation techniques described below.

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 units 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.

Trapped Charge Models (ALLV5)

    Name             Format[Units](Range)      Comment
   AE8MIN             1E [cm**(-2) s**(-1)]AE8 minimum trapped electron flux
   AE8MAX             1E [cm**(-2) s**(-1)]AE8 maximum trapped electron flux
   AP8MIN             1E [cm**(-2) s**(-1)]AP8 minimum trapped proton flux
   AP8MAX             1E [cm**(-2) s**(-1)]AP8 maximum trapped proton flux

These quantities represent modeled values of trapped geomagnetospheric charge.

All values come from the trapped radiation models known as AE8 for electrons, and AP8 for protons. These models were developed in the mid-1970s, using data taken by space-based monitors during solar minimum (1964) and solar maximum (1970). These quantities are provided by NASA's NSSDC, and may also be cited as,

Additional code and references may be found at the NSSDC's website, https://ccmc.gsfc.nasa.gov/pub/modelweb/radiation_belt/radbelt/fortran_code/ .

While these quantites may be useful for particle background modeling of space-based observatories, there are a number of limitations inherent in the models.

First of all, the models are not time-variable. They provide a snapshot of geomagnetospheric conditions in 1964 and 1970. As trapped charge conditions can change on an hourly basis, especially electrons, the AE8/AP8 models can only be considered as an approximate "guideline" of where radiation belts are located. This may be useful for mission simulations, or as a background modeling indicator, but cannot be used for historical (or forecasting) of actual conditions at a certain date.

The AE8 and AP8 models are based on upon limited space-based particle monitors, available in the mid to late 1960s. Since that time additional data has become available, and has been incorporated into new higher fidelity models.

Also, the models are based upon the magnetic field arrangement in the mid-late 1960s. The geomagnetic field structure does gradually change over time. Although the change per year is small, the accumulated change over ~50 years can be significant.

With all the caveats above being said, the AE8 and AP8 models are relatively simple and useful models to get an approximate idea where trapped charges are located in an observatory's orbit. The simplicity and heritage of the model makes it a useful and fast-running quantity that may be helpful in diagnosing observatory data.

The values are provided as the integral flux above the threshold energy, in units of particles / cm**2 / s**1. The threshold may be specified for electrons and protons independently using the ae8threshen and ap8threshen parmeters, respectively, in unites of MeV. Reported values of 1 or below are considered as no measureable flux in the model.

Positions of Bodies (ALL,ALLV3; some ALLV5)

    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)
   SUNSHINE           1I                   1=in sunshine; 0=not
the following entries are available when selecting ALLV5 and higher
   SUN_ELV           1E [deg]              angle between sun and earth limb
   TIME_SINCE_SUNSET 1E [s]                time since last SUNSHINE=1
   TIME_SINCE_SUNRISE 1E [s]               time since last SUNSHINE=0

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.

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

Requires ALLV5. SUN_TIME gives the time since last orbit day (SUNSHINE==1), in seconds. SUN_TIME may benefit from "extrapolation" as described below. SUN_ELV is the angle in degrees of the sun above the earth's limb (requires ALLV5 or higher).

Sun and Moon Body Information (ALLV5)

    Name             Format[Units](Range)      Comment
   SUN_VECTOR         3E [km]              vector from earth center to sun
   MOON_VECTOR        3E [km]              vector from earth center to moon
   MOON_SIZE          1E [deg]             Moon apparent diameter
   MOON_PHASE         1E [deg]             Moon phase (0=new; 180=full)
   MOON_ILLUM         1E [deg]             Moon illuminated fraction (0-1)

These columns provide sun and moon body information.

SUN_VECTOR and MOON_VECTOR provide the position vectors of the sun and moon, respectively, as measured from the geocenter, in the J2000 reference frame. NOTE: these columns are not selected by default with any shortcuts and if desired, but be entered manually in the columns parameter.

MOON_SIZE is the apparent angular diameter of the moon as seen from the earth. MOON_PHASE is the moon phase expressed as an angle, where 0 is a new moon and 180 degrees is a full moon. Technically this is the mean elongation of the moon.

MOON_ILLUM is the illuminated fraction of the moon. This number ranges from 0 (completely new) to 1.0 (completely full).

EXTRAPOLATION

Some orbit events are history sensitive. For example, SAA_TIME may depend on an SAA which does not intersect with the input files (either before the input orbit file starts, or in gaps of the orbit file). Thus, it is possible for an observation that begins right after exiting SAA to have in indication of that in the filter file. This is undesirable, since some efforts like background modeling efforts may need to know time since actual SAA.

As of version 5 of prefilter, the task can account for this. It can calculate "backward in time," before the start of the observation and detect any history sensitive events. This is set by the tlookback parameter. Set tlookback to a value in seconds, to can back in time before the parameter "start". All orbital events are calculated as normal by prefilter (which means that execution time increases). Attitude information may or may not be present; prefilter will use that data if it is present, but it is typically not relevant for history-sensitive events, so most callers of prefilter should set attfile as normal.

For a typical low earth orbit satellite mission that prefilter is designed to support, SAA passes happen within about a half-day, and daylight transitions happen every 90 minutes. Therefore, setting tlookback=50000 should catch at least one previous SAA and one sunshine transition.

To do this type of extrapolation, prefilter must be able to propagate the orbit backward and forward in time. For TLE-style orbit files, this is straightforward. For XTE-style tabulated ephemerides, prefilter has the capability to estimate orbital elements and propagate the orbital state to epochs not covered by the ephemeris. It is not wise to do this for more than about a day. To enable this, set orbpropagate=YES outpropagate=NO.

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].
(orbpropagate=NO) [boolean]
Only applicable if XTE-style orbit file is used (orbmode=XTE). If set, then propagate orbit beyond limits of the orbit file, including bridging between gaps in orbit file. If not set (the default), then prefilter will not calculate times that are outside of the tabulated orbit ephemeris.
(outpropagate=NO) [boolean]
Only applicable if XTE-style orbit file is used (orbmode=XTE), and if orbpropagate=YES. If set, then propagated orbit samples are output. If not set (the default), those samples are not output. Note that this parameter only governs samples that are between 'start' and 'end', inclusive. Extrapolated samples outside of this range are never output (i.e. if using tlookback > 0).
(ae8threshen=0.04) [real]
The threshold energy in MeV for electrons in the AE8 model. Reported fluxes in the AE8MIN and AE8MAX output columns will be the flux above the specified energy.
(ap8threshen=0.1) [real]
The threshold energy in MeV for protons in the AP8 model. Reported fluxes in the AP8MIN and AP8MAX output columns will be the flux above the specified energy.
(tlookback=0) [real]
Set to non-zero number of seconds to calculate quantities before "start".
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

3. For low-earth orbit spacecraft, use the following settings

	orbpropagate=YES outpropagate=NO tlookback=50000
The parameter orbpropagate=YES will propagate a tabulated ephemeris back in time by tlookback=50000 seconds. (If orbmode=TLE, then the input orbit is already propagatable, but it does not hurt to set orbpropagate=YES). The outpropagate=NO setting will cause no propagated entries to actually be written to the output, although history-sensitive values like SAA_TIME will be preserved. The value of 50000 seconds is the approximate maximum time between SAA passes, although it could be tuned to a particular style of mission.

SEE ALSO

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

LAST MODIFIED

December 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.