# TS Cube¶

Warning

This method requires Fermi Science Tools version 11-04-00 or later.

tscube() can be used generate both test statistic (TS) maps and bin-by-bin scans of the test source likelihood as a function of spatial pixel and energy bin (likelihood cubes). The implemention is based on the gttscube ST application which uses an efficient newton optimization algorithm for fitting the test source at each pixel in the ROI.

The TS map output has the same format as TS maps produced by tsmap() (see TS Map for further details). However while tsmap() fixes the background model, tscube() can also fit background normalization parameters when scanning the test source likelihood. This method makes no approximations in the evaluation of the likelihood and may be somewhat slower than tsmap() depending on the ROI dimensions and energy bounds.

For each spatial bin the method calculates the maximum likelihood test statistic given by

$\mathrm{TS} = 2 \sum_{k} \ln L(\mu,\hat{\theta}|n_{k}) - \ln L(0,\hat{\hat{\theta}}|n_{k})$

where the summation index k runs over both spatial and energy bins, μ is the test source normalization parameter, and θ represents the parameters of the background model. Normalization parameters of the background model are refit at every test source position if they are free in the model. All other spectral parameters (indices etc.) are kept fixed.

## Examples¶

The method is executed by providing a model dictionary argument that defines the spectrum and spatial morphology of the test source:

# Generate TS cube for a power-law point source with Index=2.0
model = {'Index' : 2.0, 'SpatialModel' : 'PointSource'}
cube = gta.tscube('fit1',model=model)

# Generate TS cube for a power-law point source with Index=2.0 and
# restricting the analysis to E > 3.16 GeV
model = {'Index' : 2.0, 'SpatialModel' : 'PointSource'}
cube = gta.tscube('fit1_emin35',model=model,erange=[3.5,None])

# Generate TS cubes for a power-law point source with Index=1.5, 2.0, and 2.5
model={'SpatialModel' : 'PointSource'}
cubes = []
for index in [1.5,2.0,2.5]:
model['Index'] = index
cubes += [gta.tsmap('fit1',model=model)]


In addition to generating a TS map, this method can also extract a test source likelihood profile as a function of energy at every position in the ROI (likelihood cube). This information is saved to the SCANDATA HDU of the output FITS file:

from astropy.table import Table
cube = gta.tscube('fit1',model=model, do_sed=True)

eflux_scan = tab_ebounds['REF_EFLUX'][None,:,None]*tab_scan['norm_scan']

# Plot likelihood for pixel 400 and energy bin 2
plt.plot(eflux_scan[400,2],tab_scan['dloglike_scan'][400,2])


The likelihood profile cube can be used to evaluate the likelihood for a test source with an arbitrary spectral model at any position in the ROI. The TSCube and CastroData classes can be used to analyze a TS cube:

from fermipy.castro import TSCube
tscube = TSCube.create_from_fits('tscube.fits')
cd = tscube.castroData_from_ipix(400)

# Fit the likelihoods at pixel 400 with different spectral models
cd.test_spectra()


## Configuration¶

The default configuration of the method is controlled with the tscube section of the configuration file. The default configuration can be overriden by passing the option as a kwargs argument to the method.

tscube Options
Option Default Description
cov_scale -1.0 Scale factor to apply to broadband fitting cov. matrix in bin-by-bin fits ( < 0 -> fixed )
cov_scale_bb -1.0 Scale factor to apply to global fitting cov. matrix in broadband fits. ( < 0 -> no prior )
do_sed True Compute the energy bin-by-bin fits
exclude None List of sources that will be removed from the model when computing the TS map.
init_lambda 0 Initial value of damping parameter for newton step size calculation. A value of zero disables damping.
max_iter 30 Maximum number of iterations for the Newtons method fitter.
model None Dictionary defining the spatial/spectral properties of the test source. If model is None the test source will be a PointSource with an Index 2 power-law spectrum.
nnorm 10 Number of points in the likelihood v. normalization scan
norm_sigma 5.0 Number of sigma to use for the scan range
remake_test_source False If true, recomputes the test source image (otherwise just shifts it)
st_scan_level 0 Level to which to do ST-based fitting (for testing)
tol 0.001 Critetia for fit convergence (estimated vertical distance to min < tol )
tol_type 0 Absoulte (0) or relative (1) criteria for convergence.

## Reference/API¶

GTAnalysis.tscube(prefix='', **kwargs)

Generate a spatial TS map for a source component with properties defined by the model argument. This method uses the gttscube ST application for source fitting and will simultaneously fit the test source normalization as well as the normalizations of any background components that are currently free. The output of this method is a dictionary containing Map objects with the TS and amplitude of the best-fit test source. By default this method will also save maps to FITS files and render them as image files.

Parameters: prefix (str) – Optional string that will be prepended to all output files (FITS and rendered images). model (dict) – Dictionary defining the properties of the test source. do_sed (bool) – Compute the energy bin-by-bin fits. nnorm (int) – Number of points in the likelihood v. normalization scan. norm_sigma (float) – Number of sigma to use for the scan range. tol (float) – Critetia for fit convergence (estimated vertical distance to min < tol ). tol_type (int) – Absoulte (0) or relative (1) criteria for convergence. max_iter (int) – Maximum number of iterations for the Newton’s method fitter remake_test_source (bool) – If true, recomputes the test source image (otherwise just shifts it) st_scan_level (int) – make_plots (bool) – Write image files. write_fits (bool) – Write a FITS file with the results of the analysis. maps – A dictionary containing the Map objects for TS and source amplitude. dict