Search:

[Advanced Search]



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: 2023-07-24

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.
  • Geomagnetic Data - as of HEASoft 6.31 geomagnetic data is now required to process NICER data (it is not optional).

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.

Resetting Temporary Files After a New Installation

The NICER team has heard reports that, after new software release installations, users occassionally run into problems or error messages due to temporary files lingering from previous release. See NICER Common Errors (SOLARPHI not found) for an example.

After installing a new release, it is recommended to remove temporary files in your parameter files directory. For example, rm $HOME/pfiles/*.par (if you have your parameter files stored somewhere other than $HOME/pfiles, use that directory name). This is completely harmless, and parameter files will be repopulated from the system area as needed.

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.

Geomagnetic Data

As of HEASoft 6.31 (NICERDAS 10), NICER provides several background models to choose from. Some of these models require external data that described the geomagnetospheric properties. This kind of geomagnetic information is not predictable and changes from hour to hour. For this reason, the user must download geomagnetic data and keep it up to date. For more information about this topic, please see the Geomagnetic Quantities thread.

Generally, users should update their geomagnetic data when starting a project. If the user expects to process ToO data, this may mean that the user will have to download new geomagnetic data frequently (i.e. daily).

Although the Geomagnetic Quantities thread contains more details, the basic steps are this:

  • Decide on a location where geomagnetic data will be installed. In this example, let's assume it's /home/myname/geomag.
  • In login file set the GEOMAG_PATH environment variable to this path.
    For bash or sh shells, edit .bashrc to include, export GEOMAG_PATH=/home/myname/geomag
    For csh or tcsh shells, edit .login to include, setenv GEOMAG_PATH /home/myname/geomag
    Please note: place this line just after the HEADAS setup lines.
  • Download geomagnetic data and install (must have internet connection)
    nigeodown

Whenever you desire to update your geomagnetic data, just run 'nigeodown' again and it will automatically download, unarchive and install the geomagnetic files into place. Please see the Geomagnetic Quantities thread for more details and variations.

NOTE. In HEASoft 6.31, nigeodown required the LWP::Simple Perl module to be installed. If you see an error of the form Can't locate LWP/Simple.pm in @INC please see the Common Errors page for a discussion of this issue and possible remedies.

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
  • 2022-12-20 - update for HEASoft 6.31 / 6.31.1
  • 2023-01-09 - add discussion of LWP::Simple failures
  • 2023-07-24 - move nigeodown LWP::Simple discussion to Common Errors page