NuSTAR Frequently Asked Questions


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

    General

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

    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 will be observed during NuSTAR's 2-year primary science mission phase?

  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?

    Archive and Documentation

  7. When and where will NuSTAR datasets become publicly available?*NEW*

  8. Which NuSTAR datasets were initially released?

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

  10. Where can I find documentation for analyzing NuSTAR data?

    Analysis Software and Calibration

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

  12. How can I access NuSTAR calibration data?

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

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

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

    Analysis Issues

  16. 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?

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

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

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

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

  21. On what time scales does nulccorr apply the livetime corrections?*NEW*

    Miscellaneous

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

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

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

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

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

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

  28. How are the NuSTAR file names constructed?


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 will be observed during NuSTAR's 2-year primary science mission phase?

    A: The list of all targets, both observed and to be observed, in the current NuSTAR PI mission target list is available at this SOC web page at Caltech. These tables will be regularly updated as the observations of targets are completed.


  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, ToOs from the community will only be accepted for exceptional events. 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).

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

    A: The first set of 29 NuSTAR observations were made public on August 29, 2013, at the HEASARC, the designated NuSTAR archival site. The second set of 72 NuSTAR observations was made public on November 25, 2013, the third data release of 104 NuSTAR observations occurred on February 5, 2014 and the 4th NuSTAR data release of 163 NuSTAR observations on May 7, 2014. Additional datasets will be released at roughly quarterly intervals. By the end of 2014, it is expected that the HEASARC Archive will have 'caught up' with the available NuSTAR data. From then on, the data for a NuSTAR observation should become public no more than 60 days after the completion of that observation. The exceptions to this rule are:

    a) Observations coordinated with another observatory which will be released at the end of the exclusive use period associated with the other observatory.
    b) Survey programs which will be released 60 days after the survey program is completed.
    c) Observations with significant quality issues whose release may be delayed until the NuSTAR SOC determines the impact on science analysis.


  8. 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.


  9. 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.


  10. 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.


  11. 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.


  12. 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.


  13. 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 (FITS format). After applying the clock offset correction, clock offset errors are nominally less than 2 msec.

    The NuSTAR pipeline tasks 'nupipeline' and 'nuproducts' do not accept a barycentered event file as input. Because of this, we recommend that users apply barycenter correction only to light curve products.

    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. It is expected that NuSTAR CALDB patches may only occur every 6 months so the most recent clock calibration file can be obtained between CALDB patches from the NuSTAR SOC website. The file is updated approximately once per month.


  14. 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.


  15. 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.


  16. 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.


  17. 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.


  18. 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.


  19. 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.


  20. 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.


  21. 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.


  22. 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.


  23. 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.


  24. 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.


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


  26. 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.


  27. 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.


  28. 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).