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 requires several inputs to function separately.
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 date 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.
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.
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.
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.
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.
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.
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).
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 or higher.
EARTHPNT_LON and _LAT are the longitude and latitude of the viewed point on the earth's surface.
If the earth is not in the field of view, all of these quantities are set to the point of closest approach of the view ray, which may be the satellite's own location.
EARTHPNT_RANGE is the range from the spacecraft to the viewed point. If the value is zero or negative, then ABS(EARTHPNT_RANGE) indicates the range of the point of closest approach.
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%.
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.
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,
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.
Name Format[Units](Range) Comment
SUN_RA 1E [deg] RA of sun (equatorial) (ALLV3)
SUN_DEC 1E [deg] Dec of sun (equatorial) (ALLV3)
MOON_RA 1E [deg] RA of moon (equatorial) (ALLV3)
MOON_DEC 1E [deg] Dec of moon (equatorial) (ALLV3)
EARTH_RA 1E [deg] RA of earth (equatorial) (ALLV3)
EARTH_DEC 1E [deg] Dec of earth (equatorial) (ALLV3)
SUNSHINE 1I 1=in sunshine; 0=not (ALLV3)
the following entries are available when selecting ALLV5 and higher
SUN_ELV 1E [deg] angle between sun and earth limb (ALLV5) TIME_SINCE_SUNSET 1E [s] time since last SUNSHINE=1 (ALLV5) TIME_SINCE_SUNRISE 1E [s] time since last SUNSHINE=0 (ALLV5) TERMINATOR_ANGLE 1E [deg] angle between nadir and day-night terminator (ALLV6) DAYLIT_FRACTION 1E fraction of earth illuminated (ALLV6)
This group of columns describes the positions of various celestial bodies. The (RA,DEC) values are the J2000 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 ALLV6. TERMINATOR_ANGLE is the angle between the nadir and the day-night terminator plane. A negative angle indicates a terminator on the sunward side of the nadir, and a null indicates the terminator is not visible from the S/C. DAYLIT_FRACTION is the fraction of the earth's surface illuminated by the sun. Note that these columns are approximate and do not account for the flattened oblate spheroid nature of the earth.
Name Format[Units](Range) Comment
SUN_VECTOR 3E [km] vector from earth center to sun
SATSUN_VECTOR 3E unit vector from sat. to sun (J2000)
SUN_BODY_VECT 3E unit vector of sun in body frame
SUN_BODY_AZIMUTH E [deg] azimuth angle of sun in body frame (ALLV6)
MOON_VECTOR 3E [km] vector from earth center to moon
SATMOON_VECTOR 3E unit vector from sat. to moon (J2000)
MOON_BODY_VECT 3E unit vector of moon in body frame
MOON_SIZE 1E [deg] Moon apparent diameter (ALLV5)
MOON_PHASE 1E [deg] Moon phase (0=new; 180=full) (ALLV5)
MOON_ILLUM 1E [deg] Moon illuminated fraction (0-1) (ALLV5)
MOON_BODY_AZIMUTH E [deg] azimuth angle of moon in body frame (ALLV6)
SATEARTH_VECTOR 3E unit vector from sat. to earth (J2000)
EARTH_BODY_VECT 3E unit vector of earth in body frame
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.
SATSUN_VECTOR, SATMOON_VECTOR and SATEARTH_VECTOR provide the unit vectors from the spacecraft (and not the geocenter) to the sun, moon and earth center, respectively, in the J2000 inertial coordinate system.
SUN_BODY_VECT, MOON_BODY_VECT and EARTH_BODY_VECT provide the unit vector of the respective body in the body (instrument) coordinate frame. NOTE: the *_VECTOR and *_VECT columns are not selected by default with any shortcuts and if desired, but be entered manually in the columns parameter.
SUN_BODY_AZIMUTH and MOON_BODY_AZIMUTH are the azimuth angle of the sun and moon, respectively, in body frame coordinates. A value of 0 indicates a sun/moon that lies in the instrument's (+X)(+Z) plane. A value of +90 indicates a sun/moon that lies in the in the instrument's (+Y)(+Z) plane.
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).
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 no 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 and higher 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 set tlookback larger than 86400 (about a day). To enable this, set orbpropagate=YES outpropagate=NO.
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.
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=50000The 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.
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.