HEASARC Staff Scientist Position - Applications are now being accepted for a Staff Scientist with significant experience and interest in the technical aspects of astrophysics research, to work in the High Energy Astrophysics Science Archive Research Center (HEASARC) at NASA Goddard Space Flight Center (GSFC) in Greenbelt, MD. Refer to the AAS Job register for full details.

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-09-25

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.

As of HEASoft 6.34 / NICERDAS 13, the NICER tools append certain metadata kewyords to product files which help identify which model version and settings were used for analysis. The keywords appear in both the background estimates themselves, as well as the final product files such as spectra or light curves. These keywords are listed below.

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

  • NIBKGTYP. The type of background model being used ('SW')
  • SWVERSN. The Space Weather version string.

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
Metadata keywords:
  • NIBKGTYP. The type of background model being used ('3C50').
  • BGYR3C50. The 3C50 model's version string, equivalent to 'gain year'.

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
Metadata keywords:
  • NIBKGTYP. The type of background model being used ('SCORPEON').
  • SCORPVER. The SCORPEON model version number, eg. 'v23'.
  • SCORPVAR. The SCORPEON model variant used, eg. 'nxb-detailed'
  • SCORPCOM. The SCORPEON model background components included, e.g. 'sky,nxb'.

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.

Checking an Event File or Other Product for Version Numbers

You may have existing products created by NICER software and wish to know what software or calibration versions were used to process that file.

NICER product files - cleaned event files, spectra, and light curves - have version tracking FITS keywords that indicate important version numbers. These keywords are updated by nicerl2 every time that you run nicerl2.

Check the CALDBVER and SOFTVER keywords to determine what version of calibration database and software were used to process your product.

Calibration Version (CALDB). NICER's CALDB version can be retrieved by using the following command ftlist myfile.fits+1 K include=CALDBVER where myfile.fits is the name of your event file, light curve or spectrum. The "+1" restricts ftlist to only examine the first data table extension where updated science data is stored. The result will look like this: CALDBVER= 'xti20240206' / NICER CALDB Version This CALDBVER is the same version as described above.

Software Version. NICER's software version can be retrieved by using the following command ftlist myfile.fits+1 K include=SOFTVER where myfile.fits is the name of your event file, light curve or spectrum. The "+1" restricts ftlist to only examine the first data table extension where updated science data is stored. The result will look like this: SOFTVER = 'Hea_22Aug2023_V6.32.1_NICER_2024-02-09_V012' / NICER Software Version The version that is printed contains two portions, joined with an "_" character:

  • Hea_ddMMMYYY_VNNNN - the HEASoft version used, the same as reported by fversion / ftversion as described above
  • NICER_YYYY-MM-DD_VNNN - the NICERDAS version used, the same as reported by nicerversion as described above.

These techniques are not foolproof. If you iteratively process your data, you can arrive at inconsistent keywords. For example, if you run nicerl2 with an older version of NICERDAS, and then run "nicerl2 ... tasks=SCREEN" with a newer version of NICERDAS, then the output products will have SOFTVER version keywords for the newer version of NICERDAS, even though only the screening portion of was applied.

If trackability is important to your application, you should never run NICER tools incrementally on data processed with older versions. Instead, after upgrading to a new version, reprocess your data from scratch with nicerl2.

Important note: these tracking keywords were only reliably applied to products starting with HEASoft 6.30, released March 2022. For data processed with older versions of the software, it is definitely recommended to reprocess your data with a more up-to-date version.

Modifications

  • 2021-07-16 - initial draft
  • 2022-04-25 - small updates to formatting
  • 2024-02-15 - add discussion of background model versions
  • 2024-02-27 - add discussion of CALDBVER and SOFTVER keywords
  • 2024-09-25 - add discussion of background model tracability keywords