Table of Contents

1. Introduction
2. Screening Basics
3. Screening Expression Basics
4. Creating a GTI with 'maketime'
5. Recommended Screening Criteria
   1. Recommended Basic and Conservative Screening Criteria
   2. Example Screening Expressions
6. Other Screening
   1. Simple Time Based Constraint
   2. Excluding a Specific Time Range
   3. Advanced: Orbital Phase Constraint
   4. Selecting Data by Intensity Level
7. Combining more than one GTI
8. The Next Steps

Introduction

Once you have created a set of prepared results, either from a single observation or the result of merging multiple observations, you are ready to start performing filtering. At a basic level, filtering removes bad data and keeps good data for scientific analysis. But which is bad and which is good? This is partly a mechanical set of criteria that remove known bad data, but this is also a stage where more scientific judgement enters into the picture as well.

Screening means getting rid of invalid or unwanted data - data taken, for example, when the target was outside the edge of the field of view. In practice, screening entails applying various criteria to create good time intervals (GTIs) which include only the good data. These GTIs are then implemented when light curves and spectra are extracted.

There may be other, more interesting scientific screening criteria that might be applied as well. For example, do you only want to include data when an eclipsing source is in eclipse? Or when a black hole candidate has a high count rate? In those cases, you need to create a more finely nuanced set of screening criteria.

As a reminder, you only need to "prepare" your observation data once with 'pcaprepobsid'. However, you might create many different good time filters based on different filtering strategies, and extract more than one set of products from the same prepared observation data.

Screening Basics

Most users will use at least standard set of screening criteria to keep only good data. The criteria are specified as screening expressions that are applied to the filter file using the task 'maketime'. The task 'maketime' is a mission-generic tool which allows one to construct a set of good time intervals (GTIs).

What are screening expressions? These are the key criteria that determine which part of your data are designated as good and which are designated as bad. For example, the expression,

  ELV > 4

indicates that target elevation above the earth limb (the filter file column named "ELV") must be greater than 4 degrees. Screening expressions are mathematical formulae, expressed as a text string, which describe conditions where your observation is good. Basically these are C-like or FORTRAN-like arithmetic expressions, which can use any combination of the columns of your input file. The allowed expressions are described in the fhelp for the task 'maketime'. Most of the rest of this document concern which expressions you should use for your data.

What are you screening? One usually applies the screening expressions to the filter file that you prepared when you ran 'xtefilt' or 'pcaprepobsid' in a previous step. If you ran 'pcaprepobsid', then the filter file will be stored in the results directory, listed as outdir/FP_nnnnnnnnnn-nnnnnnnnn.xfl, where nnnnnnnnnnnn-nnnnnnnnnnn is a hexadecimal time range. The name of this file is also stored as outdir/FP_xtefilt.lis.

One usually performs screening using the filter file, but this is not necessary. For example, one might be interested in screening based on source intensity, i.e. based on a light curve rather than the filter file. This example is described in more detail below.

Thus, the screening process involves applying an objective expression (usually a standard screening expression) against a given FITS file (usually the filter file). You need both the expression and the file to produce a valid screened result.

It is important to note that your input file that you apply the screening criteria against should cover the entire set of observations you are interested in. If you are interested in five RXTE observations, then you should use the merged filter file for all five observations, rather than each of them individually.

What is the output of the screening process? When you have completed running the task 'maketime' you will have a good time interval file, also known as a GTI file. This file is used by all of software used for extracting light curves and spectra. This file is a binary FITS table which has two columns: START and STOP. This file is described in more detail in the ABC Guide under the Data Files section. Together, these columns give time time intervals over when data is considered "good." The first row of the table gives the start and stop time of the first good time interval (in units of Mission Elapsed Time = MET), the second row gives the second interval and so on.

Screening Expression Basics

This section describes how to construct a screening expression, and what types of screening expressions you are recommended to use. This section is meant as an introduction to basic and intermediate users. Advanced users can of course perform any screening they wish based on objective criteria.

The screening expression is a text string, expressing as a formula the conditions for good data. For example, usually you are interested in only data where the target is above the earth's limb (i.e. not blocked by the earth), in which case you can use an expression like this:

  ELV > 4

