NuSTAR Frequently Asked Questions


Newly added or modified questions and answers are indicated by the **NEW** or **UPDATED** annotation.

    General

  1. Where can I get help if I have questions about NuSTAR data, software, archive, or other mission-related issues which are not addressed below?

    All such questions should be addressed to the HEASARC Help Desk, where you should select "NuSTAR" as the mailing list. The HEASARC will forward questions needing project expertise to the NuSTAR Project at Caltech.

  2. How can I find out which targets either have already been or are to be observed by NuSTAR?

  3. How can I find out which targets NuSTAR is currently observing or is shortly about to observe?
    Proposals

  4. Where can I find out about the NuSTAR Guest Observer (GO) Program?

  5. Can NuSTAR perform ToOs (target of opportunity observations)?

  6. How do I simulate a NuSTAR spectrum for a source, including background?
    Anonymous Proposals

  7. Where do I find instructions for writing proposals for dual-anonymous review?

  8. How is the team expertise document used?

  9. How do I reference unpublished work? How do I reference proprietary results?

  10. How do I address an unobserved category C target accepted for the previous cycle when reproposing?
    Archive and Documentation

  11. When and where will NuSTAR datasets become publicly available?**UPDATED**

  12. Which NuSTAR datasets were initially released?

  13. Once data are publicly available, what is the best way to search for them in the HEASARC Archive?

  14. Where can I find documentation for analyzing NuSTAR data?
    Analysis Software and Calibration

  15. Which software should be used to analyze NuSTAR data?

  16. How can I access NuSTAR calibration data?

  17. Where can I obtain an updated NuSTAR clock correction calibration file?

  18. How do I obtain barycenter corrected event files from the NuSTARDAS?

  19. How do I create products based on user-defined barycenter-corrected GTI files (i.e. for phase-resolved spectroscopy of pulsars)

  20. Does NuSTAR have an on-board calibration source to monitor gain variations?

  21. What do I need to know about the NuSTAR gain calibration?**NEW**

  22. Why is the NuSTAR pipeline so slow? Why does the NuSTAR pipeline not work when my network is down?

  23. How do I use the clock correction file to obtain the highest accuracy event timing?

  24. What do I do if the ISSUE flag is set to 1?**NEW**
    Analysis Issues

  25. Why does stage 1 of the pipeline processing fail when analyzing my observation taken after March 16th, 2020?

  26. Are the FPMA and FPMB telescopes sufficiently coaligned that I can use the same spatial extraction region for my source in both?

  27. Is it ever OK to co-add NuSTAR spectra?

  28. How can I get rid of a "Found more than one TLE" error when running nupipeline?

  29. In the data set that I am analyzing, I can see a lot of spikes in the power spectrum at multiples of 1 Hz. What's happening?

  30. What are the preferred region types to use when extracting a source?

  31. What other region types can be used when extracting a source?

  32. Will there be support for combining two regions, e.g., subtracting two circles to represent an ellipse?

  33. How can I recover exposure time lost when the metrology system is out of the calibrated range?

  34. On what time scales does nulccorr apply the livetime corrections?

  35. I want to construct a light curve in a limited energy range but the software needs the PI channel range ('pilow' and 'pihigh'): what is the conversion from PI channel to energy?

  36. What do I need to know about the NuSTAR background?**NEW**

  37. Why do I need to use an SAA filter?**UPDATED**

  38. What SAA filtering mode should I use?

  39. What do I do if I have a bright source?

  40. Do I have to worry about pile-up if I have a bright source

  41. How do I split up my observation?

  42. Why does the spectrum of my bright source appear significantly different in FPMA and FPMB below 8 keV?

  43. Why does the count rate in a light curve generated via nuproducts differ by up to a few factors from the count rate obtained from the spectrum in XSPEC using the same extracting region for the same energy band?

  44. Why do I see an "RMF DETNAM" warning in XSPEC?**NEW**
    Miscellaneous

  45. Why are the public dates missing for some ObservationID's in the NUMASTER table?

  46. What is the significance of null values for RA and Dec in the NUMASTER table?

  47. Why is there zero exposure time in an ObservationID when the X-ray instrumentation on NuSTAR is never turned off?

  48. How can I relate roll angle (the roll_angle parameter in NUMASTER) to a position angle on the sky?

  49. What is the significance of the NuSTAR Observation ID (called ObsID in the NUMASTER table)?

  50. Why do most targets have two Obs(ervation)ID's?

  51. How are the NuSTAR file names constructed?

  52. Why am I unable to download files from HEASARC?

  53. Why is the NORAD catalog number in the TLE files different from the USSPACECOM catalog number?

  54. What text is appropriate to acknowledge the use of NuSTAR data and NuSTARDAS in research papers?**NEW**

