NuSTAR Analysis

HEASoft, the FTOOLS and XANADU software package maintained at the HEASARC, is recommended for the analysis of NuSTAR data. The current version of HEASoft (version 6.19, released on May 11, 2016) contains the NuSTAR subpackage (v1.6.0) of tasks - NuSTARDAS - which, together with the existing FTOOLS and XANADU tasks, will enable users to do a complete analysis of NuSTAR datasets, with perhaps a few exceptions.

For more detailed information on NuSTARDAS, see the NuSTAR data analysis software users guide, v1.9.1 (2.2 MB PDF file) and the NuSTAR data analysis quickstart guide, v1.1 (2.3 MB PDF file).

For information on additional, user-contributed NuSTAR software, see here.

For information about selecting background filtering modes, see the NuSTAR FAQ page and this Caltech NuSTAR page.

What's New in the Latest NuSTARDAS Release

Released on May 11th, 2016, NuSTARDAS v1.6.0 was included in the HEASoft 6.19 release. NuSTARDAS v1.6.0 users should make sure to use version 20160502 (or later) of the NuSTAR CALDB. An updated version of the NuSTARDAS users guide (v1.9.0) is also available.

There are two major new features in this version:

1) The module 'nusplitsc' allows the user to generate separate independent output files from the data held in the Mode 06 event files based on each spacecraft star tracker combination, each of which should have reduced blurring and higher fidelity. We note that the absolute position of these images may still be different than the Mode 01 data set and do not recommend using RA/DEC coordinates when extracting produces in these modes without first inspecting the images. See the NuSTAR Observatory guide for more information about nusplitsc.

2) The module nucalcsaa has been optimized with new algorithms to automatically generate GTIs that exclude regions of the orbit that produce enhanced background counts in the detector.

NuSTARDAS v1.6.0 users should either make sure they have version 20160502 (or later) of the NuSTAR CALDB installed locally or that they are using remote access to access the latest NuSTAR CALDB from the HEASARC.

NuSTAR Calibration and Background-Subtraction Information

Documentation with information about the calibration of the NuSTAR observatory is available at Madsen et al. (2015, ApJS, 220, 8). A detailed examination of the components of the NuSTAR background can be found in the appendix of Wik et al. (2014, ApJ, 792, 48), and the software used in the latter reference is available as user-contributed software at the NuSTAR GitHub site.

NuSTAR Analysis Caveats

  • We do not recommend using XSELECT to manually generate high level products (images/spectra/light-curves) from the event files, as there are NuSTAR-specific FTOOLS that are required to accurately reproduce the livetime of the instrument. If XSELECT is used to manually filter event files, the 'nulivetime' FTOOL *must* be run in order to correct the LIVETIME keyword (XSELECT overwrites this keyword during the filtering step). However, we re-iterate that we do not recommend manually filtering data and producing high-level products in this manner as there is a significant risk of introducing some errors. Instead, if GTI filtering is required, we recommend that the users should use XSELECT to generate the GTIs and then use 'nupipeline' and 'nuproducts' with the 'usrgti' keyword to ensure that the high level products are correct.

  • We do not, in general, recommend co-adding data from the two NuSTAR telescopes for spectroscopic analyses. Simultaneously fitting the data from the two telescopes by leaving a floating cross-normalization parameter (e.g. including leading "const" model term in XSPEC) will provide more accurate results. If the "const" for FPMA is frozen to unity, then the "const" value for FPMB is typically between 0.95 and 1.05, depending on how far off-axis the source is in each telescope.

    Co-adding the effective areas of the two NuSTAR instruments without first accounting for the cross-normalization may introduce systematic errors in the model parameters. However, this should only be significant for analysis of high signal-to-noise observations when the systematic errors will be large compared to the statistical errors.

    For analysis of low signal-to-noise observations (e.g. to test for detectability), when the statistical errors will be large compared to systematic errors, or when the user wishes to combine two observations from different epochs for the same telescope, we recommend the following two methods:

    (1) For HEASoft 6.16 and earlier versions without the patch to cmprmf released on 2015/01/23, we recommend using addascaspec to combine the PHA files, background PHA files, and ARFs, and addrmf to combine the RMFs.

    (2) For HEASoft 6.16 with the patch to cmprmf applied and for HEASoft 6.17, we recommend using addspec. This will combine the source and background PHA files as well as the RMFs and ARFs.

  • NuSTARDAS v1.6.0 users should either make sure they have version 20160502 (or later) of the NuSTAR CALDB installed locally or that they are using remote access to access the latest NuSTAR CALDB from the HEASARC.

Other Known NuSTAR Analysis Issues

These will be addressed in a future release of NuSTARDAS and NuSTAR CALDB. The NuSTARDAS module that will be updated is indicated in parentheses ():

  • There is a known issue for processing observations of Sun where the SAA filtering FTOOL (nucalcsaa) causes a crash when using the default parameter values for nupipeline.

    This is caused by a redundant fselect call in nucalcsaa that is run even in the case where "saamode=NONE" and "tentacle=no" (i.e., the default nupipeline parameters). For the solar observations this fselect run can cause a crash for data from FPMB because it applies a strict event screening that artificially vetoes all of the counts. This crash can be avoided by using the following option when calling nupipeline:


    to select all events with GRADE <= 26 (i.e. "science" grade events) or, more simply, with:


    to run the pipeline without any filtering on the GRADE of the event. The NuSTAR team plans to address this issue in the version of nustardas following v1.6.0.

