Command Line Interface

nuskybgd.cli.absrmf(args=[])

{b}NAME{o}

{b}nuskybgd absrmf{o} Create RMF files that includes detector absorption (DETABS).

{b}USAGE{o}

absrmf evtfile outfile [rmffile=CALDB] [detabsfile=CALDB]

{b}DESCRIPTION{o}

{b}evtfile{o} - An event file from which the INSTRUME and DATE-OBS

keywords are taken.

{b}outfile{o} - Will be prefixed to the output file names, and can be a

file path.

{b}rmffile{o} - The RMF file to multiply by absorption. Set it to CALDB

(default) to use the latest CALDB file(s).

{b}detabsfile{o} - Detector absorption file to multiply the RMF with. Set

it to CALDB (default) to use the latest CALDB file(s).

nuskybgd.cli.aspecthist(args=[])

{b}NAME{o}

{b}nuskybgd aspecthist{o} Create an aspect histogram image from pointing info after filtering by GTI

{b}USAGE{o}

nuskybgd aspecthist aimpoints.fits gtifile=gti.fits out=aspecthist.fits

Example:

nuskybgd aspecthist nu90201039002A_det1.fits out=aspecthistA.fits

gtifile=nu90201039002A01_gti.fits

nuskybgd aspecthist nu90201039002B_det1.fits out=aspecthistB.fits

gtifile=nu90201039002B01_gti.fits

{b}DESCRIPTION{o}

The output file has an image representing the 2D histogram of pointing position with time. Gets pointing position from nu%obsid%?_det?.fits and good time intervals from nu%obsid%?0?_gti.fits. nu%obsid%?_det?.fits (e.g. nu90201039002A_det1.fits) has a table block named ‘DET?_REFPOINT’, with 3 columns (TIME, X_DET?, Y_DET?) where ? is the detector number (1-4). nu%obsid%?0?_gti.fits (e.g. nu90201039002A01_gti.fits) has a table block named ‘STDGTI’ with two columns (START, STOP) listing intervals of good times.

The image is in an extension with the name ASPECT_HISTOGRAM. Any zero padding has been cropped, and the x and y offsets are recorded in the header keywords X_OFF and Y_OFF.

nuskybgd.cli.fit(args=[])

{b}NAME{o}

{b}nuskybgd fit{o} Fit NuSTAR background model

{b}USAGE{o}

nuskybgd fit bgdinfo.json [savefile=bgdparams.xcm]

nuskybgd fit –help # print a sample bgdinfo.json

{b}DESCRIPTION{o}

Generate a multi-component background model for spectra from several background regions and save the model containing preset normalizations to an xcm file. If the intended save file exists, will retry 99 times with a number (2 to 100) appended to the name.

Required in bgdinfo.json:

{b}bgfiles{o} - An array of spectra file names, extracted from

background regions, grouped so that bins have gaussian statistics.

{b}regfiles{o} - An array of region files for the background regions,

in the same order as bgfiles.

{b}refimgf{o} - Reference image file for creating region mask images,

can be the background aperture image file.

{b}bgdapfiles{o} - Dictionary with ‘A’ and ‘B’ keys, pointing to

background aperture image files for each focal plane module.

{b}bgddetfiles{o} - Dictionary with ‘A’ and ‘B’ keys, pointing to

lists of 4 detector mask image files for each focal plane module.

nuskybgd.cli.image(args=[])

{b}NAME

{b}nuskybgd image{o} Create images of the nuskybgd model sources.

{b}USAGE{o}

nuskybgd image infofile.json bgdparams.xcm emin emax [prefix=]

{b}DESCRIPTION{o}

The result from {b}nuskybgd fit{o} is first retrieved by referring to infofile.json and loading bgdparams.xcm in Xspec. This is used to create image models of each background source defined in auxil/ratios.json are created, by getting model predicted counts in the background regions from Xspec and extrapolating to the whole field of view.

{b}infofile.json{o} - The same JSON file that was used with {b}nuskybgd

fit{o} to obtain the background model.

{b}bgdparams.xcm{o} - The Xspec save file from {b}nuskybgd fit{o}.

{b}emin{o} - Lower energy bound in keV.

{b}emax{o} - Upper energy bound in keV.

{b}prefix{o} - (Optional) Prefix for output files.

The following files will be created (or overwritten): bgd_apbgd_[A/B].fits, bgd_intbgd_[A/B].fits, bgd_intn_[A/B].fits, bgd_fcxb_[A/B].fits, as well as bgd_fcxb_[spectrum_number].fits for each background spectrum.

nuskybgd.cli.main_nuskybgd()

Entry point for main CLI interface

nuskybgd.cli.mkinstrmap(args=[])

{b}NAME