which indicates that the elevation must be greater than 4 degrees. In this case, ELV is the name of the column in the standard RXTE filter file which records the elevation of the target above the earth's limb.

Usually you will have more than one criterium to be applied at the same time. For example, if you are interested in data where the target is above the earth's limb and simultaneously the observatory is pointing at the target, then the expression would look like this:

  (ELV > 4) .AND. (OFFSET < 0.1)

which combines the previous expression, and a new expression (OFFSET < 0.1) which uses the OFFSET column of the filter file to select only data when the observatory is pointed within 0.1 degree (=6 arcmin) from the target.

Generally, screening expressions are combined like this:

  (expression1) .AND. (expression2) .AND. (expression3)

The .AND. between the sub-expressions indicates that each subexpression applies simultaneously with the others. The parentheses around each sub-expression are simply good practice, to clarify the grouping of each sub-expression.

Creating a GTI with 'maketime'

The ABC guide page about screening describes in more detail the quantities that are available in the filter file for screening. That document also describes how to make a plot of quantities in the filter file, and the basics of making a GTI file with the task 'maketime'. These are also summarized below.

In general, GTI files are created with the ftool maketime which applies Boolean and/or arithmetic selection criteria to the columns in the filter file and outputs a file containing the time ranges satisfying the criteria, described in more detail below.

The task 'maketime' is a mission-generic tool, and supports more than one type of input file. Because of this, there are some apparently arcane options that we must use to support RXTE-formatted data.

Consider the example where we want only data where the target is more than 4 degrees above the earth limb. As mentioned above, the expression is thus (ELV > 4). You can run 'maketime' interactively on the command line and it will prompt you for inputs:

