RXTE Helpdesk/FAQ RXTE What's New HEASARC Site Map


RXTE
GOF
RXTE Getting Started Guide RXTE
FAQ

  1. Introduction
  2. Getting RXTE Data
  3. The RXTE Directory Structure
  4. What you Need to Know about RXTE Data Files
  5. How to Use XDF to Browse your Files
  6. How to Install all the Necessary Software

1. Introduction

This Guide is intended to do two things. The first is to show you how to get RXTE data. The second is to explain the essential properties of the files and directories in an RXTE dataset. In particular:

  • Getting RXTE data. Simple instructions for retrieving your public or proprietary RXTE data.

  • The RXTE directory structure. RXTE data come from several instruments and spacecraft Subsystems in a multitude of modes, while a given proposal may include data collected at different times from different targets. To reduce this complexity, RXTE data files are arranged in a hierarchical set of directories.

  • What you need to know about RXTE data files. Intimate familiarity with the contents and formats of RXTE data files is not necessary for most purposes. However, some aspects of the files are very useful to know.

  • How to use XDF to browse your files. Finding your way through the hierarchical directory structure to identify the data you want to reduce is made easy using XDF (XTE Data Finder), a graphical tool described here.

Of course, the first step in getting started is to install all the necessary software. This is covered in the final section.

This Getting Started Guide does not, however, explain how to reduce RXTE data - that's covered by the materials on the Data Reduction and Analysis page. The analysis of spectra and light curves are discussed in the xspec and xronos user guides, respectively.


2. Getting RXTE Data

Both proprietary data (for PIs) and public data can be retrieved via the Internet:
To get public data from the RXTE Archive, please see our recipe, The RXTE Archive.
To get proprietary data from your PI observations, please see the recipe Retrieving Production Data from the RXTE-GOF Online Area.


3. The RXTE Directory Structure

For the sake of simplicity and ease of use, RXTE data files are arranged in a hierarchical set of directories. The top-level directory is simply FD for FITS Database; next depends on whether the data are AO1 or later. For AO1, there is simply an AO1 directory, and then a proposal level directory. For later tapes, there is a set of directories, one of which is named after the AO and contains the proposal directory while the others contain calibration, clock, orbit, and other files. Under the proposal level directory are the individual observations, while the final level contains directories for each of the Subsystems (PCA, ACS etc.). These directory levels and their nomenclature are described in more detail below.

An important feature of the directory structure is the existence at each level of index files which refer to the contents of the directories at the next level down. These index files enable the XDF data browser to find out the contents of the entire directory tree without having to examine every file, sparing the user from this task. In fact, thanks to XDF and the index files, it's possible to browse and reduce RXTE data without directly encountering the directory hierarchy.


3.1 Top Level

The FD directory contains the directories:

  • AON (where N is the Announcement of Opportunity cycle for this observation)
  • Cal
  • Clock
  • OrbitEphem
The AON directory contains the proposal level directory with all the data under it. Cal, Clock, and OrbitEphem contain the obvious corresponding files. (These three will not be present for original processing of AO1 data; the files were in the ObsId subsystems instead. See below.) The Cal directory contains all XTE calibration files, but as they have since been superceded, we recommend that you install the full CALDB.

3.2 Proposal Level

The proposal number, prefixed with P, is used for the name of the top of your data directory. It is assigned by the GOF when the proposals received and stays the same throughout the mission.


3.3 Observation IDs

Reflecting the fact that a single proposal may contain several targets and several pointings, the second directory level is devoted to single observations, where "observation" refers to a temporally contiguous collection of data from a single pointing. The format for the second-level directory names (also known as ObsIds) is as follows:


    NNNNN-TT-VV-SSX