Answers to NuSTAR Frequently Asked Questions


  1. Q: Where can I get help if I have questions about NuSTAR data, software, archive, or other mission-related issues?

    A: All such questions should be addressed to the HEASARC Help Desk, where you should select "NuSTAR" as the mailing list. The HEASARC will forward questions needing project expertise to the NuSTAR Project at Caltech.


  2. Q: How can I find out which targets either have already been or are to be observed by NuSTAR?

    A: The list of all targets, both observed and to be observed, comprising the current NuSTAR target list (including targets from both the primary science mission team and from Guest Observers) is now fully incorporated into the HEASARC's NUMASTER table. The NUMASTER table will be regularly updated as the observations of targets are completed and as previously unanticipated ToOs are performed.


  3. Q: How can I find out which targets NuSTAR is currently observing or is shortly about to observe?

    A: This information is available as the NUAFTL table on the HEASARC site, and on the NuSTAR Science Operations Center (SOC) website at Caltech: the latter hosts the NuSTAR short- and long-range observing schedules.


  4. Where can I find out about the NuSTAR Guest Observer (GO) Program?

    A: In mid-2014, the NuSTAR Project received an extension of the mission, including the institution of a Guest Observer (GO) Program, based on its proposal to the NASA Astrophysics Senior Review of Operational Missions. A first call for proposals from the community was issued on August 26th, 2014 as a new component of ROSES-2014 The NuSTAR GO Cycle 1 proposal due date is November 25th, 2014, with GO observations starting near the beginning of April 2015. Further details on this (and other) opportunities to propose for NuSTAR observations can be found here.


  5. Can NuSTAR perform ToOs (target of opportunity observations)?

    During the baseline mission and Cycle 1 of the NuSTAR Guest Observer program, ToOs from the community were accepted only for exceptional events and had to be submitted using the NuSTAR ToO website at Caltech. As of Cycle 2 of the NuSTAR Guest Observer program, ToOs can also be submitted as GO proposals. For more details on NuSTAR's ToO policy, see this page.


  6. How do I simulate a NuSTAR spectrum for a source, including background?

    A: Simulated NuSTAR spectra can be generated in XSPEC using the "fakeit" command. First you should download the appropriate response, effective area and background files (which can be downloaded from here). You should then read the background file in as both an XSPEC data file and as the background file, in order to ensure that the BACKSCAL value in the output spectrum is correct. For example:

    % xspec
    XSPEC12> data nustar_80pct_bkg.fits
    XSPEC12> back nustar_80pct_bkg.fits
    XSPEC12> resp nustar_rmf.rmf
    XSPEC12> arf nustar_80pct.arf
    XSPEC12> model whatever
    XSPEC12> fakeit
    
    Note that it is important that the "fakeit" command is used (and not "fakeit none" command).

    To use the provided NuSTAR ARF in ISIS the intrinsic variable Remove_Spectrum_Gaps has to be set to 1 before loading the ARF. We also note that ISIS assumes a background scaling factor of 1 for simulated spectra, therefore the BACKSCAL keyword in the provided background files needs to be set to 1 to have them scaled correctly.


  7. Q: Where do I find instructions for writing proposals for dual-anonymous review?

    A: Starting with Cycle 6 NuSTAR General Observer proposals are selected through dual-anonymous peer review. This means that proposals should eliminate language that identifies the proposers or institution. For more information see the
    Guide to NuSTAR Proposers and in particular the Guidelines for Anonymous Proposals.

  8. Q: How is the team expertise document used?

    A: PIs are required to upload a one-page "Team Expertise" PDF through ARK as a separate upload when submitting the science justification. A LaTeX template and a Word template are available.

    This document will be distributed to the review panel after all proposals have been reviewed and rated, only for programs which are in the selectable range. This is to allow the reviewers to assess the team capabilities required to execute a given proposed science investigation. If there are clear, compelling deficiencies in the expertise required to see through the goals of the proposal, the panel may decide to flag the submission accordingly, and provide a detailed justification in its comments to NASA. This review may not be used to flag "up" proposals for having strong team qualifications, nor may it be used to re-evaluate or upgrade proposals.


  9. Q: How do I reference unpublished work? How do I reference proprietary results?

    A: References to published work are encouraged, including work citable by a Digital Object Identifier (DOI).

    Unpublished work that is based on public data sets or public software can be referenced as work "by the proposal team", without identifying the PI or CoIs by name.

    It may be occasionally important to cite exclusive access datasets or non-public software that may reveal (or strongly imply) the investigators on the proposal. It is suggested proposers use language like "obtained in private communication" or "from private consultation" when referring to such potentially revealing work, again without identifying anyone by name.


  10. Q: How do I address an unobserved category C target accepted for the previous cycle when reproposing?

    A: Category C proposals are not carried over into the next cycle. The the time of the proposal deadline a PI of an approved category C observation might not know if the observation will be performed before the end of the current cycle and might want to repropose the same observation for the new cycle in case it will not be observed in the current cycle.

    The previously approved category C observation does not need to be mentioned in the new proposal. The target list is public and such a case will get highlighted in the technical report for the reviewers. You are, however, free to acknowledge that the target is in the public list of accepted targets with category C, without saying that it is from your proposing team.

    If the observation is performed before the start of the new cycle, it will generally not be duplicated, i.e., no observation of the target based on the same science case will be performed.

    For further clarification it is recommended to discuss in the team expertise document (see 2., above) that this is a resubmission of an accepted C target from the current cycle and to explicitly state that the observation in the new cycle is only requested if the C target of the current cycle is not observed.


  11. Q: When and where will NuSTAR datasets become publicly available?

    A:

    (1) Observations which are part of the NuSTAR Guest Observer Program become public 6 months after their receipt by the proposal's Principal Investigator (PI) unless the PI waived exclusive use (= data public immediately) or requested and was granted extended exclusive use (= data public after one year).

    (2) Observations made under the aegis of another mission's Guest Observer Program which also awarded NuSTAR observing time become public at the same time as the exclusive-use period for that other mission's data expires.

    (3) All other observations, i.e., those not performed for any NuSTAR general observer program, are made available in the NuSTAR public archive and have no exclusive-use period. This includes observations performed for calibration, directors discretionary time, and any remaining legacy program targets. The only exception will be observations with significant quality issues which may have their release delayed until the NuSTAR SOC determines the impact on science analysis.


  12. Q: Which NuSTAR datasets were initially released?

    A: The first NuSTAR data release on August 29, 2013 contained observations of celestial calibration targets placed both on-axis and at a range of off-axis angles. The targets were a sample of AGN and X-ray binaries, all of them being point sources. See the next question and answer for how to identify the specific observations which went public.


  13. Q: Once data are publicly available, what is the best way to search for them in the HEASARC Archive?

    A: The HEASARC has created a table in its database systems Browse and Xamin (both available from the main HEASARC Archive page) called NUMASTER, which lists all observations made by NuSTAR which have been processed by the NuSTAR SOC. Some of these datasets will be 'public', some will still be proprietary (and encrypted), as indicated by either a null value or a date in the future for the public_date parameter in the NUMASTER table. Users can query this table and download the data associated with the selected observation(s) using the usual Browse/Xamin procedures. For example, this Browse query lists all currently public NuSTAR data. For those interested in writing a ROSES-2014 Astrophysics Data Analysis Program proposal using NuSTAR archival data, any or all of these data sets can be referred to in such a proposal. Finally, for the expert user, the NuSTAR data are also directly accessible in the HEASARC's ftp area.


  14. Q: Where can I find documentation for analyzing NuSTAR data?

    A: On the HEASARC NuSTAR data analysis page. The primary reference for the NuSTAR mission is the article by Harrison, F.A. et al. (2013) ApJ, 770, 103 (2.9 MB PDF file) which contains information about the observatory and science instrument, the baseline science program, and the in-flight performance.


  15. Q: Which software should be used to analyze NuSTAR data?

    A: HEASoft, the FTOOLS and XANADU software package maintained at the HEASARC. The version (6.16) of HEASoft that was released on July 2, 2014 contains a NuSTAR subpackage of tasks (nustardas) which, together with the existing FTOOLS and XANADU tasks, will enable users to do a complete analysis of NuSTAR datasets. See the NuSTAR data analysis software users guide (1.3 MB PDF file) and the See the NuSTAR analysis quickstart guide (2.3 MB PDF file for more detailed information.


  16. Q: How can I access NuSTAR calibration data?

    A: NuSTAR calibration data are part of the HEASARC CALDB, and can be accessed using the normal CALDB access procedures. See the HEASARC CALDB site for general instructions and the NuSTAR CALDB page for mission-specific information.


  17. Q: Where can I obtain an updated NuSTAR clock correction calibration file?

    A: The timing of recorded events in the NuSTAR instrument can drift depending on changing thermal conditions within the spacecraft. Clock offsets from GPS values are measured during each ground station contact and are nominally adjusted if the offsets are larger than +/- 10 msec, but clock offset errors can be as large as 100 msec. Science users who require event timing more precise than this are encouraged to use a clock correction calibration file. After applying the clock offset correction, clock offset errors are nominally less than 100 μsec and relative timing accuracy may be possible to better than 60 μsec.

    The clock correction file has been formatted to be compatible with the HEASARC's barycorr multi-mission tool for applying barycenter corrections to X-ray timing data and with NuSTARDAS. NuSTAR CALDB updates to the clock correction file occur bi-weekly as the mission progresses, so the most recent clock calibration file can be obtained from the CALDB page. Information on how to use the clock correction file can be found on the NuSTAR SOC website.


  18. Q:How do I obtain barycenter corrected event files from the NuSTARDAS?

    A: There are two main methods to produce a barycenter corrected NuSTAR event file.

    (1) Use the barycorr FTOOL. Please see the documentation for barycorr on its use and syntax.

    (2) Use nuproducts (which in turn calls barycorr).

    When the barycorr-related keywords are set (i.e., barycorr=yes,srcra_barycorr,srcdec_barycorr etc, please refer to the nuproducts help page.) then nuproducts will deliver barycenter corrected products based on the location of the source provided via the srcra_barycorr and srcdec_barycorr keywords. However, the event file in the event_cl directory will not contain barycenter corrected times. The barycetner corrected event file is produced as a temporary file when lightcurves are constructed and then automatically delete by default. The barycenter corrected cleaned event file can be saved in the output directory by setting the keyword "cleanup=no". This file can then be used to define GTI files in the barycentered times (i.e. for phase-resolved spectroscopy of pulsars).


  19. Q: How do I create products based on user-defined barycenter-corrected GTI files (i.e. for phase-resolved spectroscopy of pulsars)?

    A: Use the "usrgtifile" keyword, but set the "usrgtibarycorr=no" keyword to prevent nuproducts from applying a second barycentric correction to the input GTI files.


  20. Q: Does NuSTAR have an on-board calibration source to monitor gain variations?

    A: Yes, NuSTAR has on-board 155Eu radioactive calibration sources on arms that can deploy into the light-path for FPMA and FPMB. They have only been deployed once on orbit (2012 June 24-25th). The original plan was to deploy them ~1/year to track changes in gain and spectral response. However there is a risk that the deployment arms could become stuck when deployed and so there are currently (August 2013) no plans for future deployments. Changes in the calibration of the instrument are sufficiently tracked with the large number of repeat observations of celestial sources during the mission.


  21. Q: What do I need to know about the NuSTAR gain calibration?

    A: For an overview see the report "Measuring the Evolution of the NuSTAR Detector Gains" (intended as a "living document").


  22. Q: Why is the NuSTAR pipeline so slow? Why does the NuSTAR pipeline not work when my network is down?

    A: If you have set up Remote Access CALDB then you will need network access while running the pipeline. Some of the calibration files are quite large (100s of megabytes), and will take significant time to download if your internet connection is not fast. We recommend to download the NuSTAR CALDB locally to improve processing speed.


  23. Q: How do I use the clock correction file to obtain the highest accuracy event timing?

    A: The clock correction file keeps the NuSTAR relative time (after barycentric corrections) accurate to better than 100 μs and accounts for drifts in the NuSTAR clock caused by temperature variations. An updated clock correction file is produced each week as the mission continues and is available from the NuSTAR CALDB page. The nu.attorb file is produced by Stage 1 of nupipeline and is found in the output directory (usually event_cl) along with the orig.evt file. It has the format nuXXXXXXXXXXXA.attorb where the X's are the sequence ID. For example, the observation of 3C 273 with sequenceID 10502620002 would use (for FPMA):

    barycorr infile=nu10502620002A01_cl.evt outfile=bary.evt orbitfiles=nu10502620002A.attorb clockfile=nuCclock20100101v100.fits ra=187.2779 dec=2.9525


  24. Q: What do I do if the ISSUE flag is set to 1?

    A: The COMMENTS field in the numaster table is populated with a description of why the ISSUE flag was set, most often due to solar activity or data gaps. However, the science impact of issues can often be complex and related to the analysis of an observation. If a user is in doubt as to why the ISSUE flag is set, or would like guidance on whether or not additional processing is required for the data, the user should contact the NuSTAR Helpdesk to request clarification.


  25. Q: Why does stage 1 of the pipeline processing fail when analyzing my observation taken after March 16th, 2020?

    A: An adjustment of the onboard laser metrology system (which tracks the relative motion of the NuSTAR optics bench and the focal plane bench) was performed on March 17th, 2020 to improve the longevity of the laser metrology system. Analysis of any observation taken after March 16th, 2020 will require NuSTARDAS version 1.9.2 (or later), released in HEASoft v6.27.1. The software update is transparent to the user requiring no syntax changes when calling Stage 1 of nupipeline. There is no change to the quality of the science data.


  26. Q: Are the FPMA and FPMB telescopes sufficiently coaligned that I can use the same spatial extraction region for my source in both?

    A: No, you should define separate extraction regions for each telescope. We typically observe a relative astrometric offset of 5-10" offset between the images from the two NuSTAR telescopes. The exact value of this relative offset drifts with time and the illumination of NuSTAR by the Sun. We also do not expect that the center of the extraction region will correspond exactly to the J2000 coordinates of the source since the typical absolute astrometric uncertainty is +/- 8". This can be mitigated if there are sources with a known J2000 position in the field of view that can be used to register the image.


  27. Q: Is it ever OK to co-add NuSTAR spectra?

    A: 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 all later HEASoft versions, we recommend using addspec which will combine the source and background PHA files as well as the RMFs and ARFs.


  28. Q: How can I get rid of a "Found more than one TLE" error when running nupipeline?

    A: This is caused by having multiple files in the "auxil" subdirectory of the format NUSTAR_TLE_ARCHIVE.*.

    This is usually the result of leaving behind the encrypted files when using the decrypt_data.pl script. We recommend using the "-r" option to remove the encrypted files after they have been decrypted. However, if you have already decrypted your data, you can fix this problem by simply removing the "NUSTAR_TLE_ARCHIVE*.gpg" file from the "auxil" subdirectory. You can then run the pipeline as usual.

    If you do have more than one TLE archive file (which can happen in rare cases), you may delete the older of the two TLE archives. The file-naming convention for these files uses a suffix of .YYYYDOY, where DOY stands for day of year. Thus, for example, NUSTAR_TLE_ARCHIVE.txt.2015105 is more up-to-date than NUSTAR_TLE_ARCHIVE.txt.2015082, and the latter can be safely deleted. Once you have removed the extra TLE files, nupipeline should run without crashing.


  29. Q: In the data set that I am analyzing, I can see a lot of spikes in the power spectrum at multiples of 1 Hz. What's happening?

    A: The NuSTAR flight software performs housekeeping operations every second, which results in short periods when the instrument cannot acquire photons (deadtime). In the early observations (prior to August 2012), the flight software performed these housekeeping operations at the same phase of every second, producing small "dips" every second. For bright sources, this can be detected in the power spectrum as peaks at 1 Hz (and multiples of 1 Hz). Additional peaks might appear at 0.25 and 0.50 Hz, due to other housekeeping operations. After this problem was detected, the phase of the second when the housekeeping operations are performed was randomized, which eliminated the spikes from the power spectrum, since the small gaps were no longer coherent. Observations from August 2012 on should not be affected by this issue.


  30. Q: What are the preferred region types to use when extracting a source?

    A: Any ds9 region file can be used to extract source spectra and lightcurves. However, ARF corrections and light-curve PSF corrections can only be applied when the appropriate region types are used. For point source extractions the user should use a 'Circle' ds9 region with the standard ARF generation flags. For extended sources arbitrary source extraction regions can be used.


  31. What other region types can be used when extracting a source?

    A: For point source extractions, the software currently supports ds9 circles, annuli, and ellipses. However, ghost rays are currently only supported for circular regions. Any geometry can be used to extract counts from extended sources. While the ARF and lightcurve corrections are applied in this case, ghost ray corrections are not applied to extended sources.


  32. Q: Will there be support for combining two regions, e.g., subtracting two circles to represent an ellipse?

    A: Additional combinations may be implemented in future releases of the NuSTARDAS package.


  33. Q: How can I recover exposure time lost when the metrology system is out of the calibrated range?

    A: The motion of the NuSTAR optics relative to the detectors is measured by a metrology system that consists of two lasers positioned on the optics bench pointing back along the 10m mast to position sensing detectors (PDS's) on the focal plane bench. The system is designed to register the motion of the focal point of the optics and for most observations the travel is of order a few mm on the detectors which translates to < 1 arcmin in the sky frame. The processing of metrology data within the NuSTARDAS module 'numetrology' corrects for distortions introduced by the response of the PSD0s. In sporadic cases the laser spots fall outside this calibrated range and the corresponding time intervals are filtered out during the data screening.

    The value of the exposure time (not livetime corrected) lost because of the laser spots outside the calibrated range is reported in a specific keyword of the cleaned Level 2 event files named 'NUPSDOUT'. For example see the observation of Her X-1 on 2012-11-19 (obsID 30001030002).

    To recover the lost exposure time, at the expense of some positional uncertainty, a specific 'nupipeline' input parameter named 'psdcal' allows use of the raw coordinates of the laser spots without applying the distortion correction. This procedure is safe for the analysis of bright sources, however users must check the sky images to verify the accuracy of the reconstruction of celestial positions.

    For details see the NuSTAR Data Analysis Software guide, sections 3.2 and 6.3.


  34. Q: On what time scales does nulccorr apply the livetime corrections?

    The NuSTARDAS applies livetime corrections to each lightcurve bin via the "nulccorr" FTOOL, which is automatically called by nupipeline/nuproducts when extracting lightcurves if the parameter "correctlc" is set to "yes" (the default). The lightcurve bin width is set via the hidden "binsize" parameter when calling nupipeline/nuproducts (the default binsize value is 10 seconds). It is assumed that the user has selected an appropriate lightcurve bin size for the source.

    The NuSTAR focal plane modules have a rate-dependent livetime (see the Userss Guide). To correct a lightcurve for this, the "nulccorr" FTOOL reads the instrument livetime (recorded at a 1 Hz cadence in the instrument housekeeping FITS files), integrates the livetime over each lightcurve bin, and then applies the livetime correction to that bin.

    For example: If a lightcurve is binned to 100-seconds, then the livetime is integrated over each 100-second bin and used to correct the lightcurve rate. If a source has variability on 10-second timescales the user should use 10-second (or smaller) bins, not 100-second bins.


  35. Q: I want to construct a light curve in a limited energy range but the software needs the PI channel range ('pilow' and 'pihigh'): what is the conversion from PI channel to energy?

    A: The channel to energy conversion is linear: E = Channel Number * 0.04 keV + 1.6 keV (lower energy range of bin) Channel 0 corresponds to 1.60-1.64 keV, channel 1 corresponds to 1.64-1.68 keV, etc. You can also check the ebounds extension of RMF files (with the 'fv' command) to confirm the relationship between PI value and energy.


  36. Q: What do I need to know about the NuSTAR background?

    A: For an overview see the 2022 IACHEC presentation "The NuSTAR Background -- Origins, Mitgation, Modeling".


  37. Q: Why do I need to use an SAA filter?

    A: There are regions of the NuSTAR orbit in which satellite flies through the Earth's radiation belts. The charged particles interact in the detector and the anti-coincidence CsI shield, resulting in an enhanced background in the detectors. The most famous example is the South Atlantic Anomaly (SAA), where NuSTAR flies directly through a region of the inner Van Allen belts and particle-induced triggers dominate the NuSTAR telemetry. The impact of the SAA on NuSTAR background event rates is primarily between ~300 and ~330 degrees longitude and < +1.5 degrees latitude, while the "tentacle" region is around ~270 degrees longitude and above about -2 degrees latitude. The strength and size of the SAA and the strength of the background in the tentacle region both depend on the space weather conditions at the time of the observation.

    The on-board computer samples the rate of particle hits in the anti-coincidence shield and turns off telemetry from the NuSTAR detectors when the particle background is too high (i.e., a "hardware" trigger).

    The instrument team is conservative in setting the threshold for turning off the detector telemetry and so there are periods of enhanced background as NuSTAR enters/exits the SAA. In addition there may be an enhanced background when NuSTAR flies through a short-lived radiation belt just to the East of the SAA (the "tentacle"). For bright sources the effect of the enhanced background can be negligible, while for fainter sources or sources that are sensitive to varying background levels, additional filtering of an observation may be required.

    This filtering is built into the NUSTARDAS nupipeline via the nucalcsaa FTOOL, which has a variety of user settings*. To assist the user in determining the optimal settings to use, the NuSTAR SOC generates a report for every observation that demonstrates the effect of various nucalcsaa settings. These reports can be accessed for all observations via the NuSTAR webpage at: http://www.nustar.caltech.edu/page/background.

    It is possible that even for faint sources no filtering may be required; the tentacle region specifically is highly dependent on the space weather conditions during the observation. The user should always check the observation report to see if enhanced background is important for a given observation.

    *See the HEASARC NuSTAR Analysis page for the NUSTARDAS software users guide, the NuSTAR observatory guide, and more details about NuSTAR data analysis.


  38. Q: What SAA filtering mode should I use?

    A: The impact of the nucalcsaa filters depends on the space weather conditions during the observation. The NuSTAR SOC provides background filtering reports to aid the observer in making a decision about which filtering mode to use. The default pipeline option is not to use any SAA filtering.

    The NuSTAR webpage at: https://www.nustar.caltech.edu/page/background points to an automatically generated set of reports for each NuSTAR sequence ID. Each sequence ID has a PDF report that contains multiple pages illustrating the effect of the various SAA filters. The inputs to nupipeline are given at the top of each lightcurve on the left panels, while a map of the count rate as a function of orbital position (i.e., the NuSTAR ground trace longitude and latitude) is given in the right panels. The count rates in both the lightcurve and the orbital track plots are integrated over the entire field of view and so include both source and background counts.

    For sources that are bright (here bright implies 1 counts per second or higher), the effect of the SAA filtering will likely be negligible. For fainter sources, it is up to the user to determine whether or not to use the SAA filtering and which algorithm/mode to use. A description of the modes is given in the NuSTARDAS Software User's Guide*.

    The user needs to balance the reduction in the background rates vs the loss in effective exposure time. The remaining exposure time after the filtering is given as a percentage of the unfiltered exposure time in the top right above each orbital track plot.

    *See the HEASARC NuSTAR Analysis page for the NUSTARDAS software users guide, the NuSTAR observatory guide, and more details about NuSTAR data analysis.


  39. What do I do if I have a bright source?

    There are some post-processing filters that remove spurious triggers (a.k.a "noise events") from the NuSTAR cleaned event files. The rate of these noise events is ~2e-3 counts per second in a typical source extraction region with a diameter of 1 arcminute, though this rate varies based on which focal plane module is used and on the location on each focal plane. In the case of sources that produce moderate rates (when the incident rate on the focal plane exceeds 100 counts per second), "good" source counts can be vetoed by the noise filter. This can result in a mismatch between the measured flux between FPMA and FPMB (since they have subtly different filters) and an underestimate of the source flux.

    We recommend that for bright sources a user should produce a lightcurve with 1-second bins using nuproducts with the default energy range (3-79 keV). The resulting lightcurve should be a good estimate of the incident source rate. If any of the 1-second bins exceed 100 counts per second, we recommend re-processing the data using a modified value for the "statusexpr" keyword in nupipeline:

    statusexpr="(STATUS==b0000xxx00xxxx000)&&(SHIELD==0)"

    in addition to any other keywords. This status expression changes the behavior of the "nufilter" FTOOL that produces the cleaned output event files (e.g. files of the form "nu10311002008A01_cl.evt"). nupipeline must be re-run from scratch for the cleaned event files to be updated. To repeat: using this modified statusexpr keyword or any variations of other status-related keywords will not affect lightcurves produced by nuproducts if the cleaned event files have not been regenerated using nupipeline.

    Updated Jan 2023: Note that the previous versions of this FAQ omitted the "SHIELD==0" filter in the suggested statusexpr. In this case, events coincident with a particle hit in the CsI "shield" that surrounds the detectors are not screened out of the cleaned event files.

    For bright sources, NuSTAR often turns off the on-board event cosmic ray rejection, opting to instead flag the events and send them down to the ground. This is to avoid rejecting events that have a chance coincidence between a source photon and an (unrelated) particle hitting the CsI shield. For observations when the shield rejection is turned off, this can result in a higher (~factor of 2) non-X-ray background, which dominates the NuSTAR spectrum for energies above ~20 keV.

    The SHIELD==0 option above applies a software filter that removes all events with a cosmic ray hit (e.g., SHIELD=1) from the cleaned event files, and removes this additional background term. So we recommend using the above statusexpr as a baseline for most observations.

    For timing observations or observations of bright, hard source where the source flux is well above the background level up to 80 keV, we recommend using the version of statusexp without the SHIELD==0 addition listed below. Turning the shield veto on in software can result in removing source counts that have a chance coincidence with a particle hit in the CsI shield, and may influence the resulting power spectrum by preferentially removing the (more numerous) low-energy photons. We therefore suggest using the original filter expression in this case:

    statusexpr="STATUS==b0000xxx00xxxx000"


  40. Do I have to worry about pile-up if I have a bright source?

    In general, no. The NuSTAR pile-up window is so short that the instrument has only found evidence for pile-up in sources that produce incident count rates in excess of 10,000 counts per second (and then only at the few percent level). If you are working on such a bright source (i.e. the Sun and/or the flaring state of Sco X-1), please contact the NuSTAR SOC for details.


  41. Q: How do I split up my observation?

    A: You split up an observation by generating a GTI file and including it into the "nuproducts" call by adding the parameter 'usrgtifile=path_to_gtifile/gtifile'. GTI stands for Good Time Interval and is a fits file with a table of start and stop times that define the times to be included in the extraction. It can be written by the user itself in any program capable of producing fits files, but a convenient way to produce it is by using XSELECT. In XSELECT the steps are to load in the event-list, extract a light curve, select GTIs, and save the GTIs. An example can be seen here. The saved GTI file from XSELECT can be directly used in 'nuproducts' by including the 'usrgtifile=path_to_gtifile/gtifile' parameter in the call. Note that only one GTI-file can be used at a time. If the observation is to be split according to different selections (e.g., all time segments during which the flux is higher than a certain limit, flux_a, and all time segments during which the flux is higher than a different limit, flux_b), one GTI needs to be generated for each selection and nuproducts has to be run for each of them.

    IMPORTANT: It is critical to understand that the light curves produced by XSELECT have *NOT* been corrected for deadtime, effective area, or the PSF, so differences may be expected in rate and shape when compared to the light curves produced by the NuSTAR pipeline, which have had all these corrections applied. The light curves in XSELECT are only made to facilitate the selection of the GTI and should not be used for science. If you want to reproduce your light curve with the new GTI selections it must be done with nuproducts or nulccorr.


  42. Q: Why does the spectrum of my bright source appear significantly different in FPMA and FPMB below 8 keV?

    A: A rip in the multi layer insulation (MLI) at the exit aperture of the optic module aligned with detector focal plane module FPMA has resulted in an increased photon flux through the optic that has manifested itself as a low energy excess in FPMA spectra of bright sources. The effect is largest for 3 keV, with an exponential decrease between 5-8 keV. The rip occurred in early 2016, progressively enlarged through 2017 and then appeared to stabilize in 2018. To compensate for the increased flux, the amount of MLI covering the opening, F_MLI (in fraction of opening), in the on-axis ARF of module A has been adjusted as a time dependent component released in three new ARFs valid in different ranges:

    DATE                            FILE                   MLI FRACTION
    Launch to  01/01/2017           nuA20100101v007.arf     F_MLI=0.96
    01/01/2017 to 01/01/2018        nuA20170101v007.arf     F_MLI=0.91
    01/01/2018 onwards              nuA20180101v007.arf     F_MLI=0.86
    

    These are available from CALDB v2000429 and subsequent releases. The changes in the on-axis ARF affects all FPMA data from for the entire mission. No changes have been made to FPMB. The impact on data before 2017 is small and the correction removes a 1% excess in FPMA flux between 3-4 keV. The correction for data after 2018 removes a 4% excess flux at 3 keV and then declines at higher energies, becoming insignificant at 6 keV.

    Details on the issue, and a note on future releases, can be found in Madsen et al. (2020) arXiv:2005:00569.

    In addition, an FTOOLS mtable correction is available for pathological cases when there is a residual substantial difference between FPMA and FPMB seen in spectra below 5 keV. Note that in some instances, the MLI correction may be too aggressive. In these cases the old FPMA ARF should be used. See the MLI correction page on the SOC website for more details. A list of observations where use of the mtable is recommended is available on the NuSTAR SOC website.


  43. Q: Why does the count rate in a light curve generated via nuproducts differ by up to a few factors from the count rate obtained from the spectrum in XSPEC using the same extracting region for the same energy band?

    A: A light curve generated by nuproducts includes multiple corrections made to the RATE column based on the amount of the PSF enclosed by the extraction region, exposure variations, etc, as well as the LIVETIME of the instrument. These same corrections are applied to the response files (specifically, the effective area, or ARF) but not to a spectrum as well as the count rates being reported by XSPEC. The XSPEC count rate is simply the sum of the counts in your extraction region divided by the EXPOSURE time.
    Note: These corrections of the light curve count rates are applied by default in nuproducts. They can be switched off: Setting the nuproducts parameter 'correctlc' and related parameters handles these corrections. Further details are described in the
    nuproducts help file. The count rates without the corrections are recorded in the "RATE_ORIG" and "ERROR_ORIG" columns when the corrections are applied. Additional descriptions are also found in the nulccorr help file.


  44. Q: Why do I see an "RMF DETNAM" warning in XSPEC?

    A: For historic reasons NuSTAR PHA- and associated RMF files generally have different DETNAM keywords. This means XSPEC will give a warning like:

    "Warning: RMF DETNAM keyword (DET1) is not consistent with that in spectrum (NONE)"

    This is an alert for a situation where the user might be unintentionally mixing an RMF and a spectrum that do not "go together". This warning can usually be ignored for NuSTAR.


  45. Q: Why are the public dates missing for some ObservationID's in the NUMASTER table?

    A: Basic information about an observation (observation dates, exposure times, etc.) will be available in the NUMASTER table before the data quality is validated by the NuSTAR science operations center (SOC). The public release date will be included in the numaster table after the observation has been reviewed by the SOC to be of acceptable science quality. The maximum time between the completion of an observation and the release to the public is expected to be 60 days.


  46. Q: What is the significance of null values for RA and Dec in the NUMASTER table?

    A: The RA and Dec values in the NUMASTER table are based on the nominal observatory pointing J2000 coordinates calculated from the star tracker on the NuSTAR optical bench. The first ObservationID of an observation set usually contains only the time period when the observatory is slewing across the sky and when the star tracker is occulted by the Earth. No nominal observing mode (science quality) data are contained within files associated with these observationID's and so the RA and Dec values are null.

    Note that ObservationID's beginning with 0 are for non-pointing periods, usually associated with spacecraft calibration tests, and so (in all but the first calibration observations) will not contain stable observatory pointing periods.


  47. Q: Why is there zero exposure time in an ObservationID when the X-ray instrumentation on NuSTAR is never turned off?

    A: The exposure time in the numaster table is the normal mode (observing mode code = 01) livetime-corrected exposure time within an observationID. The data have been screened by the data analysis pipeline (nustardas using default parameters) to exclude periods when:

    Obs mode code   Reason
    
        02          The target is occulted by the Earth.
        03          The observatory is slewing.
        04          The observatory is passing through the South Atlantic Anomaly 
                    (SAA) and the instrument is turned off.
        05          The on-board radioactive calibration sources are in the 
                    field of view.
        06          No valid attitude solution from the optical bench star tracker 
                    is available.
    

    ObservationID's with zero exposure time are usually associated with the slew from the previous target that is timed to complete when the new target is occulted by the Earth and so contain no time in normal mode. Most observations will contain a series of time periods when normal mode data are available, separated by Earth occultation and SAA passages. These time periods are cataloged in the Good Time Interval (GTI) extension of the 01 mode event files. See sections 2 and 4 of the NuSTAR data analysis software users guide and the NuSTAR analysis quickstart guide, both available from the NuSTAR data analysis page.


  48. Q: How can I relate roll angle (the roll_angle parameter in NUMASTER) to a position angle on the sky?

    A: The roll angle tabulated in the NUMASTER table is the average position angle of the detector field of view on the sky. This is defined as the angle East of North of the direction of the +DET1Y focal plane axis. At PA = 0 degrees the +DET1X axis points East and the optical axis is approximately 1 arcminute NE of the center of the focal plane field of view.


  49. Q: What is the significance of the NuSTAR Observation ID (called ObsID in the NUMASTER table)?

    A: Every NuSTAR observation is assigned a unique 11 digit number of the form CPPttxxxvvv that is a combination of an 8 digit target identification number and a 3 digit visit number, where:

    C is the "source" category defined as:

          0 Non-pointing data (e.g. IOC) or safe hold
          1 Calibration observations, e.g. Crab nebula
          2 Solar system objects (e.g. the Sun)
          3 Galactic compact sources (stars, CVs, X-ray binaries, isolated 
            neutron stars)
          4 Non-ToO Supernovae, Supernova remnants, and Galactic diffuse emission
          5 Normal galaxies
          6 Active galaxies and quasars
          7 Galaxy clusters and extragalactic diffuse objects
          8 Proposed ToO's and Directors Discretionary Time
          9 Non-proposal ToO's 
    

    PP is two digits used to identify the program type as:

          00 is assigned to the first 2 year primary mission (2012 to 2014)
          01, 02 etc increments for each additional year of operation 
             (synchronized with possible GO time)
    

    tt is the program type within that PP. The value is reset at each PP. The tt values are the following:

           01 single observation of an object.
           02 multiple observation (monitoring) of the same object.
           10-59 reserved to tiling/mosaic/raster scan programs. These programs 
                 include several different targets (pointings) not at the same 
    	     sky position but are very close.       
          60-99 reserved to survey programs. These programs comprise observations 
                of several objects identified to carry out a specific science 
    	    investigation.
    
        xxx is the target number unique for a given C and PP.
    
        vvv is the observation visit number for a given target. Multiple 
            observations may be planned by the observer or due to operational 
    	scheduling requirements. The starting value is 001.
    

    The time period covered by an Obs(ervation)ID will begin at the time the command to slew to the target was executed and will end at the time the next slew command was executed.


  50. Q: Why do most targets have two Obs(ervation)ID's?

    A: A standard NuSTAR observation of a celestial source requires two slews and so results in two ObservationID's (obsIDs).

    The first ObsID starts with the slew from the previous target to the new target. This slew is performed in STELLAR ACS mode and can take up to an hour for the observatory to reach the new target. However this mode is unsuitable for science observations as it will include a roll maneuver of about 1 deg/day to maintain the solar array oriented to the Sun. So a second, usually short, slew maneuver is performed in INERTIAL ACS mode which freezes the observatory attitude, pointing the observatory at the celestial target for extended periods. The length of an observation is limited by how long the orientation of the solar panels in INERTIAL mode can remain within operational limits, usually about 1 week.

    To maximize efficiency the STELLAR slew is timed to arrive at the new target when it is occulted by the Earth. The following INERTIAL attitude slew maneuver is timed to complete within the same occultation period. An additional period of observatory settling is also allowed to complete before the celestial target exits Earth occultation and the science observation can begin. As an example, here are the entries in the as flown timeline around the observation of Mkn 421 on 2013 January 2nd:

        observationID Name           Start               End                  ACS
    
        60061256002   NGC5728        2013-01-02 04:20:05 2013-01-02 18:10:00  I
        60002023001   Mkn421	 2013-01-02 18:34:29 2013-01-02 18:40:00  S
        60002023002   Mkn421	 2013-01-02 18:40:02 2013-01-02 23:00:00  I
        60021009001   COSMOS_MOS009	 2013-01-02 23:16:40 2013-01-02 23:25:00  S
    
        (ACS I = INERTIAL mode, S = STELLAR mode)
    

    The slew in STELLAR mode from NGC 5728 to Mkn 421 began at 18:10:00 and completed at 18:34:29. The slew in INERTIAL mode on Mkn 421 began at 18:40:00 and completed at 18:40:02. The observatory in held in INERTIAL mode from 18:40:00 to 23:00:00. The position of Mkn 421 was occulted by the Earth from 18:22:24 until 19:00:44 and so the observatory will have completed all slews and attitude settling by the time the target emerged from behind the Earth. The observation ended when the observatory slew to the next target (COSMOS_MOS009) at 23:00:00. Observations of the same target at later dates will continue the visit numbering scheme. For example the next observation of Mkn 421 was on 2013 January 10th and contained obsID's 60002023003 & 60002023004.

    Note that some observations may have an additional obsID if it was deemed necessary to refine the observatory pointing. The small maneuver is usually performed within the first 10 orbits of an observation.

    Some targets may only have a single obsID associated with the observation if they are part of a survey program. These programs are usually planned as a mosaic of positions where the distance between the tiles in the mosaic are less than 10 degrees. No STELLAR mode slew is required to set the orientation of the solar array when observing these tiles contiguously.


  51. Q: How are the NuSTAR file names constructed?

    A: The filename format for the NuSTAR science files uses the following convention: "nuObservationID[M][xx]_[ll].ss" where:

    'nu' is the prefix indicating the mission name (NuSTAR);
    
    'ObservationID' is an 11-digit number identifying the observation (ObsID);
    
    'M' is a one-character string that identifies the Focal Plane Module (A or B);
    
    'xx' is a code to identify the observing mode as defined below: 
    
        01 (SCIENCE): normal observing scientific mode;
        02 (OCCULTATION): Earth in the field of view;
        03 (SLEW): data taken during a spacecraft slew;
        04 (SAA): South Atlantic Anomaly passages;
        05 (CALIBRATION): on-board calibration radioactive source in the field of 
    view; 
         06 (SCIENCE_SC): attitude reconstruction from the spacecraft bus star 
    trackers;
    
    'll' indicates for event files the processing level ('uf' for Level 1 and 
    Level 1a files, 'cl' for Level 2 files). For other data files it describes 
    their content (e.g. 'met' for raw metrology data, 'mast' for mast aspect 
    solution file, 'ex' for exposure maps);
    
    'ss' is the file extension and indicates the data type (e.g. 'evt' for event 
    files, 'img' for sky images, 'hk' for housekeeping files, 'lc' for 
    light-curves, 'pha' for energy spectra).
    
    The quantities in square brackets may not always be present, for example, (i) 'M' (A or B) is not used for data files from the metrology laser system and (ii) the observing mode code 'xx' is not used for Level 1/1a event files since the data splitting is carried out during Stage 2 of NuSTAR data processing (see Chapter 4 of the
    NuSTAR Data Analysis Software Users Guide for more details).

  52. Q: Why am I unable to download files from HEASARC?

    If you are using ftp, please note that HEASARC support for unencrypted FTP access ended on September 20, 2019. Please take a look at https://heasarc.gsfc.nasa.gov/docs/FTPWarning.html for further instructions. More detailed information about FTPS is here: https://spdf.gsfc.nasa.gov/ftps_readme.html


  53. Q: Why is the NORAD catalog number in the TLE files different from the USSPACECOM catalog number?

    A preliminary catalog designation for the NuSTAR satellite of 99105 was provided before launch and this is what is recorded in the archived Two Line Element (TLE) files in the NuSTAR archive. After launch NuSTAR was assigned the USSPACECOM catalog number 38358 but the TLE files are not updated with this number. The catalog number is not used in any calculations during the analysis of NuSTAR data.


  54. Q: What text is appropriate to acknowledge the use of NuSTAR data and NuSTARDAS in research papers?

    A: A typical acknowledgment in a work containing NuSTAR analysis is the following: "This research has made use of data from the NuSTAR mission, a project led by the California Institute of Technology, managed by the Jet Propulsion Laboratory, and funded by the National Aeronautics and Space Administration. Data analysis was performed using the NuSTAR Data Analysis Software (NuSTARDAS), jointly developed by the ASI Science Data Center (SSDC, Italy) and the California Institute of Technology (USA)."

    In addition, if using the HEASARC service made a significant contribution to a research project, please make the following acknowledgement in any resulting publication: "This research has made use of data and/or software provided by the High Energy Astrophysics Science Archive Research Center (HEASARC), which is a service of the Astrophysics Science Division at NASA/GSFC."