SCORPEON Background Model Versions and Variants

Overview

The SCORPEON background model has been updated over time with improved capabilities. This page discusses how SCORPEON handles versioning and variants.

Read this thread if you want to: Understand SCORPEON versions and variants

Last update: 2024-02-15

Introduction

SCORPEON provides a way to estimate NICER backgrounds. Like any software and calibration effort, the NICER team improves SCORPEON over time. These improvements provide more capabilities or adjustable parameters. This page provides a discussion of how SCORPEON handles versioning, and what versions are available.

It is important for scientific analysis to repeatable and documentable, and NICER is no exception. Keeping track of which software, calibration and background versions you use will aid future scientists in understanding how NICER data were processed. For a more in-depth discussion of how this is can be done for all aspects of NICER analysis, please see the Reporting versions page.

SCORPEON also maintains the concept of "variants" of models. These variants may provide added detail or additional parameters to the model, while not actually changing the construction of the model. Variants are discussed in later sections.

Help! I See New Parameters in My SCORPEON Model That Weren't There Before

The NICER team is committed to providing new and updated background models as they become available. When this occurs, the default value of bkgver is incremented to the newly-available model version.

If users perform their analysis with all standard defaults, and upgrade to a new version of the software, they may find that a new background model has been used instead of the older one that they were expecting.

In this case, the users have a choice. They can:

• Proceed with the new background model, understanding that they may obtain different results, or have to adapt their XSPEC scripts.
• Request an older background model be used instead. For example, for spectral products with nicerl3-spect, run nicerl3-spect ... bkgver=vNN where vNN is the older version.

The disadvantage of using an older model is that it may not be as accurate, or as capable of dealing with NICER configuration changes.

SCORPEON background model files are fully self-contained. Even if new software becomes available, old background .xcm files will continue to work in XSPEC without change. However, you should not attempt to "mix-and-match" between different versions since parameters may be different.

Overview of SCORPEON Background Model Versions

SCORPEON background models are tagged with a version string, also known as the "bkgver". This string is a "v" followed by an integer number. For example, v23 corresponds to SCORPEON version 23. For reporting purposes, one can simply indicate that SCORPEON model "v23" was used for background estimation.

All SCORPEON-related tasks accept a bkgver parameter which indicates which background model version to use. In addition, the high level product scripts such as nicerl3-spect and nicerl3-lc accept the same parameter. While these tasks have a default bkgver value, you are permitted to specify a different version if you wish.

It is the NICER team's intent to permit specifying older SCORPEON background versions, even if newer versions of the model become available, by using the bkgver parameter to any of the tasks. In this way, it should be possible to reproduce older or published results.

However, it is conceivable that some future software library or operating system changes make older background models incompatible in some way. Also, it is conceivable that configuration changes to the NICER hardware (for example, in response to the optical light leak of May 2023) may render older models obsolete for newer data.

For these reasons, the NICER team cannot guarantee complete backward compatibility for older/obsolete SCORPEON background models.

The NICER team indicates a change in capability or parameters for a model by incrementing the version number. If SCORPEON software execution bugs are fixed, or if new output formats are added (for example, light curves in addition to spectra), but the background model's behavior remains the same, then the version number is not incremented. Thus, the bkgver version string tracks the capabilities and accuracy of the model, rather than the version of software that is used.

NICER tracks SCORPEON background versions, which can be specified to any SCORPEON-aware task with the bkgver parameter. This version is incremented when model capabilities or accuracy is changed.

Available SCORPEON Versions

The SCORPEON tasks support working with different versions of the SCORPEON model. This facilitates reproducibility of scientific analysis for older works that may have been analyzed with earlier model versions. It is also possible to load different versions of background model for comparison purposes. The available released background versions are:

• v22 - First SCORPEON background model release, which handles the following background components:
  • nxb - Non-X-ray background, including terms for constant background (CON), cosmic-rays (COR), SAA, and trapped (TREL), low-energy (LEEL) and precipitating (PREL) electrons (default model 99:nxb)
  • noise - model of the NICER noise peak (default model 99:nxb)
  • sky - astrophysical sky backgrounds, including terms for cosmic X-ray background (CXB), galactic halo, local hot bubble (LHB) (default model 98:sky)
  • swcx - geo- and helio-related lines, including solar wind charge exchange (SWCX) from O VII, O VIII, and Ne IX, as well as neutral oxygen from the earth's polar cusp regions (default model 98:sky)
• v23 - SCORPEON background model release available with HEASOFT 6.33 / NICERDAS 12. Overall this version has the same components as v22 (see above). However, it has the following changes. Some of these changes are designed to help deal with the effects of the optical light leak that developed in May 2023.
  • nxb - Includes a new parameter thresh_offset, which shifts the low energy threshold by the requested amount. This parameter is used for data taken after the optical light leak during orbit day, when the lower energy threshold setting is raised.
    
    Two more parameters, prel_hiindoff and prel_hicutoff, are only available when using the "detailed" variant, and provide more control when fitting data with strong precipitating electron ("PREL") flares.

SCORPEON versions that predate v22 were for internal testing and development and not public.

Overview of SCORPEON Variants

SCORPEON also allows variants of background models.

Unlike a background version, a variant of a model is a different view of that model, without changing its fundamental character.

You may select such variants using the bkgvariant=NAME parameter, for example bkgvariant=detailed.

The "detailed" variant provides addiitional detailed parameters for some model components. The actual spectral shape and normalization of the detailed variant is the same as the default variant, but the detailed variant provides additional parameters that are adjustable in the case of special circumstances. Currently, only the NXB model component has a detailed variant, which provides additional normalization adjustment factors for sub-components such as COR and SAA, as well as normalization adjustment factors for the strong background lines.

Currently the only supported variant is for the nxb component (non-X-ray background). This variant supplies additional parameters to allow a higher fidelity fit to bright backgrounds, or spectra with very high statistics. Most users will not need the detailed variant.

A planned "sf" variant provides background models tailored to NICER's SLOW+FAST data mode. This mode consists of only events that have both slow and fast pulse heights, which automatically implies energies above about 0.6 keV. A threshold at 0.572 keV is applied to the background model. The total background for SLOW+FAST events may be lower than the default mode.

How Do I Know Whether I Should Use a Variant?

You mask as yourself, how should I decide whether to use a variant or not? This is not an easy question to answer, but the basic answer is that for very high backgrounds or very long exposures with high statistics, the accuracy of the SCORPEON model may break down to some extent. The variants may provide a way to improve the accuracy without changing the nature of the model

As noted above, the only variant currently available is the "detailed" variant of the "nxb" component. This variant provides additional control over some of the features in the model. Specifically,

• Fluorescent line norms - if you see under- or over- subtraction features in your residuals around fluorescent lines at Al K (alk_corr), Si K (sik_corr), Au M (aum_corr), Ni K (nik_corr), or the Au L complex (aula_corr, aulb_corr, aulg_corr), you can free the corresponding XXXX_corr value.
• Unaccounted line broadening - for any of the line features, if the residuals indicate broader features, free the "sigma" parameter. This sigma value (in keV) is added in quadrature to the sigma of all line features.
• Slow-only norms for SAA or COR - for expert use only. To be adjusted if the slow-only range of 0.25-0.9 keV shows poor subtraction.
• PREL shape - (v23 or later) if your data have strong PREL flares, they may not be subtracted well at high energies. This is because the spectrum of precipitating electrons is highly variable from one moment and geographic location to the next. The prel_hiindoff and prel_hicutoff parameters can be thawed to allow adjustment of the high energy behavior of the background curve (> 6 keV).

Modifications

• 2024-02-15 - initial draft