XMM-Newton Science Analysis System


attfilter (attfilter-1.4) [xmmsas_20230412_1735-21.0.0]

Description

attfilter performs exposure-specific attitude data filtering and Good-Time-Interval (GTI) creation driven by a single boolean selection expression. The task generates a single GTI table whose rows represent time intervals during which the spacecraft attitude did not deviate from a given reference attitude by more than a specified tolerance limit. Thus, filtering an event list with this GTI table will eliminate all events that have been detected during times of unfavorable attitude, e.g., short pointing excursions due to loss of guide star(s) by the star tracker system. Although the aspect correction tasks in the SAS, viz. attcalc (EPIC), rgsangles (RGS), and omatt (OM) can correctly treat even large attitude variations attitude GTI filtering is deemed crucial in order to avoid the generation of unnecessarily large sky images and exposure maps and to reduce variability due to sources moving across the face of the detector (e.g. crossing chip gaps, changing vignetting). In the case of RGS this processing step is especially important since the scientific quality of the calibrated event lists and high level products is directly correlated with the stability of the spacecraft during the exposure.

Starting from an attitude data time series as created by atthkgen and a given exposure in the current ODF (pointed at by the environment variable SAS_ODF) attfilter carries out the following operations in sequential order:

1. Inquire the start and end time of the exposure specified via the parameter instexpid
2. Disregard the attitude data (specified via parameter attset) which lie outside the exposure time window
3. Compute the median spacecraft attitude within the exposure time window. In default of a mathematically rigorous definition of this quantity the median attitude is calculated as the composition of the individual medians of:
   • Right Ascension (J2000) of star tracker viewing direction
   • Declination (J2000) of star tracker viewing direction
   • Astronomical position angle of spacecraft
4. Generate a GTI table with the task tabgtigen under the control of a filtering expression which involves the previously computed median spacecraft attitude values and a user-specified set of tolerance angles (see parameter tolangles) $(\alpha_1, \alpha_2, \ldots)$. There are two ways to choose the filtering expression: The user can either give the full expression himself via the parameter expression in conjunction with setting filtertype=user or choose one of two predefined filters (in the following $\vec{P}_{med}$ designates the median and $\vec{P}(t)$ the actual spacecraft pointing direction at time $t$ expressed as unit vectors in the earth-centered J2000 sky reference system):
   1. cone (filtertype=cone):
      
        $$\arccos(\vec{P}(t)\cdot\vec{P}_{med}) \leq \alpha_1$$ (1)
      This equation describes a cone with symmetry axis $\vec{P}_{med}$ and half-opening angle $\alpha_1$.
   2. pyramid (filtertype=pyramid):
      
      

      	$$\left\vert\left(A_{med}\cdot(\vec{P}_{med}-\vec{P}(t))\right)_y\right\vert$$	$\leq$	$$\alpha_1$$
      	$$\left\vert\left(A_{med}\cdot(\vec{P}_{med}-\vec{P}(t))\right)_z\right\vert$$	$\leq$	$$\alpha_2$$

      where $A_{med}$ stands for the direction cosine matrix corresponding to the previously computed median spacecraft attitude and $\vec{v}_y$ and $\vec{v}_z$ designate the $y$ and $z$ components of a vector $v$. The combination of the two equations describes a pyramid with a rectangular base subtending the two half-opening angles $\alpha_1$ and $\alpha_2$. This base rectangle is aligned with the spacecraft $y$ and $z$ axes which in turn are aligned with the RGS cross-dispersion and dispersion direction respectively.

5. Add the median spacecraft attitude values to the new GTI table as attributes MEDI_RA, MEDI_DEC, and MEDI_APA.

The task's main output is a new GTI table in a new or previously existing data set suitable for direct event list filtering.