Previous NuSTAR Analysis Issues Which Have Been Fixed

[1] means the issue was fixed in NuSTARDAS v1.3.0 (released with HEASOFT 6.15).

[2] means that the issue was fixed in CALDB release 20131007.

[3] means that the issue was fixed in CALDB release 20131223.

[4] means the issue was fixed in NuSTARDAS v1.3.1 (released with HEASOFT 6.15.1). [5] means the issue was fixed in NuSTARDAS v1.5.1 (released with HEASOFT 6.17.0).

  • An adjustment of the NuSTAR FPM effective areas above 50 keV was needed to correct for the residuals of the W k-edge (69.5 keV) and the Pt k-edge (78.4 keV) in CALDB version 20131007 (and earlier). Analysis of very bright objects may show smooth residual features of order 5 - 15% at energies above 50 keV. This adjustment was included in the NuSTAR CALDB patch 20131223, which was released on January 17, 2014. [3]

  • As of CALDB version 20131007, the NuSTAR clock correction file for use with the FTOOL barycorr is available within the standard HEASARC CALDB releases/patches. It is also available from the NuSTAR SOC website. [2]

  • Bad/hot pixels were only approximately accounted for in the exposure maps. There is now an improved algorithm for inclusion of bad/hot pixels in exposure maps which requires new CALDB files of instrument cumulative probability maps. (nuexpomap) [1]

  • The energy dependence of the vignetting correction to PSF was not taken account of. The corrections for the dependence of the PSF on energy are at most 5%. This correction, performed in 6 energy bands (3-4.5, 4.5-6, 6-8, 8-12, 12-20, 20-79 keV), required new CALDB PSF files. (numkarf) [1]

  • There was a processor memory issue handling temporary FITS files in the extended source case when using a small value of the input parameter 'boxsize'.This was fixed. (numkarf) [1]

  • A correction for energy-dependent PSF losses in lightcurve file generation required using new CALDB PSF files. (nulccorr) [1]

  • Adjustment of the NuSTAR FPM effective areas by +15% placed NuSTAR measured fluxes between Swift and XMM measurements based on simultaneous observations of calibration targets in 2012. [2]

  • The value of the DEADC FITS keyword affected how lightcurves are displayed. The "DEADC" FITS header keyword in the NuSTAR lightcurve files (produced by nuproducts/nupipeline) contains the average livetime fraction over the course of the observation (i.e. the livetime integrated over GTIs divided by the "real" seconds integrated over the GTIs). Some standard tools for plotting lightcurves (i.e. the "lcurve" FTOOL) read the DEADC FITS header keyword value and apply this value to the displayed lightcurve. However, the nulccorr FTOOL in NuSTARDAS v1.3.0 (and previous versions) applied a deadtime correction to each individual bin in the lightcurve. Thus using lcurve to display a NuSTAR lightcurve which has been corrected by nulccorr (as is the default for nupipeline/nuproducts) resulted in a "double counted" deadtime correction in the displayed lightcurve, and as a result over-estimated the source flux in each bin. In the meantime users can work around this by either a) setting the DEADC keyword values to 1.0 in the the NuSTAR lightcurve file before using lcurve or b) using the DEADC value to rescale the lightcurve displayed in lcurve. For example:
    % lcurve 1 [1] rescale=0.92
    where is a lightcurve file generated by nuproducts (with the parameter correctlc="yes") and 0.92 is the value of the DEADC keyword in [4]
  • The pilow/pihigh input parameters in nupipeline/nuproducts define the energy band over which the lightcurve is produced but as of NuSTARDAS v1.3.0 were not applied to images or spectra. The plan is to update nupipeline and nuproducts to use the pilow/pihigh keywords for image generation also so that nuproducts/nupipeline can be used to produce images as well as lightcurves in the specified energy band. For users with NuSTARDAS v1.3.0 installed (distributed as part of the heasoft-6.15 release) we recommend using the " extractor" FTOOL or XSELECT to generate images over a given energy band. [4]

  • The PIXBIN and PERC values were missing from the exposure map FITS header. The PIXBIN and PERC parameters drive the performance of nuexpomap and should have been included in the FITS header for self-documentation purposes. [4]

  • NuSTARDAS v1.4.1 (released as part of HEASOFT 6.16) is not compatible with NuSTAR CALDB version 20131223. In particular, nupipeline will fail when trying to process data with NuSTARDAS v1.4.1 and version 20131223 of the NuSTAR caldb. NuSTARDAS v1.4.1 users should either make sure they have version 20140414 of the NuSTAR CALDB installed locally or that they are using remote access to access the latest NuSTAR CALDB from the HEASARC. [5]

Notes for Specific NuSTAR Datasets

As of the date of the 3rd NuSTAR data release on February 5th, 2014, the notes for specific NuSTAR ObsID's that used to be found on this page are now captured in several parameter for those ObsIDs in the NUMASTER table. Potentially problematical issues are indicated by the parameter issue_flag in the NUMASTER table having a value set to 1. The specific nature of the issue affecting the observation will be indicated in one or more non-blank or non-zero values of the following parameters in NUMASTER: data_gap, nupsdout or solar_activity. In addition, the coordinated parameter in NUMASTER lists observatories for which coordinated observations were made with the specified NuSTAR observation. The comments parameter in NUMASTER contains a brief text synopsis of the major known issues and unusual features.