where:
  1. NNNNN is the five-digit proposal number assigned by the GOF and is identical to the name of the parent directory (see above).

  2. TT is the two-digit target number assigned by the GOF. Note that for the case of only one target, the target number may be zero.

  3. VV is the two-digit viewing number, assigned by GOF, which tracks the number of scheduled looks at the target. In particular the viewing number corresponds to:

    • different (requested) observations of the same target (e.g., at different epochs for monitoring),

    • different instrument configurations during the same pointing,

  4. SS is the two-digit sequence number used for identifying different pointings that make up the same viewing:

    • for different scans for scan-mapping of extended sources,

    • if the SOF decided, for operational reasons, to split that viewing into more than one chunk, or

    • if it was split "by accident", by a TOO, for instance.

  5. X, 15th character, when present, indicates:

    
        A       Slew before observation
        Z       Slew after observation
        S       Scan observation
        R       Raster grid observation
        G,C,D   ObsIDs that may contain data gaps
        0-9     Segments of a long observation (i.e., > 8 hours)
        b-r     (reserved for) Real-time configuration changes
    

    When not present, it indicates a regular pointed observation (< 8 hours) or the last segment of a long observation.


3.4 Spacecraft Subsystems

Each ObsID directory contains a set of 15 subdirectories, each containing data files derived from a single spacecraft Subsystem. The typical user will not need to know about most of them, but a complete listing is as follows:

ace - Attitude Control Electronics & star trackers
acs - Attitude Control System
cal - References to files in the Calibration Database*
clock - Time delta correction data from Mission Operations Center*
eds - Experiment Data System housekeeping
fds - Flight Data System
gsace - Gimbals and Solar Array Control Electronics
hexte - HEXTE science and housekeeping data
ifog - Interferometric Fibre Optics Gyroscope
ipsdu - Instrument Power Switching and Distribution Unit
orbit - Orbit ephemeris from the Flight Dynamics Facility*
pca - PCA science and housekeeping data
pse - Power System Electronics
spsdu - Spacecraft Power Switching and Distribution Unit
stdprod - Standard Products - cleaned light curves, spectra etc.

* If the top level Cal, Clock, and OrbitEphem directories exist, then these subsystems simply contain links to those files. The links exist so you can find the appropriate files using the index files via XDF. If those directories do not exist, then the files themselves should reside in each subsytem, so there may be many duplicate files in different ObsIds.

Though they represent the lowest rung in the directory hierarchy, the Subsystem directories do not necessarily contain files of one type. In most cases, a further division is made based on Application, the term used for a distinct source of telemetry.

Note that the ASM is not included.


4. What you Need to Know about RXTE Data Files

4.1 Applications

Each Subsystem can be thought of as a set of several distinct sources of telemetry (there are six PCA Event Analyzers, for example). These telemetry sources are known as Applications and are designated by AppIds (Application IDs). In all, there are 255 possible AppIds, and the telemetry packets they produce end up in corresponding RXTE data files after conversion to FITS on the ground.


4.2 Configurations

The content of the telemetry packets from the three scientific Subsystems, ASM, HEXTE and PCA, can be arranged in different ways to maximize the science return within the overall telemetry budget. This amounts to choosing an observing mode and setting the adjustable parameters which define the mode. The combination of mode and mode parameters is known as the configuration. This is an important concept, for only data from the same AppId with the same configuration have a truly homogeneous format and can be reduced together in the same way.

RXTE has hundreds of possible configurations - and the flexibility to add new ones - but the data you get on your tape or Internet download will have only those configurations chosen for that particular observation.


4.3 Design of RXTE Data Files

The structure of the RXTE data files - FITS data tables, to be more exact - follows these design principles:

  • Homogeneous contents: The contents of individual data file come from the same Application.

  • Time span: A new data file is started when:

    • a new observation begins,

    • the configuration changes, or

    • the Application is rebooted (note that the Event Analyzers are rebooted once per orbit).

  • Rows: One row per packet or logical group of packets in time order.

  • Columns: Data from different data sources (the Pulse Height Analyzer, for example) will be separated into different columns, some of which may contain arrays rather than single values.


4.4 XTE Filter File:

For each ObsId, the stdprod directory should contain an XTE filter file, named FP_xxxxxxx-yyyyyyy.xfl (where xxxxxxx and yyyyyyy are the start and stop time in hexidecimal mission elapsed seconds.) This filter file incorporates much of the housekeeping data from other subsystems and is intended for creating good time intervals based on those data. Checking, and remaking if necessary, this file is one of the first steps to data analysis. (See recipe.) Make sure it includes everything you will need (by plotting the columns ELV, OFFSET, PCUn_ON, BKGD_THETA, BKGD_PHI, NUM_PCU_ON, TIME_SINCE_SAA, and ELECTRONn at minimum) before you delete any housekeeping data.