csh> maketime
> Name of FITS file and [ext#][] 93067-01-42-01-zzz/FP_1adf146f-1adf1819.xfl
> Name of output FITS file[] elv4.gti
> Selection Expression[] (ELV > 4)
> Column containing HK parameter names[] NAME
> Column containing HK parameter values[] VALUE
> Column containing HK parameter times[] TIME
> Flag, yes if HK format is compact[] no

In this example, you were prompted for the filter file (93067-01-42-01-zzz/FP_1adf146f-1adf1819.xfl) and the output GTI file (elv4.gti). The NAME, VALUE and TIME and compact=no parameters are historical but needed for RXTE-style filter files. (Those keywords would be relevant for ASCA-style "compact" housekeeping files but not RXTE's.)

Like all HEASoft tasks, you can also run 'maketime' in non-interactive mode on the command line, which is useful for scripting. To achieve the same results as the previous interactive invocation, use this command:

maketime infile=93067-01-42-01-zzz/FP_1adf146f-1adf1819.xfl \
     outfile=elv4.gti expr="(ELV > 4)" \
     value=VALUE time=TIME prefr=0.5 postfr=0.5 compact=NO clobber=YES

The extra parameters 'prefr' and 'postfr' are recommended. They indicate that good time intervals begin halfway between time samples in the input file.

Recommended Screening Criteria

The following sections describe screening expressions you can use with your data. We provide both a "basic" and a "conservative" set of criteria which depend to some extend on what kind of data you have.

The "basic" criteria are weighted towards accepting good data and removing most of the bad data. Occasionally some "semi-bad" data will leak through this set of criteria. We advise this set of criteria when you are analyzing bright sources where you are often less concerned if a very small amount of bad data survive.

The "conservative" criteria are weighted towards removing all bad data, at the expense of sometimes removing good data. This is the most conservative in the sense that bad data will rarely leak through, but at the same time, you might reject data that you might consider good as well. We recommend this set of criteria when you are analyzing faint sources where you are concerned about sensitive flux determinations.

Recommended Basic and Conservative Screening Criteria

Elevation "(ELV > 4)"

The elevation screening expression ensures that the target is above the Earth's limb or horizon. It is possible for the PCA detectors to be on and registering background counts even when the target is below the limb, so this expression is important. In addition, this criterium removes incidences of bright earth (solar reflection from earth's atmosphere) which may increase the background level even when the target is formally not visible. For most cases, "(ELV > 4)" is sufficient but "(ELV > 10)" will be absolutely sure that the target is visible and bright earth screened out.
Conservative: "(ELV > 10)".

Pointing Offset "(OFFSET < 0.1)"

This offset screening expression ensures that the PCA is pointed at the target to within 0.1 deg (=6 arcmin). It is possible for the RXTE PCA detectors to be on and registering background counts even when the observatory is not pointing at the target, so this expression is also important. For most targets the basic criterium is sufficient, but a more conservative value for the offset will ensure that the target is within 1 arcmin of the pointing direction and thus that the response is >99% of maximum.
Conservative: "(OFFSET < 0.02)"

Detectors Enabled "(NUM_PCU_ON > 0 .AND. NUM_PCU_ON < 6)"

This screening expression ensures that at least one PCU detector is enabled. Since detectors can be off even if the observatory is pointed at the target and the target is visible, this expression is also important. The "NUM_PCU_ON < 6" portion ensures that non-sensical values are not included. If you wish to include only times when PCU2 is enabled, then use the conservative expression.
Conservative: "(PCU2_ON)" (a boolean flag)

South Atlantic Anomaly "(TIME_SINCE_SAA .GT. 30.0 .OR. TIME_SINCE_SAA .LT. 0.0)" (early mission)

This applies to data 1996-04-15 and before only! The background models during Epcohs 1 and 2 (between launch and 1996-04-15) did not accurately subtract background due to induced radioactivity after passing through the South Atlantic Anomaly (SAA). This screening expression removes data within 30 minutes of the passing through the SAA. For data taken after 1996-04-15, i.e. the large majority of the RXTE mission archive, this expression is not required.

Precipitating electrons "(ELECTRON2 < 0.1)" (faint targets)

This conservative screening expression reduces the chances of precipitating electrons contaminating the background of your observation. Typically these flares are short term (few minutes). Electrons penetrating the propane layer are not very well modeled by the standard PCA background models, so it's best to exclude such electron flares from faint source observations if you wish to perform conservative screening.

High Voltage Breakdowns "(TIME_SINCE_BRK .LT. -150 .OR. TIME_SINCE_BRK .GT. 600)" (if you do not use pcadeadcalc2)

During episodes of high voltage breakdowns the affected PCU becomes unstable in terms of gain and possible count rate outbursts. By default, pcaprepobsid and pcadeadcalc2 automatically screen out these episodes. If you use these high level tasks, then you do not need to do the above filtering. If you do not use pcaprepobsid or pcadeadcalc2, then you should to manually screen them with the above expression. The PCA team provides a PCU breakdown history file for this purpose in CALDB. For more information, see the PCA breakdown recipe.

Offset-Pointed Targets "(ANGSEP(POINT_RA,POINT_DEC,(offpoint_ra),(offpoint_dec)) .LT. 0.1)"

In some cases targets are observed with an offset pointing direction. Sometimes this is because the true position of the target is not known before the observation begins. In other cases, an offset is used to prevent bright targets from harming the PCA detectors. For example, offset pointings were commonly used for the target Sco X-1. In such cases, the "OFFSET .LT. 0.1" filtering expression will not be sufficient, because the pointing will always be offset by a large amount. To work around this, we use the ANGSEP() function to compute the offset between the desired offset pointing direction and the actual pointing direction. The values of the desired offset pointing direction, (offpoint_ra, offpoint_dec) can be found from the planning observation, or by examining the filter file by hand and determining the "median" pointing direction.

Example Screening Expressions

The above section gives the basic "building blocks" for filtering expressions. Here we summarize the complete screening expressions for two common examples.

• Example: You have a bright target and want to do the "basic" filtering. Your observation is in the year 2002. Assuming you are using the pcapreobsid/pcadeadcalc2 tasks, your filtering expression would be:

  (ELV > 4) .AND. (OFFSET < 0.1) .AND. (NUM_PCU_ON > 0 .AND. NUM_PCU_ON < 6)
  

• Example: You have a faint target and want to do "conservative" filtering. Your observation is in the year 2003, and you are using the pcaprepobsid/pcadeadcalc2 tasks. Your filtering expression would be:

  (ELV > 10) .AND. (OFFSET < 0.02) .AND. (NUM_PCU_ON > 0 .AND. NUM_PCU_ON < 6) .AND. (ELECTRON2 < 0.1)
  

If your observation is before 1996-04-15, then you should add the TIME_SINCE_SAA screening expression. If you are not using pcaprepobsid/pcadeadcalc2, then you should add the TIME_SINCE_BRK screening expression to remove data during PCA breakdown events.

Other Screening

The sections above give you basic screening criteria to remove "bad" PCA data from your observation, but what if you want to control how much "good" data are included? You might want to include data during a particular orbital phase, or a certain count rate, or hardness ratio. This section gives some examples of how one might achieve those goals.

Simple Time Based Constraint

Let's assume that you are interested in data only from a certain time. For example, you may wish to analyze a particular burst of emission at a particular time. Or, you may desire to synchronize your time intervals with another observatory. A simple way to do this is to make a simple time-based screening expression. This is easy, if you convert your times into RXTE Mission Elapsed Time (MET) time system, which is time measured in seconds since 1994.0.

Consider an example, where you are interested in data between the following two times:

• Start of time interval to include: 2003-01-07T06:25:00 (MET 284538300 using xTime)

• End of time interval to include: 2003-01-07T06:32:00 (MET 284538720 using xTime)

Given a calendar time in UTC, or MJD, you can use the web tool xTime to make the conversion to RXTE MET.

Given the above time range, the filtering expression to select your time range would be:

  (TIME >= 284538300 .AND. TIME <= 284538720)

where the times are expressed in MET.

If you wish to include multiple time ranges in one filtering expression, then combine the above expressions with ".OR.". For example here are two time ranges:

  ((TIME >= 284538300 .AND. TIME <= 284538720) .OR. (TIME >= 284638300 .AND. TIME <= 284638720))

However, beware that this expression will make a single GTI file with multiple time intervals. If you extract a spectrum with such a GTI you will obtain one spectrum containing the summation of both time intervals. If you wish to make two different spectrum files covering two different time intervals, then make two different GTI files with the desired time ranges.

Excluding a Specific Time Range

In contrast to the previous section this section covers the case where you desire to exclude a particular segment in time. This may be because you desire to manually exclude some bad data that survived the standard screening expressions, or because the target exhibited some anomalous X-ray behavior.

Consider the same example as the previous section, only now you desire to exclude data during the following two times:

• Start of time interval to exclude: 2003-01-07T06:25:00 (MET 284538300 using xTime)

• End of time interval to exclude: 2003-01-07T06:32:00 (MET 284538720 using xTime)

Given a calendar time in UTC, or MJD, you can use the web tool xTime to make the conversion to RXTE MET.

Given the above time range, the filtering expression to exclude your time range would be:

  .NOT. (TIME >= 284538300 .AND. TIME <= 284538720)

where the times are expressed in MET. This is essentially the same expression as above, except with the ".NOT." operator, which indicates that the given time range is "not" acceptable.

If you wish to exclude multiple time ranges in one filtering expression, then combine the above expressions with ".AND.". For example here are two time ranges:

  (.NOT. (TIME >= 284538300 .AND. TIME <= 284538720) .AND. .NOT. (TIME >= 284638300 .AND. TIME <= 284638720))

Advanced: Orbital Phase Constraint

When observing an X-ray binary, the X-ray emission and absorption properties may vary during the orbital period. For example, if there is an eclipse, then one might be scientifically interested in the residual emission during the eclipse phase of the orbit.

Consider an X-ray binary with the following known properties:

• Epoch of Phase zero: MJD 52646.0768 (MET 284515204 using xTime)

• Orbital period: 9.76 hour (35136 sec)

And for this example, let us say we are interested in orbital phases 0.2 through 0.8.

This simplified example uses a model with a constant orbital period, measured from a fixed epoch which corresponds to orbital phase of zero. For such a model, it is possible to compute orbital phase from time using the following formula:
phase = (time - epoch)/period
where the parameters are given above. For more complicated orbital models, computing the phase may be more difficult, but the model can always be linearly approximated around the time of your observation.

The best way to achieve this is to compute a new column of the filter file called ORB_CYCLE, which is derived from the time and known orbital properties, and using the above formula. Let's assume that we start with an original unmodified filter file called FP_orig.xfl and want to add an orbital phase column. The calculator task 'ftcalc' can make such a calculation easily.

  ftcalc FP_orig.xfl     FP_orbcycle.xfl ORB_CYCLE "(TIME - 284515204.0)/35136.0"
  ftcalc FP_orbcycle.xfl FP_orbphase.xfl ORB_PHASE "(ORB_CYCLE % 1.0)"

First we computed the orbital cycle number, which is a real number which increases with time. Second, we computed the orbital phase by using the calculator operator "%" which computes the modulus (remainder) after dividing by 1.0. In this example, the revised filter file will be named FP_orbphase.xfl and have a new column named ORB_PHASE which is calculated using the given expression. The values come from the above list.

Now you can use a 'maketime' expression to filter on the desired orbital phase (between 0.2 and 0.8). Here is an example:

  maketime infile=FP_orbphase.xfl outfile=ph_2_8.gti expr="ORB_PHASE > 0.2 .AND. ORB_PHASE < 0.8" \
     value=VALUE time=TIME prefr=0.5 postfr=0.5 compact=NO clobber=YES

The resulting output GTI is ph_2_8.gti and represents any times when the ORB_PHASE column is between 0.2 and 0.8.

Selecting Data by Intensity Level

You may wish to select certain data of interest by other properties unrelated to the filter file. For example, it's common to select a source based on its emission state or total flux. A simple way to do this is by selecting based on a count rate level.

Consider an example where we are interested a black hole candidate, and separating high intensity portions of the observation for special analysis. Assume for the sake of simplicity that we have determined that when the count rate exceeds 2500 ct/s/PCU, the target is in the desired high intensity state.

First, we need to follow the instructions to make a light curve from all of the data using basic screening. Following the above instructions for basic screening, will produce a GTI file, which can be used to extract a light curve. Let say that the resulting light curve based on RXTE data is called basic.lc.

Given the existence of your light curve, you can create a good time interval using this light curve as a basis:

maketime infile=basic.lc outfile=highrate-2500.gti expr="(RATE .GT. 2500)" \
     value=VALUE time=TIME prefr=0.5 postfr=0.5 clobber=YES

The output file highrate-2500.gti is suitable to use as input to another extraction run.

Combining more than one GTI

You may have more than one good time interval file. For example, one file may represent the basic filtering criteria, whereas another file may represent an a cut on the count rate intensity. We use the task 'mgtime' ("merge time") to merge one or more GTI files into a single file.

The most common way to combine time intervals is to use the intersection or AND operator. This is the most conservative operator because it represents only those time intervals that meet all of the criteria simultaneously. If two GTI files are created with "(expression1)" and "(expression2)" then the good time intersection of these two files is equivalent to using "(expression1) .AND. (expression2)" as your original screening expression.

Here is an example of merging two files using the task 'mgtime' interactively on the command line:

csh> mgtime
> Names of GTI files and [ext#][] gti1.gti,gti2.gti
> Name of output GTI file[] total.gti
> Merge mode: OR or AND[] AND

The two input GTI file names are gti1.gti and gti2.gti; and the output GTI file name is total.gti.

To perform the same interaction non-interactively, you can use the following command:

  mgtime ingtis="gti1.gti,gti2.gti" outgti="total.gti" merge=AND

Another more rare case is where you are interested in forming the union of multiple time intervals (the OR operator). This situation usually arises when you have data from two disjoint observations, A and B, and would like to merge them together. Mathematically speaking, you wish to accept times where either A or B are true, hence the OR operator.

Here is example of using 'mgtime' to form the union of the files gtiA.gti and gtiB.gti using the non-interactive style:

  mgtime ingtis="gtiA.gti,gtiB.gti" outgti="gtiAB.gti" merge=OR

For more information about merging good time interval files, please see the help file for the task 'mgtime' ('fhelp mgtime').

The Next Steps

Once you have prepared your observation data and created a good time interval file, you are ready to start extracting light curves and/or spectra. For more information, please see the detail page on extraction.