NAME

USAGE

DESCRIPTION

'nuproducts' extracts high-level product data files, i.e. spectra, light-curves and images, using as input the calibrated and screened event file (Level 2). Optionally, the task generates the ARF and RMF files.

By default, the high-level data products are extracted from the 01 cleaned event file (input parameter 'infile=DEFAULT'). The data products are: spectrum, light-curve and image. The source spectrum and light-curve are extracted by filtering the data on a spatial region in SKY coordinates. If the parameter 'srcregionfile' is set to DEFAULT the user, through the parameters 'srcra', 'srcdec' and 'srcradius', can specify the Right Ascension and Declination of the center and the radius of a circular extraction region.

An extraction region file with an arbitrary shape can be input through the parameter 'srcregionfile'. This file should have a format compatible with XSELECT and DS9. Note that, for point-like sources, while arbitrary region geometries can be used for products extraction, specific region geometries are required for the generation of corrected ARFs and the PSF correction of light-curves. For a list of the supported geometries of the extraction regions see the help files of the modules 'numkarf' and 'nulccorr'. A full field of view image in sky coordinates is produced if the parameter 'imagefile' is different from 'NONE'.

Spectra and light-curves are not background subtracted. By setting the parameter 'bkgextract' to 'yes' the user can extract the spectrum and light-curve of the background from a region file specified by the parameter 'bkgregionfile'. Alternatively ('bkgregionfile'='DEFAULT'), the user can define through the parameters 'bkgra', 'bkgdec', 'bkgradius1' and 'bkgradius2' the Right Ascension, Declination of the center and the inner and outer radiii of an annular extraction region. If the input parameter 'runbackscale=yes' (default), the 'BACKSCAL' keywords of the source and background energy spectra are updated by running the 'nubackscale' task (see help file).

Optionally, by setting the input parameter 'rungrppha' to 'yes', an additional output source energy spectrum (parameter 'grpphafile') is generated. This spectrum is grouped through an internal run of the FTOOL 'grppha'. The energy spectrum is grouped such that i) a minimum of 'grpmincounts' counts is contained in each bin and ii) the energy channels lower than 'grppibadlow' and higher than 'grppibadhigh' are flagged as bad. By default, the energy range of the output grouped spectrum is 35-1909 PI channels corresponding to the 3-78 keV energy band.

For the extraction of light-curves the user can set the binsize (in seconds) via the parameter 'binsize'. For the extraction of light-curves and sky images the minimum and maximum values of the PI channels can be changed via the parameters 'pilow' and 'pihigh'. Moreover, the user can apply a time filter to the event file and high-level data products providing in input a fits GTI file (parameter 'usrgtifile').

By default (parameter 'correctlc=yes'), the task applies the livetime, PSF/EXPOSURE and vignetting corrections to the output light-curves by running the 'nulccorr' task (see help file).

The user can choose the device for the plots of the image, light curve and enery spectrum through the input parameter 'plotdevice' (GIF or PS).

Optionally, by setting to 'yes' the input parameters 'rummkarf' and 'runmkrmf', the task also generates the appropriate ARF and RMF files for the extracted source spectrum. This is achieved by running the tasks 'numkarf' and 'numkrmf' (see the specific help files for more details). Optionally, by setting the input parameter 'arfmlicorr' to 'yes', the OBEB Housekeeping FITS File (input parameter 'obebhkfile') is provided in input to 'numkarf' to enable the CALDB temperature dependent on-axis ARF file query (FPMA data only).

The task can also optionally apply the barycenter correction to the output files by setting the input parameter 'barycorr' to 'yes' (default is 'no'). The barycenter correction is calculated through the multimission FTOOL 'barycorr'. The correction is applied to the following input files: 'infile', 'mastaspectfile', 'attfile', 'det1reffile', 'optaxisfile', 'hkfile'. If 'arfmlicorr' is set to 'yes', the barycenter correction is applied also to the 'obebhkfile'. Note that when 'nuproducts' is run providing in input a user GTI file (parameter 'usrgtifile') the barycenter correction is applied to it if the input parameter 'usrgtibarycorr' is set to 'yes' (default value).

To apply the barycenter correction it is necessary to set the input parameter 'orbitfile' and specify the position of the source (parameters 'srcra_barycorr' and 'srcdec_barycorr'). The barycenter corrected cleaned event file can be saved in the output directory by setting the parameter 'write_baryevtfile=yes'.

PARAMETERS

indir [string]

Input Directory Path.

instrument [string]

Focal Plane Module to be processed [FPMA|FPMB].

steminputs [string]

Stem for FITS input files [i.e. nu40060001001].

outdir [string]

Name of the output directory for products.

(stemout = DEFAULT)

Stem for the output files or DEFAULT to use the stem of input files.

(infile = DEFAULT) [file name]

Name of the input FITS Event File or DEFAULT to use the 01 event file from the input directory.

(srcregionfile = DEFAULT) [file name]

Name of the input source region file or DEFAULT to create a standard region file.

(bkgextract=yes) [boolean]

Extract background products? (yes/no).

(bkgregionfile = DEFAULT) [file name]

Name of the input background region file or DEFAULT to create a standard region file (only if bkgextract=yes).

(mastaspectfile=DEFAULT) [file name]

Name of the input Mast Aspect Solution File or DEFAULT to use the file from the input directory.

(attfile=DEFAULT) [file name]

Name of FITS attitude file or DEFAULT to use the file from the input directory.

(det1reffile=DEFAULT) [file name]

Name of the input DET1 Reference Point File or DEFAULT to use the file from the input directory.

(arfmlicorr=no) [boolean]

If set to yes, enables ARF MLI temperature-dependent correction for FPMA data.

(obebhkfile=DEFAULT) [file name]

Name of the input OBEB Housekeeping FITS File or DEFAULT to use the file from the input directory (only if arfmlicorr=yes)

srcra [string]

Source RA position (degrees or hh mm ss.s) (only if srcregionfile=DEFAULT).

srcdec [string]

Source DEC position (degrees or hh mm ss.s) (only if srcregionfile=DEFAULT).

(srcradius=20) [real]

Radius of source extraction region in pixels (pixel size = 2.46 arcsec) (only if srcregionfile=DEFAULT)

bkgra [string]

RA of background extraction region center (degrees or hh mm ss.s) (only if bkgregionfile=DEFAULT).

bkgdec [string]

DEC of background extraction region center (degrees or hh mm ss.s) (only if bkgregionfile=DEFAULT).

(bkgradius1=50) [real]

Inner radius of background extraction region in pixels (pixel size = 2.46 arcsec) (only if bkgregionfile=DEFAULT)

(bkgradius2=80) [real]

Outer radius of background extraction region in pixels (pixel size = 2.46 arcsec) (only if bkgregionfile=DEFAULT)

(binsize=10) [real]

Bin size (seconds) for the light curve.

(lcfile = DEFAULT) [file name]

Name of the output source light-curve file or DEFAULT to use stem or NONE for none.

(phafile = DEFAULT) [file name]

Name of the output source PHA file or DEFAULT to use stem or NONE for none.

(bkglcfile = DEFAULT) [file name]

Name of the output background light-curve file or DEFAULT to use stem or NONE for none (only if bkgextract=yes).

(bkgphafile = DEFAULT) [file name]

Name of the output background PHA file or DEFAULT to use stem or NONE for none (only if bkgextract=yes).

(imagefile = DEFAULT) [file name]

Name of the output image file or DEFAULT to use stem or NONE for none.

(usrgtifile = NONE) [file name]

Name of the input GTI file for spectrum and light curve extraction or NONE for none.

(plotdevice = gif)

Device for plots (gif or ps).

(pilow = 35) [integer]

Minimum PI value for light curve and image extraction.

(pihigh = 1909) [integer]

Maximum PI value for light curve and image extraction.

(pixposfile=CALDB) [filename]

Name of the input pixel location file or CALDB.

(alignfile=CALDB) [filename]

Name of the input alignment file or CALDB.

(teldef=CALDB) [filename]

Name of teldef calibration file or CALDB.

(instrprobmapfile=CALDB) [filename]

Name of the input Instrument Probability Map File or CALDB.

(aberration=no) [boolean]

If set to yes, aberration is included in aspecting.

(pixbin = 5) [integer]

Bin size of aspect histogram in pixels (pixel size = 2.46 arcsec).

(barycorr=no) [boolean]

If set to yes, barycenter correction is executed.

(clockfile=CALDB) [filename]

Name of the Clock Correction File or CALDB (used only if barycorr=yes).

orbitfile [filename]

Name of the input Attitude-Orbit FITS File (used only if barycorr=yes).

srcra_barycorr [real]

Source RA position in decimal degrees (used only if barycorr=yes).

srcdec_barycorr [real]

Source DEC position in decimal degrees (used only if barycorr=yes).

(outfile=DEFAULT) [filename]

Name of the output barycenter corrected FITS Event File or DEFAULT to use stem (used only if barycorr=yes).

(usrgtibarycorr=yes) [boolean]

If set to yes, barycenter correction to the input user GTI file is executed.

(write_baryevtfile=no) [boolean]

Write output barycenter corrected FITS Event File? (yes/no) (used only if barycorr=yes).

(correctlc=yes) [boolean]

If set to yes, nulccorr task is executed.

(hkfile=DEFAULT) [file name]

Name of the input Housekeeping FITS File or DEFAULT to use the file from the input directory.

(lcenergy = 10) [real]

Energy value for PSF and vignetting calculation in LC correction (keV).

(lcpsfflag=yes) [boolean]

If set to yes, apply PSF correction to LC file (used only if extended=no).

(lcexpoflag=yes) [boolean]

If set to yes, apply EXPOSURE correction to source and background LC files (used only if extended=yes).

(lcvignflag=yes) [boolean]

If set to yes, the vignetting correction is applied to LC file.

(lcsrccorrfile=NONE) [filename]

Name of the output LC source correction file or NONE for none.

(lcbkgcorrfile=NONE) [filename]

Name of the output LC background correction file or NONE for none.

(runmkarf=yes) [boolean]

If set to yes, numkarf task is executed.

(outarffile=DEFAULT) [file name]

Name of the output ARF FITS File or DEFAULT to use stem.

(optaxisfile=DEFAULT) [file name]

Name of the input Optical Axis File or DEFAULT to use the file from the input directory.

(offaxisfile=NONE) [file name]

Name of the output Off-Axis File or DEFAULT to use stem or NONE for none (only if extended=no).

(offaxishisto=NONE) [file name]

Name of the output Off-Axis Histogram or DEFAULT to use stem or NONE for none (only if extended=no).

(apstophisto=NONE) [file name]

Name of the output Aperture Stop Histogram or DEFAULT to use stem or NONE for none (only if extended=no).

(grhisto=NONE) [file name]

Name of the output Ghost Rays Histogram or DEFAULT to use stem or NONE for none (only if extended=no).

(phibin = 30) [real]

Azimuth angle bin size for vignetting correction (degrees).

(apstopphibin = 10) [real]

Azimuth angle bin size for Aperture Stop correction (degrees).

(grphibin = 10) [real]

Azimuth angle bin size for Ghost Rays correction (degrees).

(inarffile=CALDB) [filename]

Name of the input ARF file or CALDB.

(grppsffile=CALDB) [filename]

Name of the input 2D-PSF Grouping File for ARF generation or CALDB.

(psfdir=CALDB) [filename]

Name of the input 2D-PSF files directory for ARF generation or CALDB.

(psffile=CALDB) [filename]

Name of the input 2D-PSF file for LC correction or CALDB.

(vignfile=CALDB) [filename]

Name of the input vignetting file or CALDB.

(apstopcorrfile=CALDB) [filename]

Name of the input Aperture Stop Correction file or CALDB.

(grcorrfile=CALDB) [filename]

Name of the input Ghost Rays Correction file or CALDB.

(detabscorrfile=CALDB) [filename]

Name of the input DETABS Correction file or CALDB.

(psfflag=yes) [boolean]

If set to yes, apply psf correction to ARF file (used only if extended=no).

(vignflag=yes) [boolean]

If set to yes, apply vignetting correction to ARF file.

(apstopflag=yes) [boolean]

If set to yes, apply aperture stop correction to ARF file.

(grflag=yes) [boolean]

If set to yes, apply ghost rays correction to ARF file (used only if extended=no).

(detabsflag=yes) [boolean]

If set to yes, apply DETABS correction.

(extended=no) [boolean]

Extended source?(yes/no).

(boxsize=20) [integer]

Size in pixel for the subimage boxes (used if extended=yes).

(pilowarf=35) [integer]

Minimum PI value for subregion ARF weight calculation (only if extended=yes).

(pihigharf=1909) [integer]

Maximum PI value for subregion ARF weight calculation (only if extended=yes).

(flatflagarf=no) [boolean]

If set to yes, use flat distribution for addarf execution (only if extended=yes).

(cutmaps=yes) [boolean]

Use resized exposure maps for PSF correction?(yes/no) (only if extended=no).

(percent = 0.02) [real]

Probability threshold for DET1 instrument map generation.

(runmkrmf=yes) [boolean]

If set to yes, numkrmf task is executed.

(outrmffile=DEFAULT) [file name]

Name of the output RMF FITS File or DEFAULT to use stem.

(grprmffile=CALDB) [filename]

Name of the input RMF Grouping File for RMF file generation or CALDB.

(rmfdir=CALDB) [file name]

Name of the input RMF files directory or CALDB.

(cmprmf=yes) [boolean]

If set to yes, the output RMF file is compressed.

(runbackscale=yes) [boolean]

If set to yes, nubackscale task is executed.

(rungrppha=no) [boolean]

If set to yes, grppha task is executed to group source energy spectrum.

(grpphafile=DEFAULT) [file name]

Name of the output source grouped PHA file or DEFAULT to use stem (only if rungrppha=yes).

(grpmincounts=30) [integer]

Minimum number of counts in each channel bin (only if rungrppha=yes).

(grppibadhigh=1909) [integer]

Maximum PI value for grouping of source PHA file (only if rungrppha=yes)

(grppibadlow=35) [integer]

Minimum PI value for grouping of source PHA file (only if rungrppha=yes).

(initseed=no) [boolean]

If set to yes, the random number generator uses a frozen seed value. If set to no, different seeds are generated for each run.

(cleanup = yes) [boolean]

If set to 'yes', delete temporary files.

(clobber=no) [boolean]

If set to yes, overwrite the output file.

(history=yes) [boolean]

If set to yes, write parameter values and other information in HISTORY blocks.

(chatter = 3) [integer]

Chatter Level (min=0, max=5).

EXAMPLES

1. Extract from the Level 2 event file 'nu40060001001A01_cl.evt' the source spectrum and corrected light-curve in a spatial region specified in the file 'source.reg'. The background spectrum and corrected light-curve are also produced using the region file 'bkg.reg'.

   > nuproducts srcregionfile=source.reg bkgregionfile=bkg.reg indir=./ outdir=./products
     steminputs=nu40060001001 instrument=FPMA runmkarf=no runmkrmf=no
   

2. Extract from the Level 2 event file 'nu40060001001A01_cl.evt' the source spectrum and corrected light-curve included in a circular region of 20 pixels radius centered on celestial coordinates (RA,Dec)=(187.383,30.071). The background spectrum and light-curve are not produced. ARF and RMF files are also generated in output.

   > nuproducts srcra=187.383 srcdec=30.071 bkgextract=no indir=./ outdir=./products  
     steminputs=nu40060001001 instrument=FPMA
   

3. Extract from the Level 2 event file 'nu40060001001A01_cl.evt' the source spectrum and corrected light-curve in a spatial region specified in the file 'source.reg'. The background spectrum and corrected light-curve are also produced using the region file 'bkg.reg'. The barycenter correction is also applied to the ouput files using the celestial coordinates specified by the parameters 'srcra_barycorr' and 'srcdec_barycorr'.

   > nuproducts srcregionfile=source.reg bkgregionfile=bkg.reg indir=./ outdir=./products
     steminputs=nu40060001001 instrument=FPMA barycorr=yes srcra_barycorr=187.383 srcdec_barycorr=30.071
     orbitfile=nu40060001001A.attorb
   

4. Extract from the Level 2 event file 'nu40060001001A01_cl.evt' the source spectrum and corrected light-curve in a spatial region specified in the file 'source.reg'. The background spectrum and corrected light-curve are also produced using the region file 'bkg.reg'. A grouped source energy spectrum (named 'nu40060001001A01_sr_grp.pha') is also generated.

   > nuproducts rungrppha=yes srcregionfile=source.reg bkgregionfile=bkg.reg indir=./ outdir=./products
     steminputs=nu40060001001 instrument=FPMA grpmincounts=30 grppibadlow=35 grppibadhigh=1909
   

5. Extract from the Level 2 event file 'nu40060001001A06_chu1_N_cl.evt' the source spectrum and corrected light-curve in a spatial region specified in the file 'source06_chu1.reg'. The background spectrum and corrected light-curve are also produced using the region file 'bkg06_chu1.reg'. ARF and RMF files are also generated in output.

   > nuproducts infile=nu40060001001A06_chu1_N_cl.evt srcregionfile=source06_chu1.reg bkgregionfile=bkg06_chu1.reg 
     indir=./ outdir=./products06 steminputs=nu40060001001 instrument=FPMA
   

   BUGS

   SEE ALSO

   LAST MODIFIED

   March 2021