4.5 Which Files Can I Delete to Save Disk Space?

For completeness and to avoid having to redistribute data, your RXTE data tape contains all the satellite telemetry, only parts of which are essential for data analysis. Here we list again the directories corresponding to the satellite subsystems, but this time with recommendations about which to keep on disk.

  • Directories or files which you should keep:

    • pca - keep everything
    • hexte - keep everything
    • OrbitEphem (top level; or orbit subsystem) - keep the ephemerides in case you need them
    • stdprod - keep the .xfl file (see note above)
    • Cal (top level) or
    • cal (subsystem) - keep one copy from one of your ObsIds and delete the identical copies from the other ObsIds (unless you have installed either the full or surrogat XTE CALDB; then these directories are extraneous.)

  • Directories you can delete entirely:

    • ace
    • acs *
    • clock
    • eds
    • fds
    • gsace
    • ifog
    • ipsdu
    • pse
    • spsdu
* You may delete the acs directory only after you have a good filter file (see section 4.4) and you won't need the satellite attitude information at a time resolution smaller than that contained in the filter file.

Please note that for most observations the PCA contributes the most telemetry: deleting the non-science subsystem directories doesn't always save a lot of space. If you still can't fit all your data onto your disk, please consider the following:

  • Buy more disk space: This isn't a facetious comment. RXTE data files are large because the scientific instruments provide unprecedented temporal resolution and telemetry options. Since disks are relatively cheap and since future missions are likely to produce files just as large, buying more disk space is probably the best solution.

  • Delete event-mode configurations: Files derived from event modes, such as PCA Good Xenon or HEXTE E_8us_256_DX1F provide the highest time resolution and consequently the largest files. If your source is weak, it's likely that you won't be able to exploit this resolution for lack of signal-to-noise. Moreover, in the case of the PCA, the Standard-2 data provide the same anode and detector ID as Good Xenon, as well as an adequate number of PHA channels. The same is true for HEXTE Archive mode.


5. How to Use XDF to Browse your Files

XDF (XTE Data Finder) is a tool with a graphical user interface (GUI) to make the task of browsing the hierarchical directory structure much easier. Its end-product is a list of filenames corresponding to the data you want to analyze, as chosen by target name, time of observation, instrument and configuration.

To start XDF, type xdf at your system prompt. A window will appear on the screen divided in boxes with accompanying buttons. In broad terms, you start at the top of the window and work downwards, gradually narrowing your data selection criteria by filling the boxes until you produce the file list which appears in the box at the bottom. In more detail:

  1. The first box to fill in is the Path to the directory containing the FMI (FITS Master Index) file - usually the proposal level directory. It is not necessary to type a carriage return when the path name is complete.

  2. Next, use the mouse to activate the Make ObsList button on the top row. This fills the Observations box with one-line summaries of the ObsIds in the top level directory. For each ObsId, the directory name, target name, and time range are listed. At this point you can choose a particular target or time range, though for most GOs this option is not needed.

  3. You select ObsIds themselves by clicking on them with the mouse or by pushing the All button.

  4. The next step is to choose Subsystems from the Subsystems box by clicking on the names of the ones you're interested in.

  5. To see the AppIds/ Configurations of your chosen Subsystem, push the Make AppIdConfigList button on the top row. Select the Appid/Configurations you're interested in from the AppIds/Configurations window.

  6. Finally, when you've completed your choice of AppIds, push the Make FileList button on the top row. The list of corresponding files will appear in the box at the bottom of the screen: if you want to save it, push the Save FileList button on the top row to write out the list to an ASCII file called whatever you put into the File Name window. If no name is specified, it will be called "fits_files.xdf".

Using the @filename convention, the .xdf file may be input to the data reduction software to identify the raw input files.


6. How to Install all the Necessary Software

Software for RXTE data analysis is available in the HEASoft package, a unified release of the HEASARC's FTOOLS and Xanadu software. Installation instructions are included on the HEASoft Web page.


If you have a question about RXTE, please send email to one of our help desks.

This page is maintained by the RXTE GOF and was last modified on Thursday, 01-Nov-2012 10:22:23 EDT.