Suzaku Project Data Management Plan (PDMP)

Suzaku Project
Data Management Plan

(PDMP)
Suzaku Guest Observer Facility

NASA/GSFC, Greenbelt, MD 20771, USA,
and
Institute of Space and Astronautical Science (ISAS/JAXA)
Yoshinodai, Sagamihara, Kanagawa, 229 Japan
Version 2.0
September 27, 2007
Version History
v0.0 (September 9, 2005) — Revision from the PDMP of the Astro-E(1) project. Remove
explanations about the instruments.
v0.1 (December 3, 2005) — Revision with comments from Ken Ebisawa. Update the software
description. Remove documents about the XRS.
v0.2 (January 17, 2006) — Additional post-launch information included.
v1.0 (April 17, 2007) — First official version, corresponding to Version 1.X processing.
v1.1 (April 20, 2007) — Including description in the Suzaku memo. Adding comments from
Yoshitaka Ishisaki.
v2.0 (September 27, 2007) — The version corresponding to Version 2.X processing. Adding
comments from Ken Ebisawa, Yoshitomo Maeda, Yukikatsu Terada, Tadayuki Takahashi,
Hironori Matsumoto, Masanobu Ozaki.
Contents
1 Introduction 4
1.1 Scope of this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Mission Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 The Suzaku Guest Observer Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 Observations Types 7
2.1 Observations Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.1 In-Orbit Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.2 Observatory Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.3 Science Working Group Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.4 GO Observations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.5 Calibration Observations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.6 Target of Opportunity Observations . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1.7 HXD WAM Observations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Proprietary Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Satellite and Instrument Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.1 Data Retrieval and Raw Data Archives . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.2 Data Processing at ISAS and GSFC . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.3 Data Delivery to Suzaku Observers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.4 Suzaku Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Software Principles 12
3.1 General Software Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2 Suzaku Specific Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.3 Suzaku Software Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3.1 Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.3.2 Coding Rules and Compiler Requirements . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3.3 Systems Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3.4 Coordination and Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.3.5 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.4 Suzaku FTOOLS Global Development Scheme . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.5 Suzaku Ftools Release Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4 Suzaku Function Libraries 17

4.1 Suzaku Specific Tasks (aste tool) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1.1 Time Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1.2 Coordinate Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1.3 Energy Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1.4 HK Information Acquisition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.1.5 Other Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1
CONTENTS 2
4.2 Attitude and Orbit Related Tasks (atFunctions) . . . . . . . . . . . . . . . . . . . . . . . . 18

4.2.1 Attitude Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.2 Orbit Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.3 Attitude and Orbit Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 Ray-Tracing Function Library (xrrt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5 Planning and Simulation Software 20

5.1 Observation Planning Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.1.1 TAKO (Timeline Assembler, Keyword Oriented) . . . . . . . . . . . . . . . . . . . . 20
5.1.2 MAKI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2 Simulation Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.1 Counting Rate Simulation – PIMMS . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.2 Spectral Simulation – XSPEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.3 XRT Ray-Tracing Library – libxrrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.4 Suzaku XIS Event Simulator xissim . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6 Data Analysis and Processing Software 23

6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.2 Stage 0 – Satellite Specific Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.2.1 Orbit Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.2.2 Attitude Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.2.3 Raw Packet Telemetry Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.3 Stage 1 – Production of the First FITS Files . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.3.1 First Stage Software – mk1stfits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.3.2 Convention for naming First FITS Files . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.4 Stage 2 – Instrument Specific Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.4.1 Stage 2-1 – Preprocess the Supplementary Data . . . . . . . . . . . . . . . . . . . . . 27
6.4.2 Stage 2-2 – Refine the First FITS Event Files . . . . . . . . . . . . . . . . . . . . . . 27
6.4.3 Stage 2-3 – Apply the Calibration Data . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.4.4 Stage 2-4 – Classify Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.5 Stage 3 – Data Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.5.1 Stage 3-1 – Screen the Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.5.2 Stage 3-2 – Extract Scientific Products . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.5.3 Stage 3-3 – Generate Analysis Specific Data Sets . . . . . . . . . . . . . . . . . . . . 30
6.5.4 Stage 3-4 – Derive Scientific Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.6 Pipeline Processing System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
7 Calibration 35
7.1 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
7.2 Calibration Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.3 Calibration Database (CALDB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.3.1 Structure and Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.3.2 Time-Dependent Calibration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.3.3 Calibration File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.3.4 Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
7.4 Important Calibration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.4.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.4.2 XRT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.4.3 XIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.4.4 HXD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.5 Suzaku Calibration File Release Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
CONTENTS 3
8 Guest Observer Support 40

8.1 On-Line Service and Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.2 Proposal Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.3 Observation Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.4 Pipeline Processing and Data Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.5 Data Analysis Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.6 Community Oversight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9 Suzaku Database and Archives 42

9.1 Suzaku Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.1.1 Proposal Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.1.2 Observation Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.1.3 Processing Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
9.2 Suzaku Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
9.2.1 Policy and Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
9.2.2 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
9.2.3 Archival Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
A Acronyms 44
B FTOOLS developers guideline 46

B.1 Items to be Delivered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
B.2 Source Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
B.3 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
B.4 Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
B.5 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
C Flow Chart of the Pipeline Processing 49
D Definition of the Coordinate System used for Suzaku 53

D.1 Definition of the Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
D.2 Implementation to the FITS Event Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
D.2.1 Names of the Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
D.2.2 Type and Range of the Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Chapter 1
Introduction
Suzaku, formerly Astro-E2, is the fifth Japanese X-ray astronomy satellite built by the Institute of Space
and Astronautical Sciences of Japan Aerospace Exploration Agency (ISAS/JAXA). It was launched from
the Uchinoura Space Center (USC) on 2005 July 10. Suzaku is the second ISAS X-ray astronomy satellite
built in close collaboration with National Aeronautics and Space Administration’s Goddard Space Flight
Center (NASA/GSFC).
1.1 Scope of this Document

This document covers the following:
• An brief overview of the mission, the instruments on-board, and the Suzaku Guest Observer Facility
(GOF).
• An overview of the end-to-end flow of data, from the satellite to the user and the archive, and
the division of labor between ISAS/JAXA and NASA/GSFC, as well as that among groups within
NASA/GSFC.
• The Suzaku data and data products.
• The support given to guest observers (GOs)
This document is not the original source for:
• High level agreements between ISAS/JAXA and NASA/GSFC, such as the allocation of observing
time.
• Detailed technical information about the instruments, including design and calibration.
• Technical information about the telemetry.
In chapter 2, Suzaku operation and types of observations are briefly explained. Suzaku software design
principles and agreements are presented in chapter 3. Further details of software are described in chapters
4, 5, and 6. Important issues regarding the calibration are given in chapter 7. Tasks regarding the Guest
Observer support are shown in chapter 8, and Suzaku archives are explained in chapter 9.
In appendix A, acronyms used in this document are defined. Guidelines for FTOOLS developers are
described in appendix B. A flow chart of the pipe-line processing is displayed in appendix C. Coordinate
system of each detector is listed in appendix D.
4
Suzaku PDMP v2.0 (September 27, 2007) 5
1.2 Mission Overview

Suzaku was launched with three types of instruments on-board, covering a wide range of energies. The
X-Ray Spectrometer (XRS) is the first micro-calorimeter based X-ray instrument to be launched into orbit.
Although it prematurely lost all its cryogen shortly after launch and therefore stopped operation before it
could obtain astronomically useful data, the XRS had an excellent energy resolution (∆E ∼ 6–7 eV) over
its 0.3–12 keV bandpass.
The 4 units of X-ray Imaging Spectrometers (XISs) are CCD cameras, providing moderate spectral
resolution over 0.2–12 keV (∆E ∼ 130 eV at 6 keV). There are five X-Ray Telescopes (XRTs) on-board
Suzaku, one in front of the XRS and the other four in front of the XISs, providing high throughput and
modest spatial resolution. The field of view (FOV) of XRT + XIS is 19′ ×19′ with a spatial resolution of
about 2′ half-power diameter (HPD).
The Hard X-ray Detector (HXD) is a non-imaging, collimated instrument that covers the energy band
∼10–700 keV using two types of detectors, PIN (10–60 keV) and GSO (50–700 keV). The full width at
half maximum (FWHM) spectral resolution is 3 keV for the PIN detector and ∼ 10 % at 600 keV for the
GSO detector. The innovative design of the HXD results in low background and, hence, high sensitivity.
All instruments operate simultaneously and are co-aligned, so that a given target can be observed
over 0.2–700 keV at high sensitivity and with good spectral resolution. This makes Suzaku a powerful
observatory for a wide range of astronomical objects. In addition, the background detectors of the HXD
can be used to monitor a wide area of the sky.
1.3 The Suzaku Guest Observer Facility

The Suzaku Guest Observer Facility (GOF) is located at NASA’s GSFC within the Office of General
Investigator Programs (OGIP). Besides the Suzaku GOF, OGIP contains the High Energy Astrophysical
Science Archive Research Center (HEASARC) and GOFs for other major high energy missions. The
HEASARC is a data center responsible for archiving data from past high energy astrophysical missions and
constructing a user-friendly data analysis environment. Suzaku GOF carries out its tasks in collaboration
with HEASARC.
The GOF is responsible for the US Guest Observer support, including:
• Support of prospective GOs’ proposal preparation

• Support of US peer-reviews of GO proposals.
• Receiving, validating, processing, archiving and distributing the data, in collaboration with the
HEASARC.
• Providing documentations and on-online materials
• Providing expert help to GOs
Suzaku GOF WWW home page is located at

http://suzaku.gsfc.nasa.gov/.
1.4 Related Documents

Other important issues which cannot be covered in this document described elsewhere, including:
• The Suzaku Technical Description — Design of the entire satellite, instruments, and their specifica-
tion. This is available at
http://suzaku.gsfc.nasa.gov/docs/suzaku/prop tools/suzaku td/
• Suzaku FITS File Formats — FITS formats of the Suzaku HK and event files, calibration files and
other important files (e.g., attitude files and orbit files)
• Suzaku Interface Control Document (ICD) — it defines the interface between Suzaku processing
processing systems and the HEASARC, and contains the directory structure and file name convention
for files that are delivered.
• Suzaku Calibration — How Suzaku instruments and data are calibrated is explained. See 7.1 for
details.
• Suzaku data analysis guide (also known as the ABC Guide) — Provides an overview of Suzaku data
analysis. This document will be available at
http://suzaku.gsfc.nasa.gov/docs/suzaku/analysis/suzaku abc/
Chapter 2
Observations Types
In this chapter, we provide a brief description of various types of Suzaku observations, because different
types of observations are treated differently in data distribution and archiving.
Figure 2.1 shows a flowchart illustrating various processes in the Suzaku observation program from
GOs’ proposal submission to the data reception. Important issues for individual processes outlined in this
chapter are explained in more details in later chapters.
2.1 Observations Types

2.1.1 In-Orbit Checkout
The period between the launch on July 10, 2005 and the end of August, 2005 is considered the in-orbit
checkout (IOC) phase. The first part of this phase was devoted to engineering activities, and no celestial
X-ray sources were observed. After the XIS first light on August 12 and the HXD first light on August
15, observations of celestial X-ray sources were carried out. Telemetry data after August 12 are processed
normally, although care must be taken as instrument parameters are not necessarily the same as for later
observations.
2.1.2 Observatory Time

Throughout the Suzaku mission life, approximately ∼12 % of the time will be reserved as the Observatory
Time. It will be used, for example, for instrumental calibration, maintenance of the satellite, or to com-
pensate for unexpected observational/operational failure such as cancellation of the ground contacts due
to bad weather. Target of opportunity (TOO) observations (section 2.1.6) may be also carried out using
the Observatory Time.
2.1.3 Science Working Group Time

Suzaku Science Working Group (SWG) is the collective name given to the instrument teams, mission
operations team, software and processing team, as well as Science Advisers who were selected to provide
guidance to the Suzaku team.
During the period between September 2005 and March 2006, the scientific (non-Observatory Time)
observations were generally selected by, and conducted by the SWG. This period is often referred to as
the SWG phase of the mission. No new SWG observations were included into the observing program after
April 2007, although a few SWG observations were carried out later, usually because of a problem with
the original observations. All SWG observations were completed by October 2006.
7
2.1.4 GO Observations
Suzaku entered the guest observer (GO) phase of the mission in April 2006. During this period, all non-
Observatory Time observations are selected from the world-wide astronomy community, with the exception
of the delayed SWG observations (see above). Some GO observations were carried out in February and
March 2006, before the nominal start of the GO period.
Targets are selected through a competitive process from observing proposals submitted by guest ob-
servers (GOs). Proposals by principal investigators (PIs) affiliated with a US institution are submitted to,
and selected by, NASA, through the annual NASA Research Announcement (NRA) process.
PIs affiliated with an institution in an ESA member country submit their proposals through ESA, who
conduct their own proposal review. Proposals submitted to ISAS/JAXA (principally by Japanese PIs,
although PIs from non-US, non-ESA country may also apply through ISAS/JAXA) are judged by ISAS.
The ESA list is folded into the Japanese list.
The final accepted target list is determined at the Japan-US merging meeting based on the Japanese
(including ESA) and US target lists. In case there are identical targets on the Japanese and US target lists,
the same target may be assigned to a Japanese PI and a US PI. Such targets are referred to as “merged.”
The GOF serves as the principal point of contact for US PIs, including co-PIs of merged targets. This
includes observation planning, notification of availability of processed data, and support in analyzing the
processed data (chapter 8).
2.1.5 Calibration Observations

Suzaku team will regularly carry out calibration observations to monitor the performance of the instru-
ments. Calibration observations are carried out using the Observatory Time.
2.1.6 Target of Opportunity Observations

Targets of Opportunity (TOOs) are observations of objects or states of objects that cannot be predicted.
X-ray novae, supernovae, strong flares of known targets, and after-glows of Gamma-ray bursts (GRBs) are
examples of TOO targets.
TOO observations may enter the Suzaku observing program in one of two possible ways. Pre-approved
TOOs are part of the GO observations, and are limited to unpredictable phenomena on specific, known
objects. In addition, genuinely unpredictable objects or events can be observed as part of the Observatory
Time.
2.1.7 HXD WAM Observations

The anti-coincidence detectors of the HXD can be used to detect GRBs and to monitor the flux levels of
bright hard X-ray/γ-ray sources. This aspect of the HXD is known as the Wide-band All-sky Monitor
(WAM). Even during the GO phase, the WAM data do not belong exclusively to the PI.
2.2 Proprietary Period

The SWG data are proprietary to the SWG until May 27, 2007, or 1 year after the date of observation,
whichever is later. In general, GO observation has a proprietary period of 1 year after the delivery of the
processed data. The project may extend the proprietary period of GO data in cases where a lack of analysis
software or calibration data seriously impacted the usefulness of the data. In such cases, the proprietary
period will extend 1 year after the availability of the software/calibration data, as judged by the project.
Calibration observations and TOO observations taken using the Observatory Time during the GO phase
have no proprietary time.
Proprietary data are available for download in encrypted form. The decryption keys are supplied to the
PIs, who may share them with their co-investigators. After the proprietary period is over, the decrypted
data are placed in the Suzaku archives (section 2.4.4; chapter 9), and open to all interested researchers.
2.3 Satellite and Instrument Monitoring

Duty scientists will monitor the health and safety of the satellite and the instruments, both at the downlink
station at the Uchinoura Space Center (USC) and at ISAS. They may not carry out scientific analysis of
the data. Any scientific insights incidentally gained by the duty scientists are considered confidential.
Certain aspects of the data are considered non-proprietary. In addition to the HXD/WAM data, they
include any data during which the instruments are pointed at the Earth, and XIS data from the area of the
CCD chips dominated by the on-board calibration source. Such data can be placed in the trend archive in
unencrypted form, even during the proprietary period for that observation.
In addition, the instrumental teams may access proprietary data for the purpose of monitoring the
performance of the instruments. They must refrain from performing any scientific analysis of the data,
and keep any knowledge incidentally gained while performing their duties confidential.
2.4 Data Flow

2.4.1 Data Retrieval and Raw Data Archives
The data are retrieved from the satellite only at USC. Suzaku has the data recorder with the 6 Gbits data
capacity and can downlink the data to USC by up to ∼10 Gbits daily in 5 contact passes. Raw data are
sent from USC to ISAS through a dedicated network, and saved in the raw database named SIRIUS. The
SIRIUS database at ISAS stores the raw telemetry data of all the current and past ISAS missions.
2.4.2 Data Processing at ISAS and GSFC

The Suzaku data processing means conversion from the raw telemetry data to the high-level calibrated
data deliverable to the Suzaku Observers. Details of the data processing are explained at section 6.1, and
only an outline is given here (figure 2.1).
At ISAS, telemetry files in the SIRIUS database are wrapped into portable Raw Packet Telemetry
(RPT) FITS files, with a minimum set of FITS keywords. Routinely, ISAS will process RPT files to
produce First FITS Files, which conform to high level FITS standards.
Attitude of the satellite and the clock correction is calculated at ISAS, and the satellite orbit is deter-
mined1 . The First FITS Files, attitude files, orbit files and timing correction files constitute a complete
data package for each observational sequence. These packages are archived at ISAS, and the identical
copies are delivered to GSFC regularly. The RPT files are also delivered to GSFC for archival and back-up
purposes, so that the First FITS Files may be produced at GSFC if necessary.
The same Pipe-line Processing runs on the First FITS Files at ISAS and GSFC, to apply the calibration
information and to produce the high-level processing products (section 6.6).
2.4.3 Data Delivery to Suzaku Observers

The processing products are delivered to the Guest Observer or the SWG members, as appropriate. US
Suzaku Observers will receive data from GSFC, and Japanese Observers will receive from ISAS. The
proprietary data are placed in on the Suzaku archives with a secure data protection method such as the
PGP encryption.
Suzaku Observers will be able to conduct scientific analysis immediately from the processing products.
The analysis software and user support are provided by the Suzaku GOF (see chapter 3, 4 and 8).
2.4.4 Suzaku Archives

All the Suzaku data will be delivered to and archived at the HEASARC at NASA/GSFC and to the PLAIN
Center at ISAS/JAXA. After the proprietary period is over, the data are made public (i.e., decrypted
1 In fact, the satellite orbit is monitored at ground stations of JAXA/TKSC. JAXA/TKSC determines the Suzaku orbit,
and delivers the orbit files to ISAS regularly.

version will be made available), so that archive users are able to obtain exactly the same datasets as the
original Guest Observers have received. From time to time, contents of the archives ma be updated, after
being reprocessed with updated software and calibration files. Details of the Suzaku archives are explained
in chapter 9.
SWG Suzaku
Observations Science Working Group
Suzaku PDMP v2.0 (September 27, 2007)

Calibration Suzaku
Observations Proposals US
Team Selection Guest Observers
Merging in USA
TOO Calibration
Figure 2.1: Overview of the Suzaku mission operation and observation program.
Observations
Selection Proposals Japanese
in Japan Guest Observers
GO
Observations
ISAS
Attitude
Proposal Determination Attitude
Database Files
Telemetry Pipe-line Processed
Database First FITS
Observation Files Processing Products
(SIRIUS) FITS
Scheduling Database Conversion
Operation Orbit
Center Files
Raw Packet
Telemetry Calibration
Operation
Commands (RPT) Database
Log
Delivery Mirrored
Raw Packet GSFC

Quick Data Calibration
Operation Telemetry Attitude
Look Acquisition Database
(RPT) Files
USC Orbit
Processed
Products
Files
Pipe-line
FITS Processing
Commands Data First FITS
Conversion
(backup) Files
Orbit
Satellite
Determination
Suzaku
(JAXA/TKSC)
archives
Proposal
Database
11
Observation Archival
Database Database
Mirrored
Chapter 3
Software Principles
In this chapter, we present the Suzaku software principles and agreements, which all the software developers
need to follow throughout the Suzaku project.
3.1 General Software Design Principles

Suzaku data analysis system should share the same design principles with all the other projects conducted
under OGIP. These design principles may be summarized as follows:
1. Standard and portable data format — FITS (Flexible Image Transport System) format is adopted
for all the binary files. System dependent binary files will never be used. Moreover, the existing
OGIP conventions should be followed wherever possible, and new conventions should be submitted
to HEASARC FITS Working Group to check for consistencies with other missions. Use of ASCII
format is allowed for small files.
2. Universal and unique software — There should not be multiple channels of the data analysis. Software
releases are controlled, and the same routines used for the instrumental calibrations by hardware
teams are used for the scientific data analysis by Guest Observers.
3. Designed for multimission analysis — Existing software infrastructures will be utilized as much as
possible. Users will be able to analyze Suzaku data with standard high-level X-ray data analysis
packages such as XSPEC, XIMAGE, XRONOS, etc.
4. Easy to install and use — The software will be easy to install and use, and extensive help, support
and documentation will be provided. Suzaku specific software for low-level tasks are distributed in
the standard FTOOLS package, providing user friendly interface on most standard platforms (section
3.3.3).
5. Free and public software — Users will not have to purchase any commercial software packages (such
as IDL), and all the source codes will be open and easily available at free of charge. Users will not
have to worry about license issues, and software authors shall not claim any privileges or credits.
Users may modify and distribute Suzaku software freely on their responsibility.
3.2 Suzaku Specific Design Principles

In addition to the general design principles above, Suzaku GOF and ISAS propose the following design
principles for the Suzaku software/data processing system. They reflect the experiences from the ASCA
mission.
12
1. The raw telemetry will be converted to FITS format before distribution. There is only
one set of software (mk1stfits; section 6.3.1) to access and interpret the raw telemetry data and to
convert them to the FITS format (First FITS Files; section 6.3). Mk1stfits, as well as other processing
software, must be fully tested and ready before the launch of the satellite.
2. All the calibration and data processing should start from the First FITS Files. To that
end, the First FITS Files should reflect the original structure of the raw telemetry as much as possible.
3. All the scientific analysis starts from the standard calibrated FITS files. The First FITS
Files are further processed by the standard software with instrumental calibration information, and
the Calibrated FITS Files (section 6.3) are produced. Scientific outputs are produced always from
the official Calibrated FITS Files, and there should not be other routes for scientific analysis.
4. The same processing system to calibrate the First FITS files should run at GSFC and
ISAS. Thereby, US and Japanese Suzaku Observers shall receive the identical Calibrated FITS Files.
5. Important calibration tools/software should be made promptly available to GOs. At any
given time, there shall be always a single version of the official instrument calibration files and software
controlled by the Suzaku GOF and instrument teams. This ensures that the Suzaku Observers can
apply the latest calibration information to the observing data.
6. Suzaku software will be written by the Suzaku software and hardware teams at GSFC,
ISAS and other institutions in Japan. Tasks which require deep understanding of the Suzaku
instruments, spacecraft and telemetry formats will be mainly written by the members of the hardware
teams and ISAS. On the other hand, higher level tasks, in which user-friendliness, standardization
and conformity with other high energy missions should have a high priority, will be mainly written
by the software team at GSFC.
7. All the software for public release will be delivered to Suzaku GOF before the release.
Suzaku GOF will ensure that the software follow the rules presented in this chapter, and will package
them in a form which is suitable for general release. Suzaku GOF will be responsible for releasing and
maintaining the packages. When modifications or bug fixes are necessary, the Suzaku GOF will be
responsible for the fix and the re-release, contacting the original authors as needed. When significant
changes are necessary, Suzaku GOF will always consult the original authors in advance.
8. Tasks required for the Pipe-line processing should run in scripts. In the automated pipe-
line processing system (section 6.6), series of data processing tasks are run as background jobs by
scripts. Therefore, all the processing tasks including those which make use of GUI are required to
run in scripts.
3.3 Suzaku Software Standards

3.3.1 Languages
Suzaku software will be mainly written in C. The use of C++ is allowed, but not encouraged. C++ will
not be adopted throughout the project, but may be used within some small independent packages (e.g.,
ray-tracing program). Fortran77 is allowed, but Fortran90 shall not be used.
In the scripting tasks, use of system independent environments such as Perl or Tcl/Tk is recommended.
Use of the shell languages (such as csh, bsh and tcsh) which do not run beside UNIX environment is
forbidden.
3.3.2 Coding Rules and Compiler Requirements

Portable coding practices shall be adhered to, including the isolation of system dependencies. C programs
will adhere to the ANSI C standard, while Fortran programs will follow the OGIP Fortran standards
(Mukai 1993)1 for Fortran programming.
The system-independence test for C shall be that the code can be compiled by gcc on the several
supported architectures (see section 3.3.3); similarly g77 will be used to test Fortran programs. The
cfortran package shall be used to combine C and Fortran routines when necessary.
To write and read FITS files, cfitsio (in C) or fitsio (in Fortran) should be used. The obsolete fitsio
C-wrappers, which were developed to call fortran fitsio routines from C-codes, should not be used.
3.3.3 Systems Supported

All the Suzaku software intended to distribute shall run on the most popular systems of Suzaku users. The
systems are likely to include Sun/Solaris, DEC/Alpha, Linux (Redhat, Power PC), and Apple/Darwin
(Mac-OS X).
3.3.4 Coordination and Version Control

The Software Coordination Group consisting of members from each hardware team, ISAS, and the GOF
shall meet regularly (at least twice a year until and soon after the launch) to ensure software coordinations.
In addition, the GOF shall have one person attached to each hardware team with responsibility to help
coordinate software development. The software coordination group shall also be responsible for ensuring
consistency of FITS keyword naming across teams.
The 1st Stage Software (section 6.3) is maintained by ISAS. GSFC keep master copies of all the software
except the 1st Stage Software under a control system. This control system shall ensure that a given file
is only edited by one person at a time and also that previous versions are archived and can be recovered.
The practical way that Suzaku FTOOLS will be developed and maintained globally is explained in section
3.4.
3.3.5 Documentation
All software intended for distribution should be fully documented in English. Comments in the source
codes should be written in English, but Japanese translation might be added for convenience and may not
have to be stripped when distributed.
All subroutines/programs of general use shall contain a standard header. The GOF will provide a script
to strip out these headers and make them available over the Web. The GOF will also provide template
routines containing the standard header.
The FITS file format of Suzaku related files is fully explained in a separate document maintained by
the Suzaku GOF.
3.4 Suzaku FTOOLS Global Development Scheme

Many scientists and programmers in the United States and Japan are involved in the Suzaku FTOOLS
development. Also, Suzaku FTOOLS users are located not only in the two countries, but also in Europe
and the rest of the world. Therefore, version control will be very important so that no different flavors of
the same FTOOLS be developed and proliferated.
In the early stage of the mission, as understanding of the instruments deepens and new data analysis
techniques are getting established, it will be necessary to update and release the Suzaku FTOOLS promptly.
We should be ready for the release cycle of a few weeks or less.
1 See http://heasarc.gsfc.nasa.gov/docs/journal/ogip fortran3.html. This is ANSI Fortran77 with some extensions.
The extension includes the following: (1) Both upper and lower case letter are allowed. (2) END DO are allowed. (3) DO
WHILE loops are allowed. (4) INCLUDE statements are allowed. (5) INTEGER*2 data type is allowed. (6) Variable can be
up to 31 character long. (7) IMPLICIT NONE is allowed.
Suzaku
GSFC Official
ftools release anonymous Users in US
(once or twice a ftp and Europe
Test year)
Develop Release
Ftools Ftools
Build Suzaku
weekly Used
Test add-on for
GOF analysis
Repository
Build anonymous
Suzaku ftools Suzaku ftp
as needed
Ftools Users
team pipe-line
processing
system
Software
Development Processing
Coordinator Ftools
Deliver Mirrored Mirrored

new codes as needed Daily
Processing Release
pipe-line
Center processing Ftools ftp Suzaku
Software Users in Japan
system
Development Suzaku
Coordinator add-on
Processing
Check Ftools
Consistency Used
for
analysis
Suzaku
XIS team Users
Test
HXD team
Test ISAS
Figure 3.1: Suzaku FTOOLS global development and version control scheme.
To accommodate both requirements of the rigorous version control and prompt release, the following
scheme, which is illustrated in figure 3.1, has been proposed and will be practiced for the Suzaku FTOOLS
development, version control, and release.
1. At GSFC, the FTOOLS team maintains the FTOOLS “Repository”, for which only the team mem-
bers are granted the write permission. The FTOOLS team receives original source codes from the
“Contact” groups (through ISAS when the Contact groups are in Japan; see 6 below), and put
the codes in the Repository, after minimal programmatic changes if necessary. The codes in the
Repository should be considered the genuine copy of the latest official FTOOLS.
2. The entire FTOOLS directory tree is built weekly from the Repository. This FTOOLS is called
“Develop” FTOOLS, and only available inside GSFC. The Develop FTOOLS are tested at GSFC,
and the codes will be fixed if any problems are found, and put in the Repository again. Note that
the Develop FTOOLS reflect updates of all the FTOOLS including Suzaku.
3. From time to time, the entire FTOOLS package is released to public. This package is called the
“Release” FTOOLS. Frequency of the release is typically once or twice a year.
4. In order to keep up with short development cycle, whenever Suzaku FTOOLS in the Repository
are updated, the FTOOLS team will build the Suzaku FTOOLS against the Release FTOOLS, and
install the “Suzaku add-on”. Interval of the Suzaku add-on build will be as short as one week (=
Develop FTOOLS build cycle). The Release FTOOLS with the Suzaku add-on is the one Suzaku
users will use for their data analysis. The Suzaku add-on package will be promptly released to Suzaku
users, so that they can install it on their own Release FTOOLS.
5. The Release FTOOLS with the Suzaku add-on will be mirrored daily to ISAS, and will be used
for Suzaku data analysis at ISAS. Japanese Suzaku users outside of ISAS may obtain the original
package from GSFC or mirrored one from ISAS.
6. Instrument teams in Japan will test and modify the source codes in the Suzaku add-on package
to reflect the latest calibration, and they will deliver the new codes to the Software Development
Coordinator at ISAS. The Software Development Coordinator will make sure that the codes from
different groups are consistent and can be built cleanly using gcc. After that, he or she will deliver
the codes to the FTOOLS team at GSFC (go back to step 1).
7. The Processing team at GSFC will obtain the Release FTOOLS with the Suzaku add-on, which
will become the base of the pipe-line processing. The Processing FTOOLS, as well as the pipe-line
processing scripts, will be mirrored to the ISAS processing center from GSFC, so that the data centers
at GSFC and ISAS use the identical system to produce standard Suzaku data products.
8. The processing software should be built-in the software packages HEAsoft, and the processing should
be performed with the the latest release (ver. 6.0.3 in November 2005).
3.5 Suzaku Ftools Release Plan

1. Ftools delivery should include .par files, .hlp files and unit test scripts following the templates provided
by HEASARC.
2. Freeze dates of the Suzaku ftools on the GSFC CVS are the last days of January, April, July and
October. After the freeze, only bug fixes may be committed to the CVS.
3. After the freeze dates, Suzaku ftools go through the multi-platform test at GSFC and ISAS, which
takes maximum six weeks.
4. After the multi-platform test, Suzaku ftools release will be around March 15, June 15, September 15,
and December 15. These release dates may be slightly shifted being affected by situations of other
ftools development/release, because it is desirable that Suzaku ftools release be synchronized with
other ftools release as much as possible.
5. After the release, new ftools, libraries or new functionalities may be committed to the GSFC CVS.
Going back to 1 above, the next release cycle starts.
Chapter 4
Suzaku Function Libraries
There will be software modules that are used repeatedly in various stages of the Suzaku mission, from the
satellite operation to the scientific data analysis. In order to avoid overhead and inconsistency, functions
supposed to be used by two or more tools will be included in the Suzaku function libraries.
There will be at least three such function libraries for Suzaku; aste tool, which includes functions for
Suzaku specific tasks, atFunctions, which includes functions for generic attitude and orbital related tasks1 ,
and xrrt, which is for XRT ray-tracing. They are implemented in the FTOOLS package as libastetool.a,
libatFunctions.a, libxrrt.a, respectively2 .
4.1 Suzaku Specific Tasks (aste tool)

4.1.1 Time Conversion
Routines to carry out conversion between Suzaku time and other time systems will be necessary. Suzaku
time will be defined as the elapsed time from the beginning of year 2000 in UTC. The leap second table is
referenced to take into account the leap seconds.
4.1.2 Coordinate Conversion

Since the XIS is an imaging instrument, coordinate systems for XIS images are must be defined. Functions
to carry out conversion between these coordinates will be necessary (e.g., when making observation plans
and calibrating FITS event files), and will be included in aste tool.
4.1.3 Energy Calibration

Suzaku instruments measure X-ray photon energy as pulse heights; the raw measurements are referred to
as the Pulse Height Analyzer (PHA) channels. Although PHA values are roughly proportional to the input
energies, they vary with several conditions such as time, location on the detector, temperature, etc. After
correcting these effects, we may define Pulse Invariant (PI), which should be perfectly proportional to the
energy.
We will need to calculate PI from PHA for all the three instruments to fill the PI columns in the event
FITS files (section 6.4). The routines to calculate PI from PHA shall be included in aste tool. These
routines need to access calibration files to get calibration information (chapter 7).
1 atFunctions has been used also for ASCA.
2 On the Unix platforms. For other platforms, the names will be different.
17
4.1.4 HK Information Acquisition

All satellite and instrument housekeeping (HK) parameters are stored in the HK FITS files (sections 2.4.2
and 6.3), which can become huge. However, only a small fraction of the HK parameters will be actually
required for scientific data processing. In order to facilitate the use of HK files, HK file access routines
shall be provided in aste tool. Note that HK access routines need to be built with efficiency in mind.
HK parameters in the telemetry are digitized at discrete intervals, thus aste tool routines may have
to convert them to physical values, and interpolate or smooth them as needed. For example, we may
require an aste tool routine which gives instrument temperatures in degrees continuously by interpolating
discretely measured temperatures in digitized units.
Parameters for conversion from the digitized HK telemetry to the physical units are stored in the
multimission database named Satellite Information Base (SIB) located at ISAS. Although SIB itself is not
portable, Suzaku related information in SIB will be necessary to interpret HK parameters in the telemetry.
Therefore, essential parts of the SIB will be extracted and put in the calibration files (section 7.4.1).
4.1.5 Other Tasks

Functions for other tasks will be included in aste tool as needed. For example, a random number generation
function will be required so that the same sequence of random numbers are always obtained from the same
seed.
4.2 Attitude and Orbit Related Tasks (atFunctions)

The attitude and orbit related functions in atFunctions will be used in various purposes such as; command
planning, assignment of SKY coordinates to events (section 6.4), creation the Filter files (section 6.4.1),
calculation of the exposure maps, and barycentric corrections (section 6.5.3). They may require the attitude
files, the orbit files, or both (section 6.2). The following are examples of the tasks in atFunctions.
4.2.1 Attitude Information

• Obtain q-parameters and/or Euler angles for a given time.
• Determine the pointing direction of each telescope/sensor for a given time.
4.2.2 Orbit Information

• Obtain satellite orbital position for a given time.
• Obtain magnetic cut-off rigidity for a given time.
• Determine if the satellite is in day (sun-lit) or dark (not sun-lit) for a give time. Also obtain the
elapsed time after the last day-to-dark or dark-to-day transition.
• Determine if the satellite is in the South Atlantic Anomaly (SAA) or not for a given time. Also
obtain the elapsed time after the last SAA passage.
• Obtain sidereal direction of the magnetic field line for a given time.
4.2.3 Attitude and Orbit Information

• Output the angles from the earth rim and sun-lit part of the earth for a given time.
• Determine if the pointing direction is blocked by earth or not. If it is, determine if the earth is sun-lit
or not.
4.3 Ray-Tracing Function Library (xrrt)

The Suzaku ray-tracing package named xrrt has been written in C++, and is available as a function
library. This library provides function to load mirror, obstruction, and reflection tables from FITS files,
and then to trace photons through the mirror sets and collect statistics about the results. See section 5.2.3
for detail.
Chapter 5
Planning and Simulation Software
In this chapter, Suzaku software used for observation planning and simulation are explained.
5.1 Observation Planning Software

5.1.1 TAKO (Timeline Assembler, Keyword Oriented)
A planning software package named “TAKO” (for Timeline Assembler, Keyword Oriented) is developed
for Suzaku by GSFC based on the methods used for ASCA and XTE.
This package is designed to accommodate Suzaku specific constraints. These constraints are determined
in cooperation of ISAS and GSFC instrument and operations teams. Post-launch changes will be handled
in a similar fashion. As has been the case for ASCA, a technician is employed by GSFC and stationed at
ISAS to maintain and operate TAKO to produce regular observation schedules.
5.1.2 MAKI
MAKI is developed at GSFC for Suzaku and future multimission planning1 . Users may run MAKI through
a Web browser (users will need to obtain and install the “LHEA Plug-In”2 ). Users may place different
satellite fields of view on a sky image to plan out observation (Euler angles are automatically calculated).
These FOVs may be rotated, and MAKI will indicate if the roll is allowed or not by different colors for a
given time period. Users can also view the sun angle visibility limits for several missions, as well as adding
phase constraints. MAKI is expected to replace the ASCA command planning program “adcongra” which
had similar but more primitive functions.
MAKI accepts a sky image file from “SkyView”3 , or almost any FITS image files. It also lets users save
and reload the results. In figure 5.1, an example of MAKI output is shown.
5.2 Simulation Software

Suzaku simulation software will have the following purposes. First, simulation software will be used to
study technical feasibility of planned observations. Second, they will be used to determine instrumental
responses in order to simulate and understand physical processes in the instruments. Third, they may be
used in data analysis when instrument responses are difficult to determine and Monte Carlo approach is
1 See the MAKI home page http://heasarc.gsfc.nasa.gov/Tools/maki/maki.html for detail.
2 The LHEA Plug-In is developed at LHEA at NASA/GSFC. It is a web plug-in that lets users use interactive astronomy
tools via the simple interface of users’ browser.
3 SkyView is a “Virtual Observatory” on the Net generating images of any part of the sky at wavelengths in all regimes from
Radio to Gamma-Ray. See http://skyview.gsfc.nasa.gov/skyview.html for details. MAKI can launch from the SkyView
output page if “Advanced” interface is selected.
20
Figure 5.1: An examples of the MAKI plot. An XRS field of view is displayed on an optical image obtained
from SkyView.
considered more effective. Finally, simulated data sets will be used to verify software for data analysis and
processing.
5.2.1 Counting Rate Simulation – PIMMS

When planning observations, the first thing needed is to estimate the expected counting rates. For such
a purpose, PIMMS (Portable, Interactive, Multi-Mission Simulator) has been developed at GSFC and
already widely used in the community. Users will be able to estimate the expected counting rates for XIS
and HXD by inputting the source flux and the spectral form. The source flux can be a physical unit (ergs
s−1 cm−2 ) or counting rates from other satellites/instruments.
As of ver. 3.6 released in late 2004, PIMMS calculates expected counting rates for Suzaku. See details
at
http://heasarc.gsfc.nasa.gov/docs/software/tools/pimms.html4.
5.2.2 Spectral Simulation – XSPEC

The XSPEC spectral fitting package has the capability to simulate instrument dependent pulse-height
spectra for given input photon spectra5 . To that end, XSPEC requires not only the effective area and
efficiency (ARFs – Ancillary Response Files), but also the response matrices (RMF – Redistribution Matrix
Files).
4 The WWW version of PIMMS, WebPIMMS is also developed and available at
http://heasarc.gsfc.nasa.gov/Tools/w3pimms.html.
5 The WWW version of the XSPEC spectral simulation, WebSpec, is available at
http://heasarc.gsfc.nasa.gov/webspec/webspec.html.
GOF has released a suite of the Suzaku response functions for spectral simulation purposes. See,
http://heasarc.gsfc.nasa.gov/docs/suzaku/aehp prop tools.html for details.
5.2.3 XRT Ray-Tracing Library – libxrrt

The ray-tracing package, named “xrrt”, was developed at GSFC ADF (Astrophysics Data Facility) in
cooperation with ISAS, Nagoya University and GSFC mirror team (code 662). The package is written in
C++. It is available as a function library (section 4.3) for use by other FTOOLS such as xissim.
The ray-tracing package will be used to determine physical parameters of the mirrors which are difficult
to measure (e.g., surface densities), by comparing the actual data and simulations. XRT responses such
as point spread functions and effective areas will be determined through iterations of the ray-tracing
simulations and actual calibration data.
The ray tracing package is also useful to simulate observations when making plans or analyzing data.
For example, if there are bright sources outside of the field of view, amounts of the stray-lights can be
estimated through the ray-tracing simulations.
5.2.4 Suzaku XIS Event Simulator xissim

A simple simulation with XSPEC does not work in estimating contamination from nearby sources or
a position dependent spectrum of extended sources, coupled with the image quality. Such estimates are
sometimes necessary for proposing new Suzaku observations or comparing the observing data with the faked
data of a complicated model through Monte Carlo simulations. The instrument team has developed the
photon-by-photon simulator of XIS events, xissim6. The simulator is comprise of two tasks: mkphlist,
which fakes incident photons from celestial sources in the XIS FOV, and xissim, which simulates XIS
events of the faked photons, taking into account the XRT efficiency and the XIS response. The software
outputs photon event files as the real observing data, so uses can analyze the simulated data with the
generic XANADU software.
6 the xissim software package can be downloaded from http://heasarc.gsfc.nasa.gov/docs/astroe/prop tools/xissim/xissim usage.html
Chapter 6
Data Analysis and Processing

Software
In this chapter, we define and explain Suzaku software tasks that are used for the data processing at ISAS
and GSFC and for the data analysis by Suzaku observers. The naming conventions of product files and
directory structures can be found in more detail in the Interface Control Document (ICD)1 .
6.1 Overview
In figure 6.1, we provide an overview of the Suzaku data flow, which we divide into four stages: satellite
specific calibration (Stage 0), production of the First FITS files (Stage 1), instrument specific calibration
(Stage 2) and data analysis (Stage 3).
In general, software tools used in the earlier stages (Stage 0, 1) do not need to be portable since they
run only at ISAS and/or GSFC, but they must be stable so that data need not be run through these stages
repeatedly. On the other hand, software used in the later stages (Stage 2, 3) must be portable and flexible
since they are distributed to Suzaku users for data analysis and for reprocessing when new calibration
information becomes available. All distributable Suzaku software are built and distributed within the
FTOOLS package (table 6.3 for a full list).
6.2 Stage 0 – Satellite Specific Calibration

In this stage, the Suzaku team at ISAS collects the orbital information, processes satellite specific cal-
ibration, and converts satellite raw telemetry data and satellite specific information to the Raw Packet
Telemetry (RPT) files, attitude FITS and orbital FITS files. The output RPS files are regularly copied to
the database at GSFC as back-up (figures 2.1, 6.1 and 6.2).
6.2.1 Orbit Determination

JAXA/TKSC determines the Suzaku orbit and sends the data regularly to ISAS. The data are converted
to FITS format, containing both the orbital elements as well as explicit satellite positions as a function of
time during the relevant period.
6.2.2 Attitude Determination

The NEC/Toshiba space system develops the attitude determination software as for the GINGA and
ASCA satellites. ISAS hires technicians who will work full-time on the attitude determination. The
Suzaku attitude files have the same FITS format as the ASCA attitude files.
1 http://heasarc.gsfc.nasa.gov/docs/suzaku/archive/astroe icd sdc v1.2.pdf
23
Suzaku Uchinoura
Satellite Space
Center
Raw Telemetry
Stage 0 Satellite Specific ISAS

Corrections
Raw Packet Telemetry (RPT) Files
Attitude Files
Orbit Files
Stage 1 FITS Conversion GSFC
First FITS Files

Stage 2
Calibration
Processing products
Stage 3 Data Analysis
GOAL
Presentation
Publication Guest
Observers
Figure 6.1: Overview of the Suzaku data flow.
6.2.3 Raw Packet Telemetry Files

The Suzaku data are downlinked at USC, sent to ISAS and stored in the telemetry database, SIRIUS, of
the ISAS data center,2 accessible through from UNIX workstations. SIRIUS embeds additional informa-
tion into the original Suzaku telemetry when the Suzaku team accesses the data through the depacketer.
The software astetimeset determines actual time corresponding to the satellite clock using the orbital
information, and produces a timing correction (“tim”) file. The final products of the processing are Raw
Packet Telemetry (RPT) FITS files, which have formats almost identical to the SIRIUS output, wrapped
by the FITS header, as well as an orbit file, an attitude file, and a tim file. The maximum data size of one
RPT is set at ∼2GB, and multiple RPT files can be produced if the data size exceeds the limit. An RPT
file has three columns; TIME when a packet was created in Suzaku time (see section 4.1.1), the APID and
the CCSDS packet.
6.3 Stage 1 – Production of the First FITS Files

The ISAS Suzaku team processes RPT files with the 1st Stage Software mk1stfits and produces the First
FITS Files (FFF). The First FITS Files are composed of the event FITS files with the science data and
HK files with the satellite and instrumental house keeping (HK) data. Since the electronic systems and
coolers of the XRS are working and outputting the HK data through the Suzaku operation, the XRS HK
data are generated regularly. Those files conform to the FITS standard defined by HEASARC.
The RPT files are used only to produce the First FITS Files at ISAS. Any other processes, such as the
routine data reduction and the instrumental calibration, start with the First FITS Files. There are two
exceptions of this rule.
2 The ISAS data center manages data from all past and current ISAS missions.
• The hardware teams may test and debug the 1st Stage Software with the RPT files.
• The GSFC processing team may generate new version of the First FITS Files from the RPT files
when the 1st Stage Software is revised.
ISAS shall routinely transfer to GSFC the RPT files, the 1st Stage Software and related files for back-up,
the First FITS Files for the Stage 2 processing as necessary.
6.3.1 First Stage Software – mk1stfits

The 1st Stage Software is developed by the instrument teams, ISAS, and GSFC. It will not be distributed
to the community, and therefore need not be portable. However, the 1st Stage Software shall be able to
run both at ISAS and GSFC on some specific machines. The First Stage Software consists of the following
components:
mkcom1stfits – binary executable for Common instruments (only create HK files)
mkxis1stfits – binary executable for XIS
mkhxd1stfits – binary executable for HXD
mkxrs1stfits – binary executable for XRS
xissubmode.pl – perl script for splitting the XIS data by the minor modes
mk1stfits – script to run the above software
The executables mk[com,xis,hxd,xrs]1stfits read a single RPT file, assign event time, reformat
event data into standard FITS binary tables, convert raw digital HK readout to physical values and split
a science FITS by major mode. The outputs are the First FITS files with the extension of “fff”, except
for mkxis1stfits, which generates Temporary First FITS files (TFF) of the XIS data with the extension
of “tff”. The perl script xissubmode.pl further splits the TFF files into different minor mode files, and
output the First FITS files.
The major mode is defined as the modes with different event formats. For example, each of the 5x5,
3x3, 2x2 and timing modes corresponds to the XIS major mode, and each of the WELL main event data
and WAM gamma-ray burst data does to the HXD major mode. Therefore, only from the event formats in
the science data packet, the executable mk1stfits can split the data into the different major modes. The
same major mode data in a single RPT file are put in one First FITS file even if they have time-gaps. For
example, if the XIS major mode switches from the 5x5 mode to the 3x3 mode and then back to the 5x5
mode, the first and last 5x5 mode data are combined into one First FITS File. In other words, mk1stfits
separates the input RPT file into different “major” observation modes, and generates a First FITS file for
each major mode.
The minor mode is defined as the data sets that have different characteristics and cannot be analyzed
together. For example, differences in exposure time of the Burst mode, parameters of the Window mode
and numbers of vertical lines added in the Timing/Psum mode represent the minor modes. Since the science
data have no change between the minor mode changes, xissubmode.pl refers to the HK information for
the minor mode split. The on/off of the area discrimination is not regarded as the change of the minor
modes, and is recorded in the EXPOSURES extension (section 6.4.2). Though the HXD well data have
the minor mode in the clocking rate (CLKRATE), they are split at Stage 3–1, when making the cleaned
event files (section 6.5.1). Moreover, CLKRATE is not supposed to change in 1 observing sequence, and
therefore no split should be necessary in the Stage 3–1, either.
Table 6.1 lists the observation data types for the XIS and the HXD.
Mk1stfits should not lose any information in the RPT files (i.e. original telemetry) including low level
instrument data, which are difficult to understand for general observers. It should generate columns of
the physical quantities such as PI, GRADE and TIME, which are calculated in Stage 2, and fills them with
a temporary value of “−999.” Likewise, the First FITS Files should contain all keywords necessary for
analysis. The First FITS Files have a preliminary GTI table, which corresponds to the time intervals
with the telemetry data, and does not depend on the instrumental status or observational conditions (see
section 6.4.2 and 6.5.1). Mk1stfits internally calls functions in the standard FTOOLS package, so that
the 1st stage processing should prohibit FTOOLS parameter files that it use to be overwritten by any other
processes running in parallel.
Table 6.1: Observation data types

Instrument Mode name
XIS 5x5, 5x5 burst
3x3, 3x3 burst
2x2, 2x2 burst
timing psum
frame, frame burst, frame psum
darkframe, darkframe burst, darkframe psum
darkinit,darkinit burst, darkinit psum
darkupdate, darkupdate bst
HXD wel, trn, bst N
Note. — N is numbered as the order of burst signals detected in an observing sequence.
Table 6.2: The HK First FITS Files

Instrument HK identifier Meaning Example
COM none common instrument HK ae100037020.hk
none extended common HK ae100037020.ehk
XRS xrs XRS HK ae100037050xrs 0.hk
XIS xi0,xi1,xi2,xi3 XIS HK for each sensor ae100037050xi1 0.hk
HXD hxd HXD HK ae100037050hxd 0.hk
6.3.2 Convention for naming First FITS Files

The First FITS Files consist of the science (event) files and the HK files. The root names of the First FITS
Files are inherited from the RPT file name. For example, if a RPT file name is ae100037050 0.rpt, its
First FITS File names always start with ae100037050 0.
Event Files (Science Files)

The RPT root name is followed by an instrument name, file number and a major mode name with under-
scores (“ ”) between them. The instrument name is either xi0, xi1, xi2, xi3 or hxd and the major mode
name is 5x5, 3x3, wam, or well, for example. The XIS major mode name is also followed by the onboard
micro code number ranging from 0 to 255. The file number is 0 when a FFF is made from only one RPT
or merged from multiple FFF files, otherwise 1 from the first RPT, 2 from the second FFF, and so on.
The extension is “.fff”.
Examples of the First FITS File names are shown below:
ae100037050xi0 0 5x5n000.fff
ae100037020xi0 1 3x3n000.fff
ae100037050hxd 0 wam.fff
ae100037050hxd 0 wel.fff
ae100037050xrs 0 ff.evt
HK Files
Instrument names are the same as the event files. Suffix of the HK files is “hk”. The HK identifiers, their
meanings and examples are shown in table 6.2.
6.4 Stage 2 – Instrument Specific Calibration

The 2nd Stage Software, so called critical FTOOLS, apply the calibration information to the First FITS
Files to generate the Second FITS Files (SFF). The major task is to populate columns of physical quan-
tities, by referring to the calibration data. The critical FTOOLS are developed by the hardware teams
in conjunction with the GSFC Suzaku GOF, and distributed to public as a part of the FTOOLS package
(table 6.3). Both ISAS and GSFC run the pipe-line processing of this stage (section 6.6).
The 2nd Stage software may add new columns or keywords on the First FITS Files, but it should not
remove any existing columns and keywords, so that the critical FTOOLS runs for the Calibrated FITS
Files as well. This allows Suzaku users to re-calibrate the data from the Calibrated FITS files, without the
First FITS files.
We explain the functions of the Critical FTOOLS by characteristics of tasks.
6.4.1 Stage 2-1 – Preprocess the Supplementary Data

• Determine the pointing direction
The task aeattcor models the attitude wobbling due to the thermal distortion of the satellite body.
Then, the task aeaspect calculates the average pointing direction from the corrected attitude file,
and puts the result on the header keywords of the FFF products (event, hk, attitude and orbit). The
result is later used as a reference point of the sky coordinate.
• Generate extended HK (EHK) files

The task aemkehk extracts attitude and orbit information and generates “Extended HK (EHK) Files”,
which has the same format as the HK files, that is, a table of their physical value as a function of
time.
• Produce a Filter file
The analysis of the scientific data requires only a small part of the enormous HK information, such as
detector temperature, count rates of the particle monitor, attitude and orbital information, magnetic
cut-off rigidity, and intervals of the South Atlantic Anomaly (SAA) passages. The task makefilter
extracts necessary HK items from the HK and EHK files into a filter file. Counting rates of the
instruments and/or BGD monitors are also used for dead time correction (section 6.5.3).
6.4.2 Stage 2-2 – Refine the First FITS Event Files

• Correct event arrival time
The task xisucode obtains information of XIS minor modes for the input 1st FITS files (FFFs) from
a microcode list file in CALDB, and writes important parameters for calibration in header keywords
of the input FFFs. Then, the task xistime corrects event arrival time in the normal, window and
burst modes, which deviate <8 ∼ sec in the First FITS files. The timing mode data need further
precise correction by referring to the RAWY coordinate with xispsumtime (TBD), which runs after
the xiscoord populates the RAWXY columns.
The task hxdtime calculates event arrival time from editing time of the event data packet.
• Update the GTI information

The GTI extension in the First FITS File merely lists intervals with valid telemetry. It is updated
in this stage with xistime for XIS and hxdtime for HXD, to list intervals when detectors are active
and accumulating data from the Filter file. The xistime also lists exposure intervals of the burst
mode. GTIs of the good observing condition such as low background and high elevation from the
Earth rim are calculated in the Stage 3 (see section 6.5.1).
• Record the XIS exposure area
The task xisexposureinfo (TBD) records onto the EXPOSURES extension the XIS exposure area,
or more precisely, the area the data are taken and downlinked. The area discriminated by the
onboard processor is excluded from the list. The list is written in the RAWXY coordinate by each
CCD exposure. This information is used for making the exposure map, for example (section 6.5.3).
6.4.3 Stage 2-3 – Apply the Calibration Data

The event data are calibrated with the CALDB information to physical quantities or equivalent, which are
filled in the corresponding columns.
• Calculate sky coordinate of XIS events

The scientific analysis requires the photon arrival direction on the sky. The task xiscoord converts
the detector coordinate of each event to the sky coordinate, with the reference to the XRT and XIS
alignment calibration in CALDB and satellite attitude at the photon arrival time in the attitude
file. The sky coordinate of each event and the reference R.A, Dec. coordinate are filled in the X/Y
columns and the FITS header, respectively.
• Calculate PI from PHA
The scientific analysis requires the photon energy of the detected events. The tasks xispi for XIS
and hxdpi for HXD convert PHA (pulse heights) values measured with each detector to PI (pulse
invariant) values, which scale to the physical energy of X-ray photons and therefore which are invariant
between detector units. The result is filled in the PI column.
6.4.4 Stage 2-4 – Classify Events

• Classify events from the event pattern
Both XIS and HXD events are classified by event grades, which are defined as the pattern of pulse
heights (PH) of 3×3 pixels for the XIS, and as the hit pattern of adjacent detector units and/or the
coincidence with the anti-detector for the HXD. The grade information is used for particle background
subtraction in Stage 3. The xispi and hxdgrade perform this task for the XIS and HXD data,
respectively.
• Flag XIS events detected at certain pixels
Events detected on certain pixels are likely to be non-X-ray events or X-rays from internal calibration
source. The task xisputpixelquality flags those events in the STATUS column, some of which are
removed in Stage 3. Pixels which are flagged are:
Bad columns and flickering pixels: Some CCD pixels permanently or intermittently pour out or draw
in charges by a defect of electronics on the CCD chips. Such pixels, called bad or flickering pixels,
disguise their PH patterns as X-ray events. The XIS team also found from the on-ground calibration
that the CCD pixels which are read after those bad or flickering pixels in the same CCD column are
mostly insensitive to X-rays, and that the X-ray insensitive area appears as a column on the CCD
chip.
55
Fe calibration source: 55 Fe calibration sources constantly illuminates two corners of each XIS de-
tector. Background level of these areas is higher at around 5.9 and 6.4 keV.
Segment boundary and rows with spaced charge injection and around: Rows with spaced charge
injection (SCI) have charges artificially injected and do not have sensitivity to X-rays. Events detected
at CCD segment boundaries and rows around the SCI rows do not have 5×5 pixel information, and
therefore the background level is higher than those of normal pixels.
The final products of the 2nd Stage are the Unscreened event files (the file extension of “ uf.evt”).
Those files are separated by instrumental modes and have all the necessary keywords and correct GTI
extensions, which are required for extraction of the scientific data products. They still include intervals
which is generally excluded for the scientific data analysis, such as high background and Earth occultation.
6.5 Stage 3 – Data Analysis

The Suzaku observers receive the Unscreened event files and supplementary files necessary for data anal-
ysis from ISAS or GSFC. For the scientific analysis, they need to be processed further: data screening to
maximize data signal-to-noise ratio, event extraction from the aiming target and generation of the cor-
responding instrumental response. The instrument teams study the standard method of data screening
and implement it in the pipe-line processing3 . The users may skip those processes by using the pipe-line
products.
6.5.1 Stage 3-1 – Screen the Data

Data used for the scientific analysis should be contaminated as little as possible by background events.
Through ground and on-board calibration, the instrument teams have studied data screening criteria that
maximize the signal-to-noise ratio of the science data. The pipe-line processing applies this screening
criteria to the Unscreened event files and outputs the Screened event files with the extension of “ cl.evt”.
Here is the standard method of the data screening.
Split Data Sets by Minor Modes

The XIS can set on board different window, grade discriminator and event threshold, and the HXD can
do on the clocking rate. The unfiltered files are not split for the different discriminators or threshold but
this is taken into account in the stage 3 processing.
Generate Good Time Intervals using the Filter File

The users have to remove bad quality data taken in high particle background, inappropriate detector
temperature, low elevation from the Earth rim, unstable satellite pointing, and so on. The generic task
maketime calculates those intervals by referring to the HK parameters in the Filter file, and outputs Good
Time Intervals (GTI), from which the users can extract events taken in the “good interval”.
Filter XIS Data Based on the Frame or Exposure

The Suzaku onboard processor processes XIS events by the unit of discrete “frames”, which corresponds to
one CCD exposure in the normal mode and to multiple exposures in the Window modes. The maximum
data capacity of the telemetry is limited per frame, and any overflows are is automatically discarded.
Data in such a frame, so called telemetry saturated frame, are useless without special treatments, and are
removed from the dataset by the tool xisgtigen.
Filter Events
The instrument teams have studied detector signals through ground and on-board calibrations and found
that certain types of events are more likely to be due to X-rays than others. Events satisfying such criteria
are selected as X-ray events.
• Select XIS and HXD events from their event patterns

X-ray or gamma ray events from the observing sources tend to fall in certain event grades, so that
events with the other grades are discarded. The task fselect selects events with good grades (The
XIS standard analysis picks up events with the grade 02346. The HXD grade selection is different
between PIN and GSO and is complicated.)
• Remove flagged events
The users may discard events flagged in the STATUS column (see section 6.4.4) using xselect.
Events on the bad columns and flickering pixels simply increase the background level, and should
3 The ASCA pipeline processing took almost 4 years to implement the automated data screening, extraction and response
generation into the pipe-line processing.

be removed in any scientific analysis. While the 55 Fe illumination produces strong background at
∼6 keV, it is almost negligible in the other bands. Therefore, events on the masking area can be
useful for soft source analysis, for example. Those events are not removed in the Cleaned Event Files
in the pipeline processing at ISAS and GSFC.
• Select HXD events in the Fast vs. Slow decay-time plane
Fluorescent lights from both GSO and BGO scintillators in the WELL unit are detected with one
PMT at the bottom. Since GSO has faster fluorescence decay time-scales than BGO, signals from
GSO can be discriminated using the pulse shape. Practically, the analog electronics has Fast and
Slow integration circuits with decaying time-scales of GSO and BGO, respectively. Pulses from GSO
and BGO fall onto different regions on the two dimensional Fast vs. Slow circuit pulse height plane.
With those information, the on-board PSD (Pulse Shape Discriminator) can discriminate and flag
the GSO events. However, to check the on-board algorithm and to optimize the region in the Fast
vs. Slow decay-time plane in on-ground data screening, the flookup task is available.4 .
• Select HXD PIN and/or GSO events
An HXD Unscreened event file include all events which hit PIN, GSO, or both. The users can choose
any sets of these events from the grade information using the task fselect.
Data Screening Script – aescreen [TBD]

The Suzaku data processing team will develop the Perl script aescreen [TBD], which carries out the
sequence of the above data screening tasks automatically. The script will have options of the built-in tasks,
which allow users to screen data with their own criteria. The script will run in the pipe-line processing
with the standard criteria to produce the Screened event files (section 6.6). The script is also available for
Suzaku users.
6.5.2 Stage 3-2 – Extract Scientific Products

The users finally extract events from the processed event files with their own scientific interest. They can
produce images, light curves and spectra, which are time, energy or spatially-sliced in need. For such
purposes, xselect, which calls the task extractor inside, is available.
The extraction conditions should be recorded on the produced FITS file header since they may be
needed by downstream software, for example by the instrumental response generator. xselect and/or
extractor may be modified for Suzaku specific requirements.
6.5.3 Stage 3-3 – Generate Analysis Specific Data Sets

The users may generate instrumental response matrices or correct the produced data (e.g. barycentric
corrections and dead-time corrections). The results depend on instrumental conditions, analytical methods,
and the coordinate of the observing target. The users may need to feed the FITS file and/or input
instrumental or physical parameters, so that the software knows specific information of the data, such as
observation date, detector temperature, event extraction region, sky coordinates of the target, and so on.
Generate Response Matrices for Spectral Analysis

To carry out spectral analysis, users need to know detector response to the incident X-rays.
From ground and onboard calibrations, the XRT and XIS teams have extracted information necessary to
build two types of XIS spectral response matrices, RMF (Redistribution Matrix File) and ARF (Ancillary
Response File), as for earlier X-ray satellites with CCD instruments, ASCA, XMM-Newton and Chandra.
The two dimensional matrix, RMF, describes pulse heights of the CCD signal against the irradiated X-rays
onto the CCD chip through the XIS optical blocking filter (OBF), whose flux is normalized at unity. The
4 The flookup implemented on gisclean is used for screening ASCA GIS data, with the discrimination criteria on the PHA
vs. Rise Time plane.

one dimensional matrix, ARF, describes the combination of telescope effective area and transparency of
the XRT thermal shield and of contamination onto the OBF by X-ray energy.
The HXD team have generated on-axis detector response files. The flux from the source at off-axis is
corrected by the auxiliary file, which describe the efficiency ratio relative to the on-axis source.
• Generate XIS RMFs

High energy particles constantly bombard CCD chips and damage CCD pixels. The damaged pixels
reduce charge transfer efficiency between CCD pixels, and a certain percentage of electron charges
is lost before readout. This appears as an increase of noise so that the spectral resolution gradually
deteriorates. Because the amount of charge loss during the charge transfer depends on both number
of pixel transfers on a CCD chip and extent of damage of a pixel, which is proportional to the
amount of irradiation of charged particles, detector responses are a function of the observation date
and the detector coordinate. The RMF generator xisrmfgen feeds the extracted spectral FITS and
the calibration files from CALDB, and outputs a RMF.
• Generate XIS ARF
Observed photon counts depend on the shape of the source extracting region, the source position in
the source region, off-axis angle of the source in the XRT field of view, and the shape of the X-ray
source (ex. point or diffuse source). The ARF generator xisarfgen and xissimarfgen feed these
information from the spectral file, response file and optional parameters, and output an ARF file.
• Generate HXD Response
The HXD team have prepared on-axis response matrices, which include information of both the
detector effective area and detector efficiency. Since it corresponds to the combination of RMF and
ARF, the extension is “rsp”, as the convention of the response file combining RMF and ARF.
The ARF file is not necessary for an on-axis point source. For an off-axis point source or diffuse
source, the arf generator hxdarfgen calculates the observed flux ratio against the on-axis source and
outputs an ARF file (section 7.4.4).
Generate XIS Exposure Maps and Vignetting Maps in Sky Coordinates

The exposure map describes exposure time of each pixel on the celestial (sky) coordinate system. The map
is used when the users measure count rates of sources on an image or make a mosaic image from multiple
images, along with the telescope vignetting map. The users first produce the exposure map of each pixel
on the detector coordinate, from the exposure information in the EXPOSURES extension of the event
file, bad column locations and the calibration-mask-area in the CALDB. From these information, the task
makeexposuremap (TBD) converts the exposure map on the detector coordinate to the sky coordinate, by
referring to the attitude file or the average Euler angle.
The vignetting map describes the telescope effective area and optionally instrumental efficiency. The
telescope effective area on the detector coordinate in CALDB (section 7.4.2) has to be converted to the
sky coordinate, to make a mosaic image.
Generate Background Files

The screened data still have a part of particle background and cosmic X-ray background, whose effect
needs to be estimated from the off-source data. Generally, it is best to take the background from the same
observation, to safeguard against possible background variation. Thanks to the imaging capability, the XIS
data can easily provide a off-source region if an imaging size of an X-ray source is enough smaller than the
XIS FOV. However, the HXD data without imaging information, or the XIS data of diffuse sources that
cover the entire XIS FOV, need background from the other off-source observations. Suzaku observers may
take an individual background data if they need a careful study of background contamination specific to
the source, but the background data or model studied by the instrument team would be enough for most
of the observations.
The instrument teams study the HXD and XIS background from the blank sky, the night Earth and day
Earth data. For the XIS, non-X-ray background is accumulated from the night Earth data and the database
is available from the trend archive. The users can extract background image or spectra from the event files
using xselect. A task generates NXB spectra optimized for the observing and analyzing conditions such
as exposure distribution against COR in an observation and event extracting regions (TBD). The database
for this task will be stored in CALDB (TBD). For the HXD, the background level strongly increases after
the SAA passage and internal background will gradually increase with time since high energy particles
radio-activate PIN and GSO. The instrument team studies behavior of the background spectra in various
conditions, generates database of events during earth occultation sorted with parameters sensitive to the
background level, and reproduces background events for each observation from the database. The HXD
team will prepare archives of background event files for each observation, or develop a tool to reproduce
background events (hxdbackest: TBD).
Correct the HXD Dead Time

The HXD detector has non-negligible dead time in observations of X-ray sources at any flux level, because
of the significant amount of particle background events at all times. The task hxddtcor derives correct
exposure time, by counting pseudo events regularly generated by the onboard electronics.
Correct Event Arrival Time to the Solar System Barycenter

In the precise timing analysis such as the pulse search, event arrival time should be measured at the
barycenteric frame of the solar system. The task aebarycen will convert event arrival time from the
satellite frame to the barycentric frame.
6.5.4 Stage 3-4 – Derive Scientific Results

Suzaku users derive scientific results from these above products. For the analysis, the XANADU packages,
XIMAGE (image), XRONOS (light curve) and XSPEC (spectrum) are available. If users need to re-extract
scientific data or to change data screening criteria, they may return to Stage 3−2 or 3−1. Users may even
go back to Stage 2 to recalibrate the data. However, there will never be the need to go back to Stage 1
(figure 6.1).
6.6 Pipeline Processing System

Most processing tasks in Stage 1–2 run automatically with a Perl script, whose system we call the pipeline
processing (Figure 6.2). The script, developed at GSFC, runs at both GSFC and ISAS with the same
versions of software and calibration files.5 Consistency of the products between GSFC and ISAS are
regularly checked, using the checksum keywords in the FITS header. The pipeline processing mainly
handles tasks in Stages 1, 2 and of the standard screening in Stage 3 (figure 6.1). Suzaku observers receive
Unscreened event files and Screened event files and are expected to carry out the latter half of Stage 3.
When software or calibration files are revised significantly, the pipeline reprocesses all earlier Suzaku
data. The new products are shipped to Suzaku observers if the data are still proprietary, or they are
updated in the Suzaku archives (chapter 9). Version names of the products are, for example, ver 0.1,
ver 1.0, ver 2.0.
5 The ASCA pipeline processing scripts was developed at GSFC ADF and ran only at GSFC. It contains over 14,000 lines
of ksh code.
ISAS GSFC
Backup
RPT RPT
mk1stfits
Distribution
FFF FFF
Critical Critical
FTOOLS FTOOLS
SFF SFF
(_uf) Comparison (_uf)
Data Data
Screening Screening
_cl _cl
DARTS HEASARC
Archive Archive
Japanese Users US Users
Figure 6.2: Overview of the Suzaku data pipeline processing at ISAS and GSFC.
Table 6.3: Suzaku FTOOLS list

Name Order Function
Attitude/Orbit
aemkehk Generate attitude and orbit Extend HK (EHK) files
aemkreg Generating region files of the XIS and HXD field of views
Common/Processing
makefilter Generate a Filter file from HK and EHK files
Common/Analysis
aeattcor Model the attitude wobbling due to the thermal distortion of the satellite body
aeaspect Calculate the mean satellite Euler angle
aebarycen Apply barycentric correction to Suzaku EVENT and HK files
aecoordcalc Calculate coordinates
aetimecalc Calculate mission time
suzakuversion Report the version string for Suzaku package
aescreen Carry out standard data screening of event files (under development)
mkphlist Photon list generator for xissim
XIS
xisucode XIS S1 Fill the microcode information in the FITS header
xistime XIS S2 Fill the time column and the EXPOSURES column
xisgtigen XIS S3 Generate a FITS file with time interval without telemetry saturation
xiscoord XIS S4 Fill the sky coordinate columns
xisputpixelquality XIS S5 Fill the STATUS column
xispi XIS S6 Fill the XIS PHA, PI and GRADE columns
xisllefilter XIS T1 Read information of light leak from fff or sff and output to files
xisexpmapgen calculate a detector mask image and an exposure map in the sky coordinates
xisputhkquality Output an HK file without unimportant HK data (under development)
xisexposureinfo Fill the EXPOSURES extension (under development)
xispsumtime (TBD) Fill the time column for the timing mode data (under development)
xiscontamicalc Calculate the XIS OBF contamination
xisrmfgen Generate a detector response matrix
xisarfgen Generate an auxiliary response matrix (under development)
xissim XRT+XIS photon simulator
xissimarfgen Generate an auxiliary response matrix from the XRT+XIS photon simulation
HXD-WPU
hxdtime Well S1 Fill the TIME column of the Well event file
hxdmkgainhist† Well S2 Generate a gain history FITS file
hxdmkgainhist gso Generate a HXD-well PMT gain history file
hxdmkgainhist pin Generate a HXD-well pin gain history file
hxdpi Well S3 Fill the PI column of the Well data using the gain history file
hxdgrade Well S4 Fill the GRADE column of the Well data
hxddtcor Calculate the dead time correction for PHA files
hxdgtigen Give the GTI to remove the telemetry saturation intervals
hxdarfgen Generate a list of the ratio of efficiency at off-axis
hxdwamtime Wam S1 Fill the TIME column of the Wam event file
hxdmkwamgainhist† Wam S2 Generate a gain history FITS file of the WAM data
hxdwampi Wam S3 Fill the PI column of the WAM data using the gain history file
hxdwamgrade Wam S4 Fill the GRADE column of the WAM data
hxdmkwamlc Make lightcurve(s) from the HXD WAM event file
hxdmkwamspec Make spectra from the HXD WAM event file
hxdwambstid
hxdbsttime Fill the TIME column of the gamma-ray burst event files
hxdmkbstlc Make lightcurve(s) from the HXD Burst event file
hxdmkbstspec Make spectra from the HXD Burst event file
hxdscltime HK S1 Assign time of the scaler HK data
The 2nd column shows the order to run tools in Stage 2 for Snumber and Stage 3 for Tnumber.
†
: hxdmkgainhist and hxdmkwamgainhist read the SFF.
Chapter 7
Calibration
The instrument teams are responsible for the calibration of instruments, which they will release in the form
of documents, software, and calibration files. The latter are released to the public through the calibration
database (CALDB; section 7.3). Suzaku GOF is responsible for obtaining the calibration products from
the instrument teams and providing them to GOs.
7.1 Documentation
In cooperation with the instrument teams and the OGIP CALDB team, Suzaku GOF will provide a set
of documents which describe the Suzaku calibration. These documents should be public and available on-
line in text, postscript, pdf or HTML format. At minimum, the document set should cover the following
subjects:
• Explain ground and in-orbit calibration

Suzaku GOF will help the hardware teams document the calibration activities. It will be necessary to
document when and how the ground and in-orbit calibrations are conducted, and which parameters
are determined. Configuration of the calibration experiments should be illustrated.
• Explanations of the calibration files
Origins, formats, meanings, and usages of the calibration files stored in the CALDB (section 7.3 and
7.4) should be explained.
• Algorithms for building responses and making corrections
The algorithms for constructing instrumental responses and perform instrument specific corrections
using calibration files and software should be explained. For example, it should be explained how
RMFs and ARFs are created from spectral files, and how exposure maps are made from event files
and attitude files.
• Summarize important calibration parameters
Important satellite and instrument parameters determined through calibration should be summarized.
These parameters include, for example, positions of the optical axis for each sensor.
• Calibration uncertainties
The instrument teams are responsible for documenting the limits of current calibration, such as the
systematic uncertainties in the latest spectral responses.
35
7.2 Calibration Software

Calibration software are developed by the instrumental teams, and will be incorporated into the function
libraries (section 4), simulation software (section 5.2), and response generators (section 6.5.3). Suzaku
GOF will make the calibration softwares conform to the Suzaku software conventions (chapter 3).
When constructing instrumental responses or carrying out instrument specific corrections, it is impor-
tant that algorithms and parameters be separated as much as possible. The calibration software should not
include hardwired parameters, instead reading instrumental parameters from the calibrations files. This
ensures that, when parameters are updated by a new calibration, only calibration files need be changed,
and will make it possible to test different responses simply by changing parameters.
7.3 Calibration Database (CALDB)

Suzaku calibration files shall be put in the HEASARC Calibration Database (CALDB)1 , which also contains
calibration files for other high energy missions. All the calibration files in CALDB should conform to the
OGIP standard FITS format.
7.3.1 Structure and Organization

The master copy of the CALDB is located at GSFC under the anonymous ftp directory,
ftp://legacy.gsfc.nasa.gov/caldb/. There are two sub-directories, docs and data (for documents and
data respectively), and those for a particular mission are stored in docs/[mission] and data/[mission],
where [mission] is the mission name. There are instrument directories data/[mission]/[instrument]
for each instrument, and each directory contains three sub-directories, pcf, bcf and cpf, which respectively
stands for the primary calibration files, basic calibration files and calibration product files.
Primary calibration files are raw or almost-raw calibration data, and will not be directly used to con-
struct instrument responses. Ground calibration data will be archived and regarded as Primary calibration
data. Calibration files used to perform instrument specific corrections or to construct responses are called
basic calibration files. Responses themselves or calibration files used in the Stage 3 data analysis (section
6.5.4) are called calibration product files.
In the case of ASCA, we did not have primary calibration files. The GIS and SIS teldef files, which
carry important instrumental parameters such as dimensions, misalignments and positional gain variations
of the sensors, are examples of the basic calibration files. SIS and GIS RMFs are categorized as calibration
product files and put under the cpf directory. In the case of Suzaku, we may archive ground calibration
data under pcf. Most of the important calibration files listed below (section 7.4) are considered basic
calibration files.
7.3.2 Time-Dependent Calibration Files

Some calibration files will be time-dependent. If the variation is long enough (> ∼ a few months) and/or
the results should be checked by an expert of the instrument, the calibration files may be put in CALDB.
The HXD gain history and XIS CTI correction are such calibration data. If the variation is as short as the
span of a single observation, the calibration files are created in the pipeline processing although there are
no current examples for Suzaku2
7.3.3 Calibration File Name

Calibration files should be given unique names to indicate their contents and dates of the release, and a
file name and the physical file should have one-to-one correspondence; hence symbolic links should not be
used. The calibration files must have the mandatory CALDB keywords which describe the nature of the
1 See http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb intro.html.
2 The XRS gain history was one.
GSFC ISAS
GOF
CALDB
XRT XIS HXD

Figure 7.1: Delivery of CALDB files between GSFC and ISAS.
files and are referenced by CALDB softwares. Recommended naming convention for the Suzaku calibration
files is the following:
ae inst kind yyyymmdd.ext
where inst is the name of the instrument3 , kind is brief description of the file contents, and must be less
than 8 characters, yyyy, mm and dd are year, month and day of the release, respectively. ext is the file
extension, which can be fits or any other letters to describe the nature of the file (e.g., rmf or arf). Both
inst and kind should not include hyphens (’-’), underscores or periods (’.’).
7.3.4 Version Control

It is essential that the calibration files be under version control and releases be conducted using a well
established procedure. Suzaku GOF and instrument teams have established the standard procedure for
the delivery and release of calibration files. For each calibration file, there shall be a contact person in
the instrument team and in GOF. To avoid confusion, those files are passed through contact persons in
GOF and ISAS. After they checked the validity of the file and agreed to release, the file will be shipped to
CALDB (Figure 7.1).
CALDB already has an established scheme of the version control. Each instrument directory
(/caldb/data/[mission]/[instrument])
has the index file named caldb.indx which contains brief descriptions for all the calibration files included in
this directory and the sub-directories. These information are taken from the mandatory CALDB keywords
in each calibration file. Also in the caldb.indx file are quality and validity flags of all the calibration files
which are to be judged by Suzaku GOF and instrument teams. The CALDB access software, provided
by the CALDB team, can choose the appropriate file based on the validity date and other information in
caldb.indx.
The identical CALDB tree is mirrored to ISAS regularly, although the primary copy of the CALDB is
maintained at GSFC. GOs can obtain and install the entire CALDB on their machines, obtain the subset
necessary for their analysis, or remotely access CALDB at GSFC or mirror sites.
3 Either xrs, xis, xi0, xi1, xi2, xi3, hxd.
7.4 Important Calibration Files

Suzaku GOF and the instrument teams will determine the types of calibration files that are necessary.
Important calibration files are listed below.
7.4.1 General
• Telescope definition files
Alignments between the telescopes and instruments are described. In addition, parameters of the
instruments and the coordinate systems, such as focal lengths and detector pixel sizes are written.
There may be separate telescope definition files for different detectors.
• Satellite Information Base (SIB)
Parameters for conversion from the digitized HK telemetry to the physical units are stored in the
multimission database named Satellite Information Base (SIB) located at ISAS. Essential parts of
the SIB will be extracted and put in the calibration files. These calibration files are used to interpret
HK parameters in the telemetry (section 4.1.4).
7.4.2 XRT
• Effective area
The XRT effective area corresponding to a certain encircled radius is given as a function of energy
for different off-axis and azimuthal angles. Separate files are made for XRT-I and XRT-S. If the four
XRT-Is have different effective areas, there shall be more than one file for XRT-I.
These files are made from calibration measurements and ray-tracing simulations (section 5.2.3), and
used to calculate ARFs and vignetting maps (section 6.5.3).
• Point spread functions
Although point spread functions can be created from ray-tracing simulations, a set of ready-made
point spread functions for different off-axis and azimuthal angles, and possibly for different photon
energies, will be provided for convenience.
Point spread functions are necessary when making ARFs (section 6.5.3) and for image analysis such
as image fitting and image deconvolution.
• Files for the ray-tracing simulations
The ray-tracing program (section 5.2.3) requires two calibration files describing the telescope param-
eters, one for reflectivity and the other for geometrical structure of the foils.
7.4.3 XIS
• Time variable XIS calibration files
Variable instrumental parameters required to calculate PI from PHA for building spectral responses
and effective area are written as functions of time. Gain history (pulse-peak of the calibration
source), Charge Transfer Inefficiency (CTI), quantum efficiency and the OBF contamination will be
such examples.4 Positions of the bad pixels and columns may also slowly vary with time. The µ code
database is updated when an observation uses a new CCD clock pattern.
• Time invariant XIS parameter files
Important time invariant XIS parameters such as area of calibration masks and DAC setup are
written.
4 In the case of ASCA SIS, RDD (Residual Dark-current Distribution) and echo parameters are also variable, and time
history of these parameters are also saved in the individual calibration files. RDD should not be present for XIS.
7.4.4 HXD
• HXD collimator transmission map
Energy dependent collimator transmission is written as a function of the pointing vectors on the
satellite frame. The direction which gives the maximum transmission becomes the bore-site. This
file will be necessary to make HXD ARFs.
• HXD detector parameter file
Important detector parameters required to build responses are written. These parameters should
include, e.g., dimensions of the GSO crystals, silicon PIN diodes and the detector assembly. This file
will be necessary to make HXD RMFs.
• HXD gain history table (GHT)
History of the energy gain of the PIN, GSO, and WAM detectors are written.
Process to generate GHT: There are two types of GHTs, GHT daily and GHT caldb. GHT daily
is automatically generated with hxdmkgainhist every observation (one file for each detector – PIN,
GSO – per observation, not per FFF) and stored in the Trend Archive. GHT caldb is generated from
GHF daily by the HXD team and stored in CALDB. The task hxdpi calibrates the data with the
latest GHF caldb in any processing. The update intervals are TBD (possibly, ∼1 month).
• HXD background parameter file (TBD)
The HXD background is modeled empirically (section 6.5.3). Model parameters necessary to con-
struct HXD background will be stored in the calibration file.
7.5 Suzaku Calibration File Release Plan

1. Suzaku calibration files may be delivered from ISAS to GSFC on the last working day of each month.
2. When a new microcode file is made (ae xis ucodelst YYYYMMDD.fits), the file may be implemented
into the GSFC and ISAS pipelines immediately, independent of CALDB update. At the end of each
month, the new microcode files introduced during the month are delivered to CALDB.
3. Should there be occasional delays of CALDB file delivery, ISAS shall give advance warning toward
GOF.
4. When calibration files require new tasks or new functionalities, these calibration files must be delivered
with the corresponding tasks; namely the delivery may be made on the last working day of January,
April, July or October.
5. When existing files are updated, the format and keywords must not be changed, except for those
keywords that are associated with a particular release (FILENAME, VERSION etc).
6. When new types of the calibration files are created by the instrument teams, their formats and
keywords must be agreed to between ISAS and HEASARC before being ingested into the CALDB.
7. For each delivery of the calibration files, reason of the new delivery and difference from the previous
version should be explained.
Chapter 8
Guest Observer Support
In this chapter, we describe Suzaku GOF’s primary functions for Guest Observer (GO) support. GOF
focuses its effort on supporting professional astronomers located in the United States who submit Suzaku
proposals and analyze Suzaku data. Suzaku observers in Japan and other countries and the Suzaku archives
users all over the world are also within the scope of the Suzaku GOF support, though their primary contact
should be the Japanese help desk at RIKEN laboratory.
In order to perform the following GO support tasks, Suzaku GOF in cooperation with other groups
under OGIP will develop infrastructures such as software, documents and database systems.
8.1 On-Line Service and Help

Suzaku GOF release most updated information through WWW at the Suzaku GOF home page,
http://suzaku.gsfc.nasa.gov/.
On-line help desk is available via the Feedback feature of the GOF web site, to which GOs can ask any
questions regarding Suzaku. Recipients will be the Suzaku GOF members. Suzaku GOF shall have a rota
system so that, at any given time, a single GOF scientist is responsible for all incoming questions.
There shall be extensive Suzaku on-line databases with which GOs can retrieve various Suzaku infor-
mation as well as the archival data. Details on the Suzaku database and archives are explained in the next
chapter.
8.2 Proposal Support

NASA releases NRAs (NASA Research Announcements) for US based astronomers to obtain Suzaku data,
currently as an element of an omnibus announcement. Suzaku GOF is responsible for preparing technical
information associated with such NRAs, including instrumental specs required for GOs to prepare propos-
als. Suzaku GOF will supply simulation tools (section 5.2) and observation planning tools (section 5.1)
which are intended to be used by prospective GOs in the course of preparing proposals.
GO proposals will be submitted electronically through the multi-mission Remote Proposal Submission
(RPS) system.
8.3 Observation Planning

Suzaku GOF will give expert advice to GOs how to plan their observations, such as best instrumental
modes, observational constraints, pointing directions, roll angles and so on. Preliminary observational plans
should be given in the proposals, and the final plans must be confirmed by GOs prior to the observations.
The procedure is that GOF members contact GOs when the short term observation schedule is released,
and ask GOs if there might be any changes from the observations plans in the proposals. If necessary, GOs
40
may make small changes at this stage (e.g., slight change of the roll-angle) consulting GOF advice. Suzaku
GOF conveys the final GO observation plans to ISAS, and the ISAS satellite operation team incorporates
the final plans into the command stream.
8.4 Pipeline Processing and Data Distribution

Suzaku GOF receive data from ISAS and process them by adding calibration information so that the pro-
cessed data are ready to be reduced to the scientific information (section 6.1). The software for processing
will be mainly developed by Suzaku GOF in cooperation with the instrument teams (section 6.1). The
US GOs receive the processed data from GSFC. By default, data will be encrypted and made available for
download, and the encryption key will be communicated to the GOs. Under exceptional circumstances,
other distribution methods (such as using a CD-ROM) may be considered.
8.5 Data Analysis Support

It is expected that GOs would obtain data analysis softwares from OGIP/Suzaku GOF through Internet,
install them, and use them to analyze their data on their own computers. The analysis software will be
developed and supplied by Suzaku GOF and OGIP, and should be simple to install and use (section 3.1).
Extensive documents and on-line help should be provided to assist software installation and use, and a
standard and thorough data analysis manual should be written by Suzaku GOF. The primary method for
GOs to submit questions is via the Feedback feature of the GOF web site.
8.6 Community Oversight

A Suzaku Users Group has been established to provide advise on the Suzaku GOF services. The Suzaku
Users Group will have regular meetings to discuss guest observer support issues.
Chapter 9
Suzaku Database and Archives
9.1 Suzaku Databases

The Suzaku team at ISAS, the Suzaku GOF, and the HEASARC will maintain a set of databases both for
internal and external purposes. Internal databases are stored on secure machines for scheduling, satellite
operation, and data processing purposes. They are maintained at ISAS within the framework of observation
database (ODB) and copies are made available to, e.g., the processing pipeline at GSFC, as appropriate.
Public databases are provided for external users, including both GOs and archive users, so they can
obtain public information and archival data. The latter will be the responsibility of the HEASARC, where
the original will be kept, and can be accessed using the “Browse” interface. By inputting target names
or coordinates, Browse users can seek specific information in the databases and retrieve archival data for
the desired targets. ISAS PLAIN center will copy the public Suzaku databases from the HEASARC and
make them accessible through their own interface. The primary Suzaku database within Browse is known
as suzamaster.
9.1.1 Proposal Database

US GO proposals are submitted to and recorded at GSFC, while ISAS handles Japanese proposals sepa-
rately. Both US and Japanese proposals are submitted electronically through RPS and all the accepted
proposals are put in the proposal database. Such databases are used in the proposal review processes and
the review results are recorded. The entire electronic records for accepted targets become part of the ODB.
Accepted proposals are considered to enter the public domain, and the abstracts and target information
for accepted targets are included in the suzamaster database. This allows Browse users to check if objects
of interest have been already observed with Suzaku, for example.
9.1.2 Observation Database

The ODB is in fact a set of databases, containing proposal information, observation plans, observation
logs, and processing logs. The ODB includes information necessary for the satellite operation, hence access
is strictly controlled.
Each GO observation, IOC observation, TOO observation and calibration observation is given a unique
sequence number, which is used as the primary key in the ODB. The ODB also includes such items as
dates and time of the observation, instrument modes and pointing directions . At ISAS, the scheduling
and command generation software access the ODB to to construct observation schedule and to construct
operation commands.
After observations have been performed, the ODB is used to check the completion of the observations
at ISAS, and the observation logs are made and stored. Status of data processing are also recorded in the
ODB, so that it is readily seen if the telemetry data are received and archived at ISAS, gone through the
Stage 1 and 2 processing, and shipped to GSFC (section 6.1).
42
9.1.3 Processing Database

The Suzaku processing pipeline uses an internal database to track the status of data processing. Starting
with the input from the ODB, the processing logs are entered into the processing database and then results
are sent back to the ODB.
The processing date is used to determine the public release date of GO observations.
9.2 Suzaku Archives

9.2.1 Policy and Responsibilities
All Suzaku data taken with XIS and HXD (including the WAM gamma-ray burst data; section 2.1.7) are
made public after the proprietary period.
The High Energy Astrophysics Science Archive Research Center, HEASARC, which belongs to OGIP,
supports multi-mission X-ray and gamma-ray archival research. The Suzaku GOF is responsible for de-
livering processed Suzaku data to the HEASARC. The HEASARC will then maintain the archives, while
the Suzaku GOF will support archival research while the mission is active. At the end of the mission, the
HEASARC takes over the archival user support responsibility.
9.2.2 Contents
The outputs of the pipeline processing are immediately delivered to the HEASARC kept encrypted until
the end of the proprietary periods, when the data are decrypted.
The products produced in the pipeline processing will be put in subdirectories of each observation
sequence.
9.2.3 Archival Access

The Suzaku data are placed in the HEASARC anonymous ftp area directory,
ftp://legacy.gsfc.nasa.gov/suzaku/data. There will be no restriction on the data access so that any
user may access and retrieve the data through anonymous FTP.
The data will be sorted by sequence numbers, and users may directly go to the desired directories if
they know the sequence numbers. However, we anticipate that most users will access the archives through
the Browse interface by inputting source names or coordinates (section ??).
Appendix A
Acronyms
Acronyms often used in the Suzaku project are summarized with their full-names and related items.
Acronym Full Name Related Item
ADF Astrophysics Data Facility GSFC

AE Analogue Electronics
AO Announcement of Opportunities
APID Application Process ID
BGO Bi4 Ge3 O12 HXD
CALDB Calibration Database

CCSDS Consultative Committee for Space Data Systems
CTI Charge Transfer Inefficiency XIS, ASCA SIS
DE Digital Electronics
DP Data Processor
ESA European Space Agency
FTP File Transfer Protocol

FITS Flexible Image Transport System
FFF First FITS files
FOV Field of View
GHF Gain History File

GO(s) Guest Observer(s)
GOF Guest Observers Facility
GSFC Goddard Space Flight Center
GSO Gd2 SiO5 HXD
GTI Good Time Intervals
GUI Graphic User Interface
HEASARC High Energy Astrophysics Science Archive GSFC

Research Center
HPD Half Power Diameter
HK Housekeeping
HTML Hyper Text Makeup Language
HTTP Hyper Text Transfer Protocol
44
APPENDIX A. ACRONYMS 45
HXD Hard X-ray Detector
IOC In Orbit Check-out

ISAS Institute of Space and Astronautical Science
JAXA Japan Aerospace Exploration Agency
NASA National Aeronautics and Space Administration

NRA NASA Research Announcement
OGIP Office of General Investigator Programs
PGP Pretty Good Privacy

PSF Point Spread Function
PHA Pulse Height Analyzer
PI Pulse Invariance
PI Principle Investigator
PIN Positive Intrinsic Negative
PIMMS Portable, Interactive, Multi-Mission Simulator
PPU Pixel Processing Unit
PSD Pulse Shape Discriminator HXD
RDD Residuals of Dark Distribution ASCA SIS

RIKEN Japanese acronym for
Institute of Physics and Chemical Research
ROM Read Only Memory
RPS Remote Proposal Submission system
RPT Raw Packet Telemetry
SI Scientific Instruments
SIB Satellite Information Base
SWG Science Working Group
TAKO Timeline Assembler, Keyword Oriented Suzaku planning

TBD To Be Determined
TI Time Counter
TOO Target Of Opportunities
USC Uchinoura Space Center
WAM Wide-band All-sky Monitor HXD

WCS World Coordinate System
WWW World Wide Web
XIS X-Ray Imaging Spectrometer

XRS X-Ray Spectrometer
XRT X-Ray Telescope
Appendix B
FTOOLS developers guideline
Here is a guideline by the GSFC FTOOLS team for the programmers developing Suzaku FTOOLS. This
guideline is particularly aimed for Japanese instrument members who are developing in the ANL environ-
ment and going to convert ANL modules into FTOOLS.
B.1 Items to be Delivered

The delivery to the GSFC Suzaku GOF/FTOOLS team should include the software and test example(s).
• Software
– Source Codes
– Parameter files (default)
– Makefile
– Documents: in plain ASCII text and IRAF “lroff” format.
• Examples:
– Relevant input files and resulted output files.
– Test parameter files or test script.
B.2 Source Codes

• Useful informations can be found at:
http://heasarc.gsfc.nasa.gov/ftools/others/develop/develop.html
(FTOOLS developer’s guide, slightly outdated).
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html
(CFITSIO HTML guide) and
http://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c user/cfitsio.html
(CFITSIO manual for C programmer)
• Use the languages of ANSI C, ANSI C++ and FORTRAN 77 only.
• For scripts, use Perl 5.0 or Tcl/Tk 8.0.
• Comply with the standards of ANSI C, ANSI C++ or Fortran 77; do not use system-dependent
extensions or features.
• For codes of mixing FORTRAN and C(i.e, C calls Fortran and Fortran calls C), use cfortran.h from
CERN.
46
APPENDIX B. FTOOLS DEVELOPERS GUIDELINE 47
• For C or FORTRAN FTOOLS, use the cdummyftool and fdummyftool as templates. They can be
found in src/examples/src in FTOOLS release.
• Subroutine or function name must be unique. This is a requirement of packaging the FTOOLS.
• Do not use the hard-coded “scanf” or command line options to read in the parameter in C or Fortran
codes. Use XPI parameter interface. The routines are documented in pfile.h for the C FTOOLS.
• Do not directly write the message to stdout, use the fcecho or fcerr routines in cFTOOLS and xpi
libraries. Put messages into the stdout directly will prevent the task from being used in a pipeline.
In case the use of fcecho/fcerr is undesirable in the development environment, as a compromise, a
centralized output routine should be used whenever “printf” is necessary.
• Provide the English translations for the important comments written in other languages.
• For handling of FITS files, use cfitsio. Do not try to read/write the files using specialized routines.
• In C FTOOLS, do not use the obsolete fcfitsio routines, which are the wrapped Fortran fitsio routines,
which are the wrapped cfitsio routines.
• Before calling the cfitsio routine, make sure the error status is set to zero, otherwise, the routine
returns immediately.
• After calling the cfitsio routine, make sure that the error status still stays at zero. If not, provide the
error handling and return gracefully.
• CFITSIO routine “ffopen” automatically handles the filename parsing, file existing tests etc. Do not
use any parsing routine or file open routines before ffopen. It can hinder the abilities of cfitsio to
open a network file or compressed file.
• “stderr” should only be used to output critical error messages, since the presence of stderr messages
are used by many scripts as part of the error handling mechanism. This restriction does not apply
to “stdout,” but even this should be used with restraint.
• The Suzaku FTOOLS defines the chatter levels in the softwares from 0 (min) to 5 (max) as does
the Swift package. Each chatter level displays 0: critical error messages only, 1: warning messages,
2 (default): useful information, 3: debugging level 1, 4: debugging level 2, 5: maximum debugging
level.
• Finally, do not try to be fancy and clever, do not reinvent the wheel, and KISS (Keep It Simple,
Stupid).
B.3 Parameters
It is well documented in URL: http://heasarc.gsfc.nasa.gov/ftools/others/pfiles.html
B.4 Makefiles
For FTOOLS development, “hmake” is used, which is a version of the “make” utility developed locally
by the HEASARC. It is not necessary for the developers to write the “hmake” style make file. However,
developers should provide a makefile in one of the popular Unix platforms (OSF, Solaris, SunOS, HPUX,
Linux or SGI, Apple/Darwin). the software and understand the dependencies between modules.
APPENDIX B. FTOOLS DEVELOPERS GUIDELINE 48
B.5 Documents
The help file should be provided in a plain ASCII text file with the extension .txt and a file with the IRAF
“lroff” format and extension .hlp. The “lroff” format is quite similar to the UNIX nroff/troff. You can
find it in any .hlp files in FTOOLS distribution.
The help file should include the following sections:
• Name: Name plus a one sentence description.

• Usage: Synnopsis of the tool
• Description: Detailed description of the tools.
• Parameters: Descriptions for parameters.
• Examples: Examples of using the tool.
• Bugs: Known bugs or features of the tool.
• See Also: References to other relevant tools.
• Author: Authorship, credits and e-mail address for questions and bug reports
(It is usually ftoolshelp@olegacy.gsfc.nasa.gov or the help desk of the mission).
Appendix C
Flow Chart of the Pipeline

Processing
Legend
========================================
[ ] critical ftools
( ) user data
" " outputs to trend area
** CALDB access
========================================
=== 0. Common ===
NOTE: The Common processes MUST be executed before HXD and XIS processings.
-----------------------------------------------------------------------------
Attitude file: aeXXXXXXXXX.att
(Attitude file) --> [aeattcor] --> [aeaspect] --> (New attitude file)
^
|
(orbit file) --+
(common HK file) --’
- The original attitude file is supersedesed by the new one.

The ae1 script is expected to take care of this.
- This procedure can be carried out multiple time (i.e. loop) safely.
-----------------------------------------------------------------------------
Orbit file: aeXXXXXXXXX.orb
(Orbit file) --> [aeaspect] --> (Orbit file)

^
|
(New attitude file)
- Some header keywords will be filled.

-----------------------------------------------------------------------------
49
APPENDIX C. FLOW CHART OF THE PIPELINE PROCESSING 50
Tim file: aeXXXXXXXXX.tim
(Tim file) --> [aeaspect] --> (Tim file)

^
|
(New attitude file)
- Some header keywords will be filled.

-----------------------------------------------------------------------------
Ehk file: aeXXXXXXXXX.ehk
[aemkehk] ----> [aeaspect] --> (Ehk file)

^ ^
| |
(Orbit file) --+ (New attitude file)
(New attitude file) --’
-----------------------------------------------------------------------------
=== 1. HXD ===
-----------------------------------------------------------------------------
(WEL FFF) -->
[hxdtime] --> [hxdmkgainhist] --> [hxdpi] --> [hxdgrade] --> (WEL UFF)
** | ** ** **
+--> "aeXXXXXXXXXhxd_0_gso.ghf"
‘--> "aeXXXXXXXXXhxd_0_pin.ghf"
-----------------------------------------------------------------------------
(WAM FFF) -->
[hxdwamtime] --> [hxdmkwamgainhist] --> [hxdwampi] --> ...continue...
** | ^ **
| |
+--> "aeXXXXXXXXXhxd_0_wam.ghf"
...--> [hxdwamgrade] --> (WAM UFF) ---> [hxdwambstid]

|
‘--> "aeXXXXXXXXXhxd_0_bstidt.fits"
-----------------------------------------------------------------------------
(BST FFF) --> [hxdbstid] --> (BST UFF)
**
-----------------------------------------------------------------------------
(HXD HK) --> [hxdscltime] --> (HXD HK)
**
-----------------------------------------------------------------------------
Note for HXD diagram:
- Before starting the HXD processing, aemkehk and aeattcor have to be
run to prepare proper EHK and attitude files.
(The XIS tools should also require them.)
- hxdmkgainhist and hxdwambstid extract the data sets that will be
sent to the trend area after the pipeline. Their products, i.e.,
aeXXXXXXXXXhxd_0_pin.ghf, aeXXXXXXXXXhxd_0_gso.ghf and
aeXXXXXXXXXhxd_0_bstidt.fits
are not used in the pipeline.

- On the other hand, aeXXXXXXXXXhxd_0_wam.ghf generated by hxdmkwamgainhist
will be used by hxdwampi.
- Pin- and gso-ghf required by hxdpi are retrieved from CALDB.
Bstidt required by hxdbsttime is also retrieved from CALDB.
-----------------------------------------------------------------------------
=== 2.XIS ===
-----------------------------------------------------------------------------
XIS hk file: aeXXXXXXXXXxiN_0.hk
(XIS hk file) --> [aeaspect] --> (XIS hk file)

^
|
(New attitude file)
-----------------------------------------------------------------------------
XIS frame FFF: aeXXXXXXXXXxiN_n_f[nbp]MMMiNN.fff
(XIS frame FFF) --> [aeaspect] --> [xisucode] --> (XIS frame SFF)
^
|
(New attitude file)
-----------------------------------------------------------------------------
XIS darkframe FFF: aeXXXXXXXXXxiN_n_dfiNN.fff
(XIS darkframe FFF) --> [aeaspect] --> (XIS darkframe SFF)

^
|
(New attitude file)
-----------------------------------------------------------------------------
XIS darkinit, darkupdate FFF: aeXXXXXXXXXxiN_n_d[iu][nbp]MMM.fff
(XIS darkinit/update FFF) --> [aeaspect] --> [xisucode] --> ...continue...

^
|
(New attitude file)
...--> [xiscoord] --> (XIS darkinit/update SFF)

^
|
(New attitude file)
-----------------------------------------------------------------------------
XIS normal, burst event FFF: aeXXXXXXXXXxiN_n_{5x5,3x3,2x2}[nb]MMM.fff
(XIS event FFF) --> [aeaspect] --> [xisucode] --> [xistime] --> ...continue...
^ ^
| |
(New attitude file) (Tim file)
...--> [xiscoord] --> [xisputpixelquality] --> [xispi] --> (XIS event SFF)
^ ^
| |
(New attitude file) (XIS hk file)
-----------------------------------------------------------------------------
XIS psum FFF: aeXXXXXXXXXxiN_n_timpMMM.fff
(XIS psum FFF) --> [aeaspect] --> [xisucode] --> [xistime] --> ...continue...
^ ^
| |
(New attitude file) (Tim file)
... --> [xiscoord] ------> [xispi] --> (XIS psum SFF)

^ ^
| |
(New attitude file) (XIS hk file)
-----------------------------------------------------------------------------
XIS telemetry unsaturated GTI file: aeXXXXXXXXXxiN_0_telem.gti
[xisgtigen] --> (temporary_xiN_n_ZZZ[nbp]MMM.gti)

^
|
(one of XIS event SFF {normal,burst,psum} x {5x5,3x3,2x2,tim} )
:
:
[xisgtigen] --> (temporary_xiN_n_ZZZ[nbp]MMM.gti)

^
|
(one of XIS event SFF {normal,burst,psum} x {5x5,3x3,2x2,tim} )
[mgtime] --> (aeXXXXXXXXXxiN_0_telem.gti)

^
|
(temporary_xiN_n_ZZZ[nbp]MMM.gti) -+
: :
(temporary_xiN_n_ZZZ[nbp]MMM.gti) -+
(temporary_xiN_n_ZZZ[nbp]MMM.gti) -’
- mgtime is operated with "merge=OR".

-----------------------------------------------------------------------------
Appendix D
Definition of the Coordinate System

used for Suzaku
D.1 Definition of the Coordinates

The following coordinates are defined to describe event locations in the telemetry, on the detector, or on
the sky. All the coordinates are written in the Suzaku event files.
• RAW coordinates:
Original digitized values in the telemetry to identify pixels of the events. May not reflect physical
locations of the pixels on the sensor. For example, XIS RAW X and Y coordinates will have values
from 0 to 255 on each Segment1 .
• PPU coordinates:
Coordinates system used for the Dark Frame mode of the XISs. The PPU coordinates add copied
pixels (2 pixels) at the front and back of the RAW X coordinate.
• ACT coordinates:
ACT is defined only for XIS. The ACT X and Y values are defined to represent actual pixel locations
in the CCD chips. ACT XY will take 0 to 1023 to denote the 1024 × 1024 pixels in the chip. The
XIS RAW to ACT conversion depends on the observation modes (such as Window Options) and will
require housekeeping information. The XIS ACT coordinates is defined by looking-down the sensors.
• DET coordinates:
Physical positions of the pixels within each sensor. Misalignments between the sensors are not taken
into account. The DETX/Y coordinates are defined by looking up the sensor, such that the satellite
+Y direction2 becomes the −DETY direction (the same as the ASCA convention). The DET X and
Y values take 1 to 1024 for XIS.
• FOC coordinates:
Focal plane coordinate common to all the sensors in unit of arcmin. Misalignments between the
sensors as well as the difference of the focal length are taken into account so that the FOC images
of different sensors can be superposed. FOC is calculated from DET by linear transformation to
represent the instrumental misalignment, i.e., the offset and the rotation angle, and the focal length
of the XRT. Information of these misalignment and the focal length are written in the teldef files.
• SKY coordinates:
Positions of the events on the sky. The conversion from FOC to SKY is made using the satellite
1 Each of the four XIS sensors has a single CCD chip, and a single chip is divided into four Segments.
2 Satellite Z-axis points the telescope direction, and +Y direction is toward the solar paddle.
53
APPENDIX D. DEFINITION OF THE COORDINATE SYSTEM USED FOR SUZAKU 54
attitude in the attitude file and the alignment matrix (3×3) written in the teldef file. For each XIS
event, the equatorial coordinates of the pixel center projected on a tangential plane are given3 .
In this scheme, it is important that the conversion from RAW to DET does not depend on the mis-
alignments between the sensors. Therefore, DET XY, as well as RAW XY, can be written in the event
FITS files without having the calibration information. The DET to FOC conversion requires information
of the focal length and the misalignment between the sensors. The same routines/functions can be used
for FOC to SKY conversions for different sensors not depending on the individual characteristics.
D.2 Implementation to the FITS Event Files

D.2.1 Names of the Columns
XIS HXD
SENSOR SENSOR SENSOR
RAW SEGMENT, RAWX, RAWY –
PPU SEGMENT, PPUX, PPUY –
ACT ACTX, ACTY –
DET DETX, DETY –
FOC FOCX, FOCY –
SKY X, Y –
D.2.2 Type and Range of the Columns

XIS
Type Minimum Maximum Origin Size of the Pixel
SENSOR Integer 0 3 – –
SEGMENT Integer 0 3 – –
RAWX/Y Integer 0 255/1023 – 0.024 mm
PPUX/Y Integer 0 259/1023 – 0.024 mm
ACTX/Y Integer 0 1023 – 0.024 mm
DETX/Y Integer 1 1024 512.5 0.024 mm
FOCX/Y Integer (1 1536)a 768.5 0.0174 arcmin
X/Y Integer (1 1536)a 768.5 0.0174 arcmin
a
: Default image region.
The DETXY pixel sizes correspond to the physical pixel size of the XIS CCD. The XY pixel size
corresponds to the angular size of a single XIS CCD pixel. To allow rotation of the image and
√ some shift
of the pointing direction during the observation, the XY range is taken slightly bigger than 2 × 1024.
HXD
Type Minimum Maximum Origin Size of the Pixel
SENSOR Integer 0 15 – –
HXD is not an imaging instrument and will not have coordinate columns. The average pointing direction
may be written in the event FITS file header.
3 There are several projection methods, such as -TAN, -SIN, -ARC and -STG.
See http://www.cv.nrao.edu/fits/documents/wcs/wcs.all.ps for details. The tangential projection (-TAN) is widely used,
and will be adopted for Suzaku event files too.
Bibliography
[1] “The Scientific Satellite Astro-E Interim Report” (“Kagaku Eisei Astro-E Chuukan Houkokusho”),
ISAS, 1998, in Japanese
[2] Serlemitsos, P. J. et al. 1995, PASJ, 47 105
[3] Serlemitsos, P. J. and Soong, Y. 1996, Astrophys. Sp. Sci., 239, 177
[4] Serlemitsos, P. J. 1997, “The Next Generation of X-ray Observatories”, p. 123
[5] Kamae, T. et al. 1996, SPIE, vol. 2806, 314
[6] Takahashi, T. et al. 1996, A&A, 120, 645
[7] Mukai, K. 1993, in Legacy, p. 65,

(http://heasarc.gsfc.nasa.gov/docs/journal/ogip fortran3.html)
55
Index
1st Stage Software, 25 mk1stfits, 25

2nd Stage Software, 27 mkcom1stfits, 25
mkhxd1stfits, 25
Ancillary Response File (ARF), 21, 31 mkxis1stfits, 25
ASCII, 12 mkxrs1stfits, 25
Astrophysics Data Facility (ADF), 22
NASA Research Announcement (NRA), 8, 40
Barycentric correction, 32
basic calibration files, 36 Observatory Time, 7
OGIP, 12
C++, 13, 22
Calibration Database (CALDB), 36 Perl, 13, 32
calibration product files, 36 PGP encryption, 9, 41
cut-off rigidity (COR), 18 pipeline processing, 32
point spread functions, 38
detector simulators, 22 Portable, Interactive, Multi-Mission Simulator (PIMMS),
21
echo, 38
primary calibration files, 36
effective area, 38
Pulse Height Analyzer (PHA), 28
Euler angles, 18
Pulse Invariant (PI), 17, 28
exposure map, 31
Extended HK (EHK) files, 27 q-parameters, 18
Filter file, 27 Raw Packet Telemetry (RPT) files, 9, 23, 24
First FITS Files, 9, 13, 25 ray-tracing package, 22
First Stage Software, 25 Redistribution Matrix File (RMF), 21
Flexible Image Transport System (FITS), 12 Remote Proposal Submission (RPS) system, 40
flookup, 30 Residual Dark-current Distribution (RDD), 38
Fortran77, 13 response generators, 22
Fortran90, 13
fselect, 29 Satellite Information Base (SIB), 18, 38
FTOOLS, 12 Science Working Group (SWG), 7
SIRIUS database, 9, 24
g77, 14 South Atlantic Anomaly (SAA), 18, 27
gcc, 14 Suzaku archives, 8
gisclean, 30 Suzaku GOF, 5
Suzaku time, 17
High Energy Astrophysics Science Archive Research
Suzaku Users Group, 41
Center (HEASARC), 5, 43
Tcl/Tk, 13
JAXA/TKSC, 9, 23
teldef files, 36
ksh, 32 timeconv, 32
Timeline Assembler, Keyword Oriented (TAKO), 20
leap second, 17 Transient Processing Units (TPU), 8
MAKI, 20 Unscreened event files, 28
56
INDEX 57
vignetting map, 31
W3Browse, 42
WebSpec, 21
XSPEC, 21

Suzaku Project Data Management Plan (PDMP)

Uploaded by

Copyright:

Available Formats

Suzaku Project Data Management Plan (PDMP)

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Suzaku Project Data Management Plan (PDMP)

Uploaded by

Copyright:

Available Formats

Suzaku Project

Data Management Plan

Suzaku Guest Observer Facility

4 Suzaku Function Libraries 17

4.2 Attitude and Orbit Related Tasks (atFunctions) . . . . . . . . . . . . . . . . . . . . . . . . 18

5 Planning and Simulation Software 20

6 Data Analysis and Processing Software 23

8 Guest Observer Support 40

9 Suzaku Database and Archives 42

B FTOOLS developers guideline 46

C Flow Chart of the Pipeline Processing 49

D Definition of the Coordinate System used for Suzaku 53

1.1 Scope of this Document

This document is not the original source for:

1.2 Mission Overview

1.3 The Suzaku Guest Observer Facility

• Support of prospective GOs’ proposal preparation

Suzaku GOF WWW home page is located at

1.4 Related Documents

2.1 Observations Types

2.1.2 Observatory Time

2.1.3 Science Working Group Time

2.1.5 Calibration Observations

2.1.6 Target of Opportunity Observations

2.1.7 HXD WAM Observations

2.2 Proprietary Period

2.3 Satellite and Instrument Monitoring

2.4 Data Flow

2.4.2 Data Processing at ISAS and GSFC

2.4.3 Data Delivery to Suzaku Observers

2.4.4 Suzaku Archives

and delivers the orbit files to ISAS regularly.

Suzaku PDMP v2.0 (September 27, 2007)

Raw Packet GSFC

3.1 General Software Design Principles

3.2 Suzaku Specific Design Principles

3.3 Suzaku Software Standards

3.3.2 Coding Rules and Compiler Requirements

3.3.3 Systems Supported

3.3.4 Coordination and Version Control

3.4 Suzaku FTOOLS Global Development Scheme

Deliver Mirrored Mirrored

3.5 Suzaku Ftools Release Plan

Suzaku Function Libraries

4.1 Suzaku Specific Tasks (aste tool)

4.1.2 Coordinate Conversion

4.1.3 Energy Calibration

4.1.4 HK Information Acquisition

4.1.5 Other Tasks

4.2 Attitude and Orbit Related Tasks (atFunctions)

4.2.1 Attitude Information

4.2.2 Orbit Information

4.2.3 Attitude and Orbit Information

4.3 Ray-Tracing Function Library (xrrt)

Planning and Simulation Software

5.1 Observation Planning Software

5.2 Simulation Software

5.2.1 Counting Rate Simulation – PIMMS