Setting Up a NICER Analysis Environment

Overview

Like all X-ray astronomy missions, NICER requires a combination of software, calibration data, and observation data to produce science results. This document describes how to set up an environment for NICER data analysis.

Read this thread if you want to: Set up NICER software and calibration.

Last update: 2021-04-16

Introduction

Like all X-ray astronomy missions, NICER requires a combination of software, calibration data, and observation data to produce science results. To get the consistent and correct results, the analyst's computer should be set up properly. This document describes how to set up an environment for NICER data analysis.

The key components for analysis are:

  • Software - NICER software is released as a part of HEASARC's multi-mission HEASoft package. NICER is one mission-specific component of the package.
  • Calibration Data - NICER calibration data is released as a part of HEASARC's Calibration Database (CALDB) system. CALDB is a way to manage and release calibration data in a consistent and documented way.

This document gives an overview of how to install software and calibration data. Where appropriate, we will link to HEASARC's web pages for further instructions.

Prerequisites

Here is what is needed:

  • A computer and operating system compatible with HEASoft. Linux and Mac OS are supported.
  • If you are going to build from source code, which is recommended, you will need certain developer software. Please see the "Building and Installing HEASOFT" section of the Installation Guide for more information.
  • If you download the binary-only installation, please be aware that you may experience odd compatibility issues.
  • Your computer should have enough free storage (disk space) for software, calibration and NICER data. Typically 2 GB is a minimum
  • Generally you should be able to use the Unix command-line, such as bash or tcsh. NICER analysis is not graphical.

Download HEASoft

You should typically download the most recent version of HEASoft.

  • Download HEASoft from here.

On the download page, you have several choices. We recommend that you download the source code distribution. However, you can choose to retrieve a precompiled software package for some computer operating systems. The selection of pre-compiled software is limited, and users have reported compatibility issues in the past with this method. However, if you are just getting started, pre-compiled binaries may be the quickest and easiest way to try things out.

You will also have to select which components to retrieve. It is often easiest to retrieve "everything." At the very minimum, you should select "NICER," "General-Use FTOOLS," and "Xspec." Click submit and the software will begin to download.

Install HEASoft

Please follow the instructions to install HEASoft on your computer.

When you have completed building and installing the software, you will still need to be sure that it is initialized properly in every session that you use. Typically this involves adding some commands to your startup file (.tcshrc or .bashrc). The installation instructions have more information about how to do this.

When you have completed the installation instructions, you can verify the installation by typing the following command: nicerversion and a version number of the form yyyy-mm-dd_Vnnn should appear.

What is Installed with HEASoft?

It is difficult to describe the full breadth of software that is available within HEASoft, since it supports tens of missions.

A key component is NICERDAS, or the NICER Data Analysis System, which has all NICER-specific data analysis software tools. When you start analyzing NICER data, you will be using NICERDAS tools. A list of NICERDAS software tasks, with task-specific documentation, can be found here.

You will also be using the mission-generic tool called XSELECT. XSELECT provides capability to extract light curves, spectra, and detector images. XSELECT uses a processing engine called "extractor" to do most of its work behind the scenes.

After extracting NICER spectra, you will likely use the spectral modeling software called XSPEC, which included as a part of HEASoft.

Finally, for temporal analysis you may try to use XRONOS. It has tasks for plotting light curves, estimating power spectra and folding pulsar periods.

Installing Calibration Data

NICER analysis software requires calibration data to produce scientific results. Like many missions, NICER uses the HEASARC's Calibration Database (CALDB) system to catalog and distribute calibration data.

CALDB provides not only a way to archive and distribute calibration data, but it also provides a way to "tag" each calibration data set with a unique release identifier. This tagging capability provides a way for analysts to describe in the papers the source of their calibration data.

To install your own local copy of CALDB, you will first download a "framework" and install it, followed by NICER-specific files. For more information, see the installation instructions:

As per the installation instructions, once you have the generic framework installed, you need at least one mission's calibration data: NICER's! Visit the following page:

You will click "Retrieve NICER XTI caldb tar file" and save that file. The CALDB installation instructions (section 3) describe how to install those files into your CALDB framework. This page also links to NICER-specific documents about calibration.

Updating NICER CALDB data to a new version. There may be a time when you wish to download a new version of NICER CALDB data. The steps remain the same. Follow the instructions above, i.e. use the "Retrieve NICER XTI caldb tar file" link to download NICER CALDB again, and install it according to the standard instructions. It is standard practice to never delete "obsolete" calibration files from CALDB. Obsolete files will still be present but marked as "bad" in the calibration index file.

To test that you have properly installed NICER CALDB, you can type the following command: quzcif NICER XTI - - ALIGNMENT now now - and the following response should appear: /path/to/caldb/data/nicer/xti/bcf/pntmis/nixtipntmis20170601v001.teldef 0 The exact path to your CALDB directory, and the exact version number (vNNN) may be different.

Summary

Once you have completed these steps, you should have a functioning NICER analysis environment. You are ready to find and download data from the archive and begin analysis.

Next Steps

Please see the thread titled Calibration Recommendations for more information about recommended calibration practices for NICER analysis.

The thread titled nicerl2 provides standard way to analyze any NICER observation.

Modifications

  • 2020-07-20 - initial draft
  • 2021-04-16 - add navigation bar