Search:

[Advanced Search]



How to report NICER software and calibration versions

Overview

It is important to document which versions of NICER software and calibrations you use. This page describes how to do this.

Read this thread if you want to: Report which versions of NICER software and calibration are being used

Last update: 2024-02-15

Introduction

Obtaining useful scientific results from NICER observations is a combination of NICER observational data with software and calibration products. Over time, NICER improves its software and calibration products so that scientists can get the most out of their data.

Thus, it is important for scientists to know which version of software and calibration are being used for their analysis. In addition, it is important to report this information in publications. Since repeatability of experiments is a vital aspect of the scientific method, this information is needed so that other analysts can repeat the analysis.

This page describes how to report the relevant NICER version information, namely:

  • HEASoft and NICER software versions
  • NICER calibration version
  • Background model version

Prerequisites

Before starting, be sure that you have NICER software and calibration data bases installed and up to date. Please see the Setting Up a NICER Analysis Environment thread for more information

Reporting HEASoft / NICER Software Versions

NICER software is distributed as a part of HEASoft. HEASoft has a reported version number, but NICERDAS does as well. Since they are distributed together, both versions should increase in lockstep.

The correct way to report the HEASoft version number is with the 'ftversion' task ('fversion' is equivalent). ftversion The result is a coded version number. Here is an example. 26Mar2021_V6.29 The actual version number is 6.29, and the date listed is typically the "code freeze" date when software began being prepared for release. However, the numerical portion (6.29 in this example) is the version of HEASoft that is relevant for documentation purposes.

The correct way to report the NICERDAS software version is with the 'nicerversion' task. nicerversion The result is also a coded version number. Here is an example. 2021-04-01_V008 The actual version number is 8 (V008), as in NICERDAS version 8. Similar to the HEASoft version, the date included is a "freeze date" and not necessary to report.

Reporting NICER Calibration Database Version

NICER also distributes separately calibration products via the HEASARC's Calibration Database (CALDB) system. The way to report the calibration version is with the 'nicaldbver' task. nicaldbver The result is a string of the form xtiYYYYMMDD. Here is an example. xti20210707 The calibration database version is the full string, i.e. "xti20210707". Pleae note that the 'nicaldbver' task was released in HEASoft version 6.29. In versions of software before that release, it is possible to determine the CALDB version if you are using "local" CALDB (not remote CALDB) using the 'readlink' command. readlink $CALDB/data/nicer/xti/caldb.indx The result is a file name. Here is an example. index/caldb.indx20210707 The date listed at the end is the NICER CALDB date string. In this example, the 20210707 is the date code that should be reported as xti20210707.

Reporting Background Model Versions

Since NICER is a non-imaging instrument, background must be estimated by more complicated means. NICER uses background models to provide estimates. Background models have been included in HEASoft / NICERDAS for several years.

Because background models can be improved and changed, it is worth reporting versions of background models that you use.

Space Weather. The Space Weather model has not changed since version 1 was released.

3C50. The 3C50 model has different versions, based on its notion of gain solution. Scientists can report the "gain year" in their scientific analysis dicussions. Here we provide a table of versions by gain solution date. Data processed with calibration database older than gain year 2021 are not recommended.

  • 3C50 Gain Year "2021" - CALDB xti20221001
  • 3C50 Gain Year "2022" - CALDB xti20240206

SCORPEON. SCORPEON has version numbering. Version numbers correspond to improvements to background modeling capability and/or adjustment parameters. These versions are specified using the bkgver parameter to the nicerl3-spect or nicerl3-lc tasks. Scientists can report which bkgver setting they used when they processed their data. SCORPEON is designed to allow backprocessing with older versions, but NICERDAS specifies default SCORPEON background versions with each release. Here is a table of the default version.

  • HEASoft 6.31 - 6.32.1 - default bkgver=v22
  • HEASoft 6.33 and higher - default bkgver=v23

Reporting Screening Criteria

In addition to versions of software, users should of course report how they processed their NICER data. This should include any special screening or filtering on the data.

If you use the standard defaults for screening, scientists can report this.

Any non-default parameter settings can be reported as well. Some of these settings include, underonly_range, cor_range, etc.

Modifications

  • 2021-07-16 - initial draft
  • 2022-04-25 - small updates to formatting
  • 2024-02-15 - add discussion of background model versions