{b}nuskybgd mkinstrmap{o} Create an instrument map for a specific observation

{b}USAGE{o}

nuskybgd mkinstrmap A01_cl.evt [usrbpix=usrbpix.fits] [prefix=prefix]

{b}DESCRIPTION{o}

Bad pixels from CALDB will always be applied.

{b}usrbpix{o} - Specify additional bad pixels using a FITS file that has

BADPIX extension(s). Multiple files can be given, separated by commas (with no space in the argument).

{b}prefix{o} - Add a file name prefix for the output file. This allows the

output to be written to any specified path. If a directory is intended, it must end with ‘/’.

{b}dryrun{o} - If ‘yes’, the task will stop after the bad pixel files have

been checked, before the instrument map is calculated.

nuskybgd.cli.projbgd(args=[])

{b}NAME{o}

{b}nuskybgd projbgd{o} Project the instrument map onto sky coordinates

{b}USAGE{o}

nuskybgd projbgd refimg=flux.fits out=output.fits

mod=[A,B] det=[1,2,3,4] chipmap=chipmap.fits aspect=aspect.fits

Example:

nuskybgd projbgd refimg=imA4to25keV.fits out=bgdapA.fits

mod=A det=1234 chipmap=newinstrmapA.fits aspect=aspecthistA.fits

{b}DESCRIPTION{o}

The output file bgdapA.fits has the background aperture image in sky coordinates. A series of files showing the projected detector masks for each detector specified by det= will also be created, named det[0-3]Aim.fits.

nuskybgd.cli.run(args=[])

{b}NAME{o}

{b}nuskybgd{o} Run nuskybgd tasks from command line.

{b}USAGE{o}

nuskybgd task [arguments for task]

{b}DESCRIPTION{o}

Without task arguments, the usage message for that task will be printed. The functions for these tasks can also be used in Python, either in an interactive session or in a script, by passing an arguments list to them in lieu of sys.argv.

(For Python functions, see their __doc__ attribute.)

The following tasks are available:

{b}aspecthist {o}Create aspect histogram image of pointing {b}mkinstrmap {o}Make instrument map image {b}projbgd {o}Create aperture background and detector mask images

rotated and convolved with the aspect histogram

{b}fit {o}Fit the background models to spectra from background

regions

{b}spec {o}Scale the fitted background model for a source

region

{b}image {o}Create images of the background sources {b}simplify {o}Simplify the source + background Xspec save file by

removing the spectra from the background regions.

{b}absrmf {o}Add detector absorption to RMF files

nuskybgd.cli.simplify(args=[])

{b}NAME

{b}nuskybgd simplify{o} Remove the background region spectra from the Xspec save file

{b}USAGE{o}

nuskybgd simplify infofile.json bgd_src.xcm [savefile=bgd_only_src.xcm]

{b}DESCRIPTION{o}

The result from {b}nuskybgd spec{o} is loaded in Xspec, and the first few spectra in the list are removed (based on how many entries there are in bgdinfo). Only source spectra and their background models remain. All parameters are frozen, making it ready for the user to load the resulting save file and add their source model.

{b}infofile.json{o} - The same JSON file that was used with {b}nuskybgd

fit{o} to obtain the background model.

{b}bgd_src.xcm{o} - The Xspec save file from {b}nuskybgd spec{o}.

{b}savefile{o} - (Optional) Name of the output file. By default, if ‘bgd_’

is in the input xcm file name, it is replaced by ‘bgd_only_’ for the output file name. Otherwise, ‘bgd_only_’ is prepended to the input file name.

nuskybgd.cli.spec(args=[])

{b}NAME

{b}nuskybgd spec{o} Rescale the background models for a source region

{b}USAGE{o}

nuskybgd spec infofile.json bgdparams.xcm source.reg source.pha

[savefile=bgd_source.xcm]

{b}DESCRIPTION{o}

The result from {b}nuskybgd fit{o} is first retrieved by referring to infofile.json and loading bgdparams.xcm in Xspec. The source spectrum is then appended to the spectra file list and its corresponding parameters values for all the background model sources are rescaled. This state is saved to a new *.xcm file, which the user can load in Xspec to inspect the quality of the background model against the source spectrum.

{b}infofile.json{o} - The same JSON file that was used with {b}nuskybgd

fit{o} to obtain the background model.

{b}bgdparams.xcm{o} - The Xspec save file from {b}nuskybgd fit{o}.

{b}source.reg{o} - Region file containing the source region.

{b}source.pha{o} - Source spectrum file, binned appropriately and

containing header keywords specifying its RESPFILE.

{b}savefile{o} - (Optional) Name of the output file. By default, ‘bgd_’ is

prepended to the prefix of the first source region file, e.g. src1.reg,src2.reg -> bgd_src1.xcm.