fermipy package

Submodules

fermipy.config module

class fermipy.config.ConfigManager

Bases: object

static create(configfile)

Create a configuration dictionary from a yaml config file. This function will first populate the dictionary with defaults taken from pre-defined configuration files. The configuration dictionary is then updated with the user-defined configuration file. Any settings defined by the user will take precedence over the default settings.

static load(path)

class fermipy.config.Configurable(config, **kwargs)

Bases: object

The base class provides common facilities like loading and saving configuration state.

config

Return the configuration dictionary of this class.

configure(config, **kwargs)

classmethod get_config()

Return a default configuration dictionary for this class.

print_config(logger, loglevel=None)

write_config(outfile)

Write the configuration dictionary to an output file.

fermipy.config.cast_config(config, defaults)

fermipy.config.create_default_config(defaults)

Create a configuration dictionary from a defaults dictionary. The defaults dictionary defines valid configuration keys with default values and docstrings. Each dictionary element should be a tuple or list containing (default value,docstring,type).

fermipy.config.validate_config(config, defaults, block='root')

fermipy.defaults module

fermipy.defaults.make_default_dict(d)

fermipy.gtanalysis module

class fermipy.gtanalysis.GTAnalysis(config, **kwargs)

Bases: fermipy.config.Configurable

High-level analysis interface that internally manages a set of analysis component objects. Most of the functionality of the fermiPy package is provided through the methods of this class. The class constructor accepts a dictionary that defines the configuration for the analysis. Keyword arguments provided in **kwargs can be used to override parameter values in the configuration dictionary.

add_source(name, src_dict, free=False, init_source=True, save_source_maps=True, **kwargs)

Add a source to the ROI model. This function may be called either before or after setup().

Parameters:

• name (str) – Source name.
• src_dict (dict or Source object) – Dictionary or source object defining the source properties (coordinates, spectral parameters, etc.).
• free (bool) – Initialize the source with a free normalization parameter.

cleanup()

components

Return the list of analysis components.

counts_map()

Return a Map representation of the counts map.

Returns:map Return type:Map

static create(infile, config=None)

Create a new instance of GTAnalysis from an analysis output file generated with write_roi. By default the new instance will inherit the configuration of the saved analysis instance. The configuration may be overriden by passing a config file path with the config argument.

Parameters:

• infile (str) – Path to the ROI results file.
• config (str) – Path to a configuration file. This will override the configuration in the ROI results file.

defaults = {'sourcefind': {'max_iter': (3, 'Set the number of search iterations.', <type 'int'>), 'min_separation': (1.0, 'Set the minimum separation in deg for sources added in each iteration.', <type 'float'>), 'tsmap_fitter': ('tsmap', 'Set the method for generating the TS map.', <type 'str'>), 'sqrt_ts_threshold': (5.0, 'Set the threshold on sqrt(TS).', <type 'float'>), 'model': (None, 'Set the source model dictionary. By default the test source will be a PointSource with an Index 2 power-law specturm.', <type 'dict'>), 'sources_per_iter': (3, '', <type 'int'>)}, 'roiopt': {'npred_frac': (0.95, '', <type 'float'>), 'shape_ts_threshold': (100.0, '', <type 'float'>), 'npred_threshold': (1.0, '', <type 'float'>)}, 'selection': {'radius': (None, 'Radius of data selection. If none this will be automatically set from the ROI size.', <type 'float'>), 'tmin': (None, 'Minimum time (MET).', <type 'int'>), 'target': (None, 'Choose an object on which to center the ROI. This option takes precendence over ra/dec or glon/glat.', <type 'str'>), 'glon': (None, '', <type 'float'>), 'emin': (None, 'Minimum Energy (MeV)', <type 'float'>), 'emax': (None, 'Maximum Energy (MeV)', <type 'float'>), 'tmax': (None, 'Maximum time (MET).', <type 'int'>), 'glat': (None, '', <type 'float'>), 'filter': (None, 'Filter string for ``gtmktime`` selection.', <type 'str'>), 'logemax': (None, 'Maximum Energy (log10(MeV))', <type 'float'>), 'ra': (None, '', <type 'float'>), 'evtype': (None, 'Event type selection.', <type 'int'>), 'evclass': (None, 'Event class selection.', <type 'int'>), 'zmax': (None, 'Maximum zenith angle.', <type 'float'>), 'logemin': (None, 'Minimum Energy (log10(MeV))', <type 'float'>), 'dec': (None, '', <type 'float'>), 'roicut': ('no', '', <type 'str'>), 'convtype': (None, 'Conversion type selection.', <type 'int'>)}, 'logging': {'verbosity': (3, '', <type 'int'>), 'chatter': (3, 'Set the chatter parameter of the STs.', <type 'int'>)}, 'tsmap': {'multithread': (False, '', <type 'bool'>), 'model': (None, 'Dictionary defining the properties of the test source.', <type 'dict'>), 'erange': (None, 'Lower and upper energy bounds in log10(E/MeV). By default the calculation will be performed over the full analysis energy range.', <type 'list'>), 'max_kernel_radius': (3.0, '', <type 'float'>)}, 'mc': {'seed': (None, '', <type 'int'>)}, 'components': (None, '', <type 'list'>), 'localize': {'dtheta_max': (0.3, 'Half-width of the search region in degrees used for the first pass of the localization search.', <type 'float'>), 'nstep': (5, 'Number of steps along each spatial dimension in the refined likelihood scan.', <type 'int'>), 'fix_background': (True, 'Fix background parameters when fitting the source flux in each energy bin.', <type 'bool'>), 'update': (False, 'Update the source model with the best-fit position.', <type 'bool'>)}, 'binning': {'projtype': ('WCS', 'Projection mode (WCS or HPX).', <type 'str'>), 'binsperdec': (8, 'Number of energy bins per decade.', <type 'float'>), 'enumbins': (None, 'Number of energy bins. If none this will be inferred from energy range and ``binsperdec`` parameter.', <type 'int'>), 'roiwidth': (10.0, 'Width of the ROI in degrees. The number of pixels in each spatial dimension will be set from ``roiwidth`` / ``binsz`` (rounded up).', <type 'float'>), 'hpx_ebin': (True, 'Include energy binning', <type 'bool'>), 'binsz': (0.1, 'Spatial bin size in degrees.', <type 'float'>), 'npix': (None, 'Number of pixels. If none then this will be set from ``roiwidth`` and ``binsz``.', <type 'int'>), 'hpx_order': (10, 'Order of the map (int between 0 and 12, included)', <type 'int'>), 'proj': ('AIT', 'Spatial projection for WCS mode.', <type 'str'>), 'coordsys': ('CEL', 'Coordinate system of the spatial projection (CEL or GAL).', <type 'str'>), 'hpx_ordering_scheme': ('RING', 'HEALPix Ordering Scheme', <type 'str'>)}, 'extension': {'save_model_map': (False, '', <type 'bool'>), 'width': (None, 'Parameter vector for scan over spatial extent. If none then the parameter vector will be set from ``width_min``, ``width_max``, and ``width_nstep``.', <type 'str'>), 'fix_background': (False, 'Fix any background parameters that are currently free in the model when performing the likelihood scan over extension.', <type 'bool'>), 'save_templates': (False, '', <type 'bool'>), 'width_max': (1.0, 'Maximum value in degrees for the likelihood scan over spatial extent.', <type 'float'>), 'width_min': (0.01, 'Minimum value in degrees for the likelihood scan over spatial extent.', <type 'float'>), 'spatial_model': ('GaussianSource', 'Spatial model use for extension test.', <type 'str'>), 'update': (False, 'Update the source model with the best-fit spatial extension.', <type 'bool'>), 'width_nstep': (21, 'Number of steps for the spatial likelihood scan.', <type 'int'>)}, 'sed': {'use_local_index': (False, 'Use a power-law approximation to the shape of the global spectrum in each bin. If this is false then a constant index set to `bin_index` will be used.', <type 'bool'>), 'bin_index': (2.0, 'Spectral index that will be use when fitting the energy distribution within an energy bin.', <type 'float'>), 'fix_background': (True, 'Fix background parameters when fitting the source flux in each energy bin.', <type 'bool'>), 'ul_confidence': (0.95, 'Confidence level for upper limit calculation.', <type 'float'>)}, 'fileio': {'workdir': (None, 'Override the working directory.', <type 'str'>), 'savefits': (True, 'Save intermediate FITS files.', <type 'bool'>), 'scratchdir': ('/scratch', 'Path to the scratch directory.', <type 'str'>), 'outdir': (None, 'Path of the output directory. If none this will default to the directory containing the configuration file.', <type 'str'>), 'logfile': (None, 'Path to log file. If None then log will be written to fermipy.log.', <type 'str'>), 'usescratch': (False, 'Run analysis in a temporary directory under ``scratchdir``.', <type 'bool'>)}, 'gtlike': {'irfs': (None, 'Set the IRF string.', <type 'str'>), 'minbinsz': (0.05, 'Set the minimum bin size used for resampling diffuse maps.', <type 'float'>), 'bexpmap': (None, '', <type 'str'>), 'edisp': (True, 'Enable the correction for energy dispersion.', <type 'bool'>), 'srcmap': (None, '', <type 'str'>), 'resample': (True, '', <type 'bool'>), 'convolve': (True, '', <type 'bool'>), 'rfactor': (2, '', <type 'int'>), 'edisp_disable': (None, 'Provide a list of sources for which the edisp correction should be disabled.', <type 'list'>)}, 'residmap': {'model': (None, 'Dictionary defining the properties of the test source. By default the test source will be a PointSource with an Index 2 power-law specturm.', <type 'dict'>), 'erange': (None, 'Lower and upper energy bounds in log10(E/MeV). By default the calculation will be performed over the full analysis energy range.', <type 'list'>)}, 'optimizer': {'retries': (3, 'Set the number of times to retry the fit when the fit quality is less than ``min_fit_quality``.', <type 'int'>), 'verbosity': (0, '', <type 'int'>), 'optimizer': ('MINUIT', 'Set the optimization algorithm to use when maximizing the likelihood function.', <type 'str'>), 'min_fit_quality': (3, 'Set the minimum fit quality.', <type 'int'>), 'tol': (0.0001, 'Set the optimizer tolerance.', <type 'float'>)}, 'model': {'catalogs': (None, '', <type 'list'>), 'limbdiff': (None, '', <type 'list'>), 'src_radius_roi': (None, 'Half-width of the ROI selection. This parameter can be used in lieu of src_roiwidth.', <type 'float'>), 'extdir': ('Extended_archive_v15', '', <type 'str'>), 'sources': (None, '', <type 'list'>), 'assoc_xmatch_columns': (['3FGL_Name'], 'Choose a set of association columns on which to cross-match catalogs.', <type 'list'>), 'diffuse': (None, '', <type 'list'>), 'src_roiwidth': (None, 'Select sources within a box of RxR centered on the ROI. If none then no cut is applied.', <type 'float'>), 'isodiff': (None, 'Set the isotropic template.', <type 'list'>), 'merge_sources': (True, 'Merge properties of sources that appear in multiple source catalogs. If merge_sources=false then subsequent sources with the same name will be ignored.', <type 'bool'>), 'extract_diffuse': (False, 'Extract a copy of all mapcube components centered on the ROI.', <type 'bool'>), 'src_radius': (None, 'Set the maximum distance for inclusion of sources in the ROI model. Selects all sources within a circle of this radius centered on the ROI. If none then no selection is applied. This selection will be ORed with sources passing the cut on src_roiwidth.', <type 'float'>), 'galdiff': (None, 'Set the galactic IEM mapcube.', <type 'list'>)}, 'data': {'evfile': (None, 'Path to FT1 file or list of FT1 files.', <type 'str'>), 'scfile': (None, 'Path to FT2 (spacecraft) file.', <type 'str'>), 'ltcube': (None, 'Path to livetime cube. If none a livetime cube will be generated with ``gtmktime``.', <type 'str'>)}, 'plotting': {'graticule_radii': (None, 'Define a list of radii at which circular graticules will be drawn.', <type 'list'>), 'erange': (None, '', <type 'list'>), 'cmap': ('ds9_b', 'Set the colormap for 2D plots.', <type 'str'>), 'catalogs': (None, '', <type 'list'>), 'format': ('png', '', <type 'str'>)}, 'tscube': {'do_sed': (True, 'Compute the energy bin-by-bin fits', <type 'bool'>), 'remake_test_source': (False, 'If true, recomputes the test source image (otherwise just shifts it)', <type 'bool'>), 'st_scan_level': (0, 'Level to which to do ST-based fitting (for testing)', <type 'int'>), 'cov_scale': (-1.0, 'Scale factor to apply to broadband fitting cov. matrix in bin-by-bin fits ( < 0 -> fixed ) ', <type 'float'>), 'max_iter': (30, 'Maximum number of iterations for the Newtons method fitter.', <type 'int'>), 'nnorm': (10, 'Number of points in the likelihood v. normalization scan', <type 'int'>), 'norm_sigma': (5.0, 'Number of sigma to use for the scan range ', <type 'float'>), 'tol_type': (0, 'Absoulte (0) or relative (1) criteria for convergence.', <type 'int'>), 'cov_scale_bb': (-1.0, 'Scale factor to apply to global fitting cov. matrix in broadband fits. ( < 0 -> no prior ) ', <type 'float'>), 'tol': (0.001, 'Critetia for fit convergence (estimated vertical distance to min < tol )', <type 'float'>), 'model': (None, 'Dictionary defining the properties of the test source. By default the test source will be a PointSource with an Index 2 power-law specturm.', <type 'dict'>)}}

delete_source(name, save_template=True, delete_source_map=False, **kwargs)

Delete a source from the model.

Parameters:name (str) – Source name. Returns:src – The deleted source object. Return type:Model

delete_sources(cuts=None, distance=None, minmax_ts=None, minmax_npred=None, square=False)

Delete sources in the ROI model satisfying the given selection criteria.

Returns:srcs – A list of Model objects. Return type:list

energies

Return the energy bin edges.

enumbins

Return the number of energy bins.

erange

extension(name, **kwargs)

Test this source for spatial extension with the likelihood ratio method (TS_ext). This method will substitute an extended spatial model for the given source and perform a one-dimensional scan of the spatial extension parameter over the range specified with the width parameters. The 1-D profile likelihood is then used to compute the best-fit value, upper limit, and TS for extension. Any background parameters that are free will also be simultaneously profiled in the likelihood scan.

Parameters:

• name (str) – Source name.
• spatial_model (str) – Spatial model that will be used when testing extension (e.g. DiskSource, GaussianSource).
• width_min (float) – Minimum value in degrees for the spatial extension scan.
• width_max (float) – Maximum value in degrees for the spatial extension scan.
• width_nstep (int) – Number of scan points between width_min and width_max. Scan points will be spaced evenly on a logarithmic scale between log(width_min) and log(width_max).
• width (array-like) – Sequence of values in degrees for the spatial extension scan. If this argument is None then the scan points will be determined from width_min/width_max/width_nstep.
• fix_background (bool) – Fix all background sources when performing the extension fit.
• update (bool) – Update this source with the best-fit model for spatial extension.
• save_model_map (bool) – Save model maps for all steps in the likelihood scan.

Returns:

extension – Dictionary containing results of the extension analysis. The same dictionary is also saved to the dictionary of this source under ‘extension’.

Return type:

dict

find_sources(prefix='', **kwargs)

An iterative source-finding algorithm.

Parameters:

• model (dict) – Dictionary defining the properties of the test source. This is the model that will be used for generating TS maps.
• sqrt_ts_threshold (float) – Source threshold in sqrt(TS). Only peaks with sqrt(TS) exceeding this threshold will be used as seeds for new sources.
• min_separation (float) – Minimum separation in degrees of sources detected in each iteration. The source finder will look for the maximum peak in the TS map within a circular region of this radius.
• max_iter (int) – Maximum number of source finding iterations. The source finder will continue adding sources until no additional peaks are found or the number of iterations exceeds this number.
• sources_per_iter (int) – Maximum number of sources that will be added in each iteration. If the number of detected peaks in a given iteration is larger than this number, only the N peaks with the largest TS will be used as seeds for the current iteration.
• tsmap_fitter (str) –

  Set the method used internally for generating TS maps. Valid options:

  • tsmap
  • tscube
• tsmap (dict) – Keyword arguments dictionary for tsmap method.
• tscube (dict) – Keyword arguments dictionary for tscube method.

fit(update=True, **kwargs)

Run the likelihood optimization. This will execute a fit of all parameters that are currently free in the ROI model and update the charateristics (TS, Npred, etc.) of the corresponding model components. The fit will be repeated N times (set with the retries parameter) until a fit quality of 3 is obtained.

Parameters:

• update (bool) – Do not update the ROI model.
• tol (float) – Set the optimizer tolerance.
• verbosity (int) – Set the optimizer output level.
• retries (int) – Set the number of times to rerun the fit when the fit quality is < 3.
• min_fit_quality (int) – Set the minimum fit quality. If the fit quality is smaller than this value then all model parameters will be restored to their values prior to the fit.
• reoptimize (bool) – Refit background sources when updating source properties (TS and likelihood profiles).

Returns:

fit – Dictionary containing diagnostic information for the fit (fit quality, parameter covariances, etc.).

Return type:

dict

free_index(name, free=True)

Free/Fix index of a source.

Parameters:

• name (str) – Source name.
• free (bool) – Choose whether to free (free=True) or fix (free=False).

free_norm(name, free=True)

Free/Fix normalization of a source.

Parameters:

• name (str) – Source name.
• free (bool) – Choose whether to free (free=True) or fix (free=False).

free_parameter(name, par, free=True)

free_shape(name, free=True)

Free/Fix shape parameters of a source.

Parameters:

• name (str) – Source name.
• free (bool) – Choose whether to free (free=True) or fix (free=False).

free_source(name, free=True, pars=None)

Free/Fix parameters of a source.

Parameters:

• name (str) – Source name.
• free (bool) – Choose whether to free (free=True) or fix (free=False) source parameters.
• pars (list) – Set a list of parameters to be freed/fixed for this source. If none then all source parameters will be freed/fixed with the exception of those defined in the skip_pars list.

free_sources(free=True, pars=None, cuts=None, distance=None, minmax_ts=None, minmax_npred=None, square=False, exclude_diffuse=False)

Free or fix sources in the ROI model satisfying the given selection. When multiple selections are defined, the selected sources will be those satisfying the logical AND of all selections (e.g. distance < X && minmax_ts[0] < ts < minmax_ts[1] && ...).

Parameters:

• free (bool) – Choose whether to free (free=True) or fix (free=False) source parameters.
• pars (list) – Set a list of parameters to be freed/fixed for this source. If none then all source parameters will be freed/fixed. If pars=’norm’ then only normalization parameters will be freed.
• cuts (dict) – Dictionary of [min,max] selections on source properties.
• distance (float) – Distance out to which sources should be freed or fixed. If this parameter is none no selection will be applied.
• minmax_ts (list) – Free sources that have TS in the range [min,max]. If either min or max are None then only a lower (upper) bound will be applied. If this parameter is none no selection will be applied.
• minmax_npred (list) – Free sources that have Npred in the range [min,max]. If either min or max are None then only a lower (upper) bound will be applied. If this parameter is none no selection will be applied.
• square (bool) – Switch between applying a circular or square (ROI-like) selection on the maximum projected distance from the ROI center.
• exclude_diffuse (bool) – Exclude diffuse sources.

Returns:

srcs – A list of Model objects.

Return type:

list

free_sources_by_position(free=True, pars=None, distance=None, square=False)

Free/Fix all sources within a certain distance of the given sky coordinate. By default it will use the ROI center.

Parameters:

• free (bool) – Choose whether to free (free=True) or fix (free=False) source parameters.
• pars (list) – Set a list of parameters to be freed/fixed for this source. If none then all source parameters will be freed/fixed. If pars=’norm’ then only normalization parameters will be freed.
• distance (float) – Distance in degrees out to which sources should be freed or fixed. If none then all sources will be selected.
• square (bool) – Apply a square (ROI-like) selection on the maximum distance in either X or Y in projected cartesian coordinates.

Returns:

srcs – A list of Source objects.

Return type:

list

generate_model(model_name=None)

Generate model maps for all components. model_name should be a unique identifier for the model. If model_name is None then the model maps will be generated using the current parameters of the ROI.

generate_model_map(model_name, name=None)

Parameters:

• model_name (str) – String that will be append to the name of the output file.
• name (str) – Name of the component.

get_free_params()

get_free_source_params(name)

get_model_map(name=None)

get_source_name(name)

Return the name of a source as it is defined in the pyLikelihood model object.

get_sources(cuts=None, distance=None, minmax_ts=None, minmax_npred=None, square=False)

Retrieve list of sources in the ROI model satisfying the given selections.

Returns:srcs – A list of Model objects. Return type:list

get_src_model(name, paramsonly=False, reoptimize=False, npts=20)

Compose a dictionary for the given source with the current best-fit parameters.

Parameters:

• name (str) –
• paramsonly (bool) –
• reoptimize (bool) – Re-fit background parameters in likelihood scan.
• npts (int) – Number of points for likelihood scan.

like

Return the global likelihood object.

load_roi(infile)

This function reloads the analysis state from a previously saved instance generated with write_roi.

load_xml(xmlfile)

Load model definition from XML.

localize(name, **kwargs)

Find the best-fit position of a source. Localization is performed in two steps. First a TS map is computed centered on the source with half-width set by dtheta_max. A fit is then performed to the maximum TS peak in this map. The source position is then further refined by scanning the likelihood in the vicinity of the peak found in the first step. The size of the scan region is set to encompass the 99% positional uncertainty contour as determined from the peak fit.

Parameters:

• name (str) – Source name.
• dtheta_max (float) – Maximum offset in RA/DEC in deg from the nominal source position that will be used to define the boundaries of the TS map search region.
• nstep (int) – Number of steps in longitude/latitude that will be taken when refining the source position. The bounds of the scan range are set to the 99% positional uncertainty as determined from the TS map peak fit. The total number of sampling points will be nstep**2.
• fix_background (bool) – Fix background parameters when fitting the source position.
• update (bool) – Update the model for this source with the best-fit position. If newname=None this will overwrite the existing source map of this source with one corresponding to its new location.
• newname (str) – Name that will be assigned to the relocalized source when update=True. If newname is None then the existing source name will be used.

Returns:

localize – Dictionary containing results of the localization analysis. This dictionary is also saved to the dictionary of this source in ‘localize’.

Return type:

dict

make_plots(prefix, mcube_maps, **kwargs)

model_counts_map(name=None, exclude=None)

Return the model counts map for a single source, a list of sources, or for the sum of all sources in the ROI. The exclude parameter can be used to exclude one or more components when generating the model map.

Parameters:

• name (str or list of str) – Parameter controlling the set of sources for which the model counts map will be calculated. If name=None the model map will be generated for all sources in the ROI.
• exclude (str or list of str) – List of sources that will be excluded when calculating the model map.

Returns:

maps – A list of Map objects.

Return type:

list

model_counts_spectrum(name, emin=None, emax=None, summed=False)

Return the predicted number of model counts versus energy for a given source and energy range. If summed=True return the counts spectrum summed over all components otherwise return a list of model spectra.

npix

Return the number of energy bins.

optimize(**kwargs)

Iteratively optimize the ROI model. The optimization is performed in three sequential steps:

• Free the normalization of the N largest components (as determined from NPred) that contain a fraction npred_frac of the total predicted counts in the model and perform a simultaneous fit of the normalization parameters of these components.
• Individually fit the normalizations of all sources that were not included in the first step in order of their Npred values. Skip any sources that have NPred < npred_threshold.
• Individually fit the shape and normalization parameters of all sources with TS > shape_ts_threshold where TS is determined from the first two steps of the ROI optimization.

To ensure that the model is fully optimized this method can be run multiple times.

Parameters:

• npred_frac (float) – Threshold on the fractional number of counts in the N largest components in the ROI. This parameter determines the set of sources that are fit in the first optimization step.
• npred_threshold (float) – Threshold on the minimum number of counts of individual sources. This parameter determines the sources that are fit in the second optimization step.
• shape_ts_threshold (float) – Threshold on source TS used for determining the sources that will be fit in the third optimization step.

print_model()

print_roi()

profile(name, parName, emin=None, emax=None, reoptimize=False, xvals=None, npts=None, savestate=True)

Profile the likelihood for the given source and parameter.

profile_norm(name, emin=None, emax=None, reoptimize=False, xvals=None, npts=20, savestate=True)

Profile the normalization of a source.

Parameters:

• name (str) – Source name.
• reoptimize (bool) – Re-optimize all free parameters in the model at each point in the profile likelihood scan.

projtype

Return the type of projection to use

reload_source(name)

Delete and reload a source in the model. This will refresh the spatial model of this source to the one defined in the XML model.

residmap(prefix='', **kwargs)

Generate 2-D spatial residual maps using the current ROI model and the convolution kernel defined with the model argument.

Parameters:

• prefix (str) – String that will be prefixed to the output residual map files.
• model (dict) – Dictionary defining the properties of the convolution kernel.
• exclude (str or list of str) – Source or sources that will be removed from the model when computing the residual map.
• erange (list) – Restrict the analysis to an energy range (emin,emax) in log10(E/MeV) that is a subset of the analysis energy range. By default the full analysis energy range will be used. If either emin/emax are None then only an upper/lower bound on the energy range wil be applied.
• make_plots (bool) – Write image files.
• make_fits (bool) – Write FITS files.

Returns:

maps – A dictionary containing the Map objects for the residual significance and amplitude.

Return type:

dict

restore_counts_maps()

Revert counts maps to their state prior to injecting any simulated components.

roi

Return the ROI object.

scale_parameter(name, par, scale)

sed(name, profile=True, energies=None, **kwargs)

Generate an SED for a source. This function will fit the normalization of a given source in each energy bin.

Parameters:

• name (str) – Source name.
• profile (bool) – Profile the likelihood in each energy bin.
• energies (ndarray) – Sequence of energies in log10(E/MeV) defining the edges of the energy bins. If this argument is None then the analysis energy bins will be used. The energies in this sequence must align with the bin edges of the underyling analysis instance.
• bin_index (float) – Spectral index that will be use when fitting the energy distribution within an energy bin.
• use_local_index (bool) – Use a power-law approximation to the shape of the global spectrum in each bin. If this is false then a constant index set to bin_index will be used.
• fix_background (bool) – Fix background components when fitting the flux normalization in each energy bin. If fix_background=False then all background parameters that are currently free in the fit will be profiled. By default fix_background=True.
• ul_confidence (float) – Set the confidence level that will be used for the calculation of flux upper limits in each energy bin.

Returns:

sed – This dictionary is also saved to the ‘sed’ dictionary of the Source instance.

Return type:

dict Dictionary containing output of the SED analysis.

setEnergyRange(emin, emax)

Set the energy range of the analysis.

set_edisp_flag(name, flag=True)

Enable or disable the energy dispersion correction for the given source.

set_free_params(free)

set_log_level(level)

set_norm(name, value)

set_norm_scale(name, value)

set_parameter(name, par, value, true_value=True, scale=None, bounds=None, update_source=True)

set_parameter_bounds(name, par, bounds)

Set the bounds of a parameter.

Parameters:

• name (str) – Source name.
• par (str) – Parameter name.
• bounds (list) – Upper and lower bound.

setup(init_sources=True, overwrite=False)

Run pre-processing for each analysis component and construct a joint likelihood object. This function performs the following tasks: data selection (gtselect, gtmktime), data binning (gtbin), and model generation (gtexpcube2,gtsrcmaps).

Parameters:

• init_sources (bool) – Choose whether to compute properties (flux, TS, etc.) for individual sources.
• overwrite (bool) – Run all pre-processing steps even if the output file of that step is present in the working directory. By default this function will skip any steps for which the output file already exists.

simulate_roi()

Perform a simulation of the whole ROI. This will replace the current counts cube with a simulated realization of the current model. The counts cube can be restored to its original state by calling restore_counts_maps.

simulate_source(src_dict=None)

Inject a simulated source into the ROI.

Parameters:src_dict (dict) –

stage_input()

Copy data products to intermediate working directory.

stage_output()

Copy data products to final output directory.

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.
• make_fits (bool) – Write FITS files.

Returns:

maps – A dictionary containing the Map objects for TS and source amplitude.

Return type:

dict

tsmap(prefix='', **kwargs)

Generate a spatial TS map for a source component with properties defined by the model argument. The TS map will have the same geometry as the ROI. 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.

This method uses a simplified likelihood fitting implementation that only fits for the normalization of the test source. Before running this method it is recommended to first optimize the ROI model (e.g. by running optimize()).

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.
• exclude (str or list of str) – Source or sources that will be removed from the model when computing the TS map.
• erange (list) – Restrict the analysis to an energy range (emin,emax) in log10(E/MeV) that is a subset of the analysis energy range. By default the full analysis energy range will be used. If either emin/emax are None then only an upper/lower bound on the energy range wil be applied.
• max_kernel_radius (float) – Set the maximum radius of the test source kernel. Using a smaller value will speed up the TS calculation at the loss of accuracy. The default value is 3 degrees.
• make_plots (bool) – Write image files.
• make_fits (bool) – Write FITS files.

Returns:

maps – A dictionary containing the Map objects for TS and source amplitude.

Return type:

dict

unzero_source(name)

update_source(name, paramsonly=False, reoptimize=False, npts=20)

Update the dictionary for this source.

Parameters:

• name (str) –
• paramsonly (bool) –
• reoptimize (bool) – Re-fit background parameters in likelihood scan.
• npts (int) – Number of points for likelihood scan.

workdir

Return the analysis working directory.

write_roi(outfile=None, make_residuals=False, make_tsmap=False, save_model_map=True, format=None, **kwargs)

Write current model to a file. This function will write an XML model file and an ROI dictionary in both YAML and npy formats.

Parameters:

• outfile (str) – Name of the output file. The extension of this string will be stripped when generating the XML, YAML and Numpy filenames.
• make_residuals (bool) – Run residual analysis.
• save_model_map (bool) – Save the current counts model as a FITS file.
• format (str) – Set the output file format (yaml or npy).

write_xml(xmlfile)

Save current model definition as XML file.

Parameters:xmlfile (str) – Name of the output XML file.

zero_source(name)

fermipy.logger module

class fermipy.logger.Logger

Bases: object

This class provides helper functions which facilitate creating instances of the built-in logger class.

static get(name, logfile, loglevel=10)

static setup(config=None, logfile=None)

This method sets up the default configuration of the logger. Once this method is called all subsequent instances Logger instances will inherit this configuration.

class fermipy.logger.StreamLogger(name='stdout', logfile=None, quiet=True)

Bases: object

File-like object to log stdout/stderr using the logging module.

close()

flush()

write(msg, level=10)

fermipy.logger.logLevel(level)

This is a function that returns a python like level from a HEASOFT like level.

fermipy.roi_model module

class fermipy.roi_model.Catalog(table, extdir='')

Bases: object

Source catalog object. This class provides a simple wrapper around FITS catalog tables.

static create(name)

glonlat

radec

skydir

table

Return the Table representation of this catalog.

class fermipy.roi_model.Catalog2FHL(fitsfile=None, extdir=None)

Bases: fermipy.roi_model.Catalog

class fermipy.roi_model.Catalog3FGL(fitsfile=None, extdir=None)

Bases: fermipy.roi_model.Catalog

class fermipy.roi_model.IsoSource(name, data)

Bases: fermipy.roi_model.Model

diffuse

filefunction

write_xml(root)

class fermipy.roi_model.MapCubeSource(name, data)

Bases: fermipy.roi_model.Model

diffuse

mapcube

write_xml(root)

class fermipy.roi_model.Model(name, data=None)

Bases: object

Base class for source objects. This class is a container for both spectral and spatial parameters as well as other source properties such as TS, Npred, and location within the ROI.

add_name(name)

assoc

check_cuts(cuts)

static create_from_dict(src_dict)

data

get_norm()

items()

name

names

params

set_name(name, names=None)

set_spectral_pars(spectral_pars)

spatial_pars

spectral_pars

update_data(d)

update_from_source(src)

class fermipy.roi_model.PowerLaw(phi0, x0, index)

Bases: object

dfde(x)

static eval_dfde(x, phi0, x0, index)

static eval_flux(phi0, x0, index, xmin, xmax)

static eval_norm(x0, index, xmin, xmax, flux)

params

class fermipy.roi_model.ROIModel(config=None, **kwargs)

Bases: fermipy.config.Configurable

This class is responsible for managing the ROI model (both sources and diffuse emission components). Source catalogs can be read from either FITS or XML files. Individual components are represented by instances of Model and can be accessed by name using the bracket operator.

• Create an ROI with all 3FGL sources and print a summary of its contents:

>>> skydir = astropy.coordinates.SkyCoord(0.0,0.0,unit='deg')
>>> roi = ROIModel({'catalogs' : ['3FGL'],'src_roiwidth' : 10.0},skydir=skydir)
>>> print roi
name                SpatialModel   SpectrumType     offset        ts       Npred
--------------------------------------------------------------------------------
3FGL J2357.3-0150   PointSource    PowerLaw          1.956       nan         0.0
3FGL J0006.2+0135   PointSource    PowerLaw          2.232       nan         0.0
3FGL J0016.3-0013   PointSource    PowerLaw          4.084       nan         0.0
3FGL J0014.3-0455   PointSource    PowerLaw          6.085       nan         0.0

• Print a summary of an individual source

>>> print roi['3FGL J0006.2+0135']

• Get the SkyCoord for a source

>>> dir = roi['SourceA'].skydir

• Loop over all sources and print their names

>>> for s in roi.sources: print s.name

clear()

Clear the contents of the ROI.

copy_source(name)

static create(selection, config, **kwargs)

Create an ROIModel instance.

static create_from_position(skydir, config, **kwargs)

Create an ROIModel instance centered on a sky direction.

Parameters:

• skydir (SkyCoord) – Sky direction on which the ROI will be centered.
• config (dict) – Model configuration dictionary.

static create_from_roi_data(datafile)

Create an ROI model.

static create_from_source(name, config, **kwargs)

Create an ROI centered on the given source.

static create_roi_from_ft1(ft1file, config)

Create an ROI model by extracting the sources coordinates form an FT1 file.

create_source(name, src_dict, build_index=True, merge_sources=True)

Add a new source to the ROI model from a dictionary or an existing source object.

Parameters:

• name (str) –
• src_dict (dict or Source) –

Returns:

src

Return type:

Source

defaults = {'logfile': (None, '', <type 'str'>), 'catalogs': (None, '', <type 'list'>), 'src_roiwidth': (None, 'Select sources within a box of RxR centered on the ROI. If none then no cut is applied.', <type 'float'>), 'limbdiff': (None, '', <type 'list'>), 'src_radius_roi': (None, 'Half-width of the ROI selection. This parameter can be used in lieu of src_roiwidth.', <type 'float'>), 'extract_diffuse': (False, 'Extract a copy of all mapcube components centered on the ROI.', <type 'bool'>), 'galdiff': (None, 'Set the galactic IEM mapcube.', <type 'list'>), 'extdir': ('Extended_archive_v15', '', <type 'str'>), 'sources': (None, '', <type 'list'>), 'fileio': {'workdir': (None, 'Override the working directory.', <type 'str'>), 'savefits': (True, 'Save intermediate FITS files.', <type 'bool'>), 'scratchdir': ('/scratch', 'Path to the scratch directory.', <type 'str'>), 'outdir': (None, 'Path of the output directory. If none this will default to the directory containing the configuration file.', <type 'str'>), 'logfile': (None, 'Path to log file. If None then log will be written to fermipy.log.', <type 'str'>), 'usescratch': (False, 'Run analysis in a temporary directory under ``scratchdir``.', <type 'bool'>)}, 'logging': {'verbosity': (3, '', <type 'int'>), 'chatter': (3, 'Set the chatter parameter of the STs.', <type 'int'>)}, 'isodiff': (None, 'Set the isotropic template.', <type 'list'>), 'merge_sources': (True, 'Merge properties of sources that appear in multiple source catalogs. If merge_sources=false then subsequent sources with the same name will be ignored.', <type 'bool'>), 'assoc_xmatch_columns': (['3FGL_Name'], 'Choose a set of association columns on which to cross-match catalogs.', <type 'list'>), 'diffuse': (None, '', <type 'list'>), 'src_radius': (None, 'Set the maximum distance for inclusion of sources in the ROI model. Selects all sources within a circle of this radius centered on the ROI. If none then no selection is applied. This selection will be ORed with sources passing the cut on src_roiwidth.', <type 'float'>)}

delete_sources(srcs)

diffuse_sources

get_nearby_sources(name, dist, min_dist=None, square=False)

get_source_by_name(name, unique=False)

Return a source in the ROI by name. The input name string can match any of the strings in the names property of the source object. Case and whitespace are ignored when matching name strings.

Parameters:

• name (str) –
• unique (bool) – Require a unique match. If more than one source exists with this name an exception is raised.

get_sources(cuts=None, distance=None, minmax_ts=None, minmax_npred=None, square=False, exclude_diffuse=False, coordsys='CEL')

Retrieve list of sources satisfying the given selections.

Returns:srcs – List of source objects. Return type:list

get_sources_by_position(skydir, dist, min_dist=None, square=False, coordsys='CEL')

Retrieve sources within a certain angular distance of a sky coordinate. This function supports two types of geometric selections: circular (square=False) and square (square=True). The circular selection finds all sources with a given angular distance of the target position. The square selection finds sources within an ROI-like region of size R x R where R = 2 x dist.

Parameters:

• skydir (SkyCoord) – Sky direction with respect to which the selection will be applied.
• dist (float) – Maximum distance in degrees from the sky coordinate.
• square (bool) – Choose whether to apply a circular or square selection.
• coordsys (str) – Coordinate system to use when applying a selection with square=True.

get_sources_by_property(pname, pmin, pmax=None)

has_source(name)

load(**kwargs)

Load both point source and diffuse components.

load_diffuse_srcs()

load_fits_catalog(name, **kwargs)

Load sources from a FITS catalog file.

Parameters:name (str) – Catalog name or path to a catalog FITS file.

load_source(src, build_index=True, merge_sources=True, **kwargs)

Load a single source.

Parameters:

• src (Source) – Source object that will be added to the ROI.
• merge_sources (bool) – When a source matches an existing source in the model update that source with the properties of the new source.
• build_index (bool) – Re-make the source index after loading this source.

load_sources(sources)

Delete all sources in the ROI and load the input source list.

load_xml(xmlfile, **kwargs)

Load sources from an XML file.

match_source(src)

Look for source or sources in the model that match the given source. Sources are matched by name and any association columns defined in the assoc_xmatch_columns parameter.

point_sources

skydir

Return the sky direction objection corresponding to the center of the ROI.

sources

src_name_cols = ['Source_Name', 'ASSOC', 'ASSOC1', 'ASSOC2', 'ASSOC_GAM', '1FHL_Name', '2FGL_Name', '3FGL_Name', 'ASSOC_GAM1', 'ASSOC_GAM2', 'ASSOC_TEV']

write_xml(xmlfile)

Save this ROI model as an XML file.

class fermipy.roi_model.Source(name, data=None, radec=None)

Bases: fermipy.roi_model.Model

Class representation of a source (non-diffuse) model component. A source object serves as a container for the properties of that source (position, spatial/spectral parameters, TS, etc.) as derived in the current analysis. Most properties of a source object can be accessed with the bracket operator:

# Return the TS of this source >>> print src[‘ts’]

# Get a skycoord representation of the source position >>> print src.skydir

associations

static create_from_dict(src_dict)

Create a source object from a python dictionary.

static create_from_xml(root, extdir=None)

Create a Source object from an XML node.

data

diffuse

extended

load_from_catalog()

Load spectral parameters from catalog values.

radec

separation(src)

set_position(skydir)

Set the position of the source.

Parameters:skydir (SkyCoord) –

set_roi_direction(roidir)

set_spatial_model(spatial_model, spatial_width=None)

skydir

Return a SkyCoord representation of the source position.

Returns:skydir Return type:SkyCoord

update_data(d)

write_xml(root)

Write this source to an XML node.

fermipy.roi_model.add_columns(t0, t1)

Add columns of table t1 to table t0.

fermipy.roi_model.create_model_name(src)

fermipy.roi_model.get_dist_to_edge(skydir, lon, lat, width, coordsys='CEL')

fermipy.roi_model.get_linear_dist(skydir, lon, lat, coordsys='CEL')

fermipy.roi_model.get_skydir_distance_mask(src_skydir, skydir, dist, min_dist=None, square=False, coordsys='CEL')

Retrieve sources within a certain angular distance of an (ra,dec) coordinate. This function supports two types of geometric selections: circular (square=False) and square (square=True). The circular selection finds all sources with a given angular distance of the target position. The square selection finds sources within an ROI-like region of size R x R where R = 2 x dist.

Parameters:

• src_skydir (SkyCoord) – Array of sky directions.
• skydir (SkyCoord) – Sky direction with respect to which the selection will be applied.
• dist (float) – Maximum distance in degrees from the sky coordinate.
• square (bool) – Choose whether to apply a circular or square selection.
• coordsys (str) – Coordinate system to use when applying a selection with square=True.

fermipy.roi_model.join_tables(t0, t1, key0, key1)

fermipy.roi_model.lonlat_to_xyz(lon, lat)

fermipy.roi_model.make_parameter_dict(pdict, fixed_par=False)

fermipy.roi_model.project(lon0, lat0, lon1, lat1)

This function performs a stereographic projection on the unit vector (lon1,lat1) with the pole defined at the reference unit vector (lon0,lat0).

fermipy.roi_model.resolve_file_path(path, **kwargs)

fermipy.roi_model.row_to_dict(row)

fermipy.roi_model.scale_parameter(p)

fermipy.roi_model.strip_columns(t)

fermipy.roi_model.xyz_to_lonlat(*args)

fermipy.utils module

class fermipy.utils.Map(counts, wcs)

Bases: fermipy.utils.Map_Base

Representation of a 2D or 3D counts map using WCS.

static create_from_fits(fitsfile, **kwargs)

static create_from_hdu(hdu, wcs)

create_image_hdu(name=None)

create_primary_hdu()

ipix_swap_axes(ipix, colwise=False)

Return the transposed pixel index from the pixel xy coordinates

if colwise is True (False) this assumes the original index was in column wise scheme

ipix_to_xypix(ipix, colwise=False)

Return the pixel xy coordinates from the pixel index

if colwise is True (False) this uses columnwise (rowwise) indexing

pix_center

Return the ROI center in pixel coordinates.

pix_size

Return the pixel size along the two image dimensions.

skydir

Return the sky coordinate of the Map center.

sum_over_energy()

Reduce a 3D counts cube to a 2D counts map

wcs

width

Return the sky coordinate of the Map center.

xy_pix_to_ipix(xypix, colwise=False)

Return the pixel index from the pixel xy coordinates

if colwise is True (False) this uses columnwise (rowwise) indexing

class fermipy.utils.Map_Base(counts)

Bases: object

Abstract representation of a 2D or 3D counts map.

counts

fermipy.utils.apply_minmax_selection(val, val_minmax)

fermipy.utils.cl_to_dlnl(cl)

Compute the delta-log-likehood corresponding to an upper limit of the given confidence level.

fermipy.utils.convolve2d_disk(fn, r, sig, nstep=200)

Evaluate the convolution f’(r) = f(r) * g(r) where f(r) is azimuthally symmetric function in two dimensions and g is a step function given by:

g(r) = H(1-r/s)

Parameters:

• fn (function) – Input function that takes a single radial coordinate parameter.
• r (ndarray) – Array of points at which the convolution is to be evaluated.
• sig (float) – Radius parameter of the step function.
• nstep (int) – Number of sampling point for numeric integration.

fermipy.utils.convolve2d_gauss(fn, r, sig, nstep=200)

Evaluate the convolution f’(r) = f(r) * g(r) where f(r) is azimuthally symmetric function in two dimensions and g is a gaussian given by:

g(r) = 1/(2*pi*s^2) Exp[-r^2/(2*s^2)]

Parameters:

• fn (function) – Input function that takes a single radial coordinate parameter.
• r (ndarray) – Array of points at which the convolution is to be evaluated.
• sig (float) – Width parameter of the gaussian.
• nstep (int) – Number of sampling point for numeric integration.

fermipy.utils.create_hpx_disk_region_string(skyDir, coordsys, radius, inclusive=0)

fermipy.utils.create_model_name(src)

Generate a name for a source object given its spatial/spectral properties.

Parameters:src (Source) – A source object. Returns:name – A source name. Return type:str

fermipy.utils.create_source_name(skydir)

fermipy.utils.create_wcs(skydir, coordsys='CEL', projection='AIT', cdelt=1.0, crpix=1.0, naxis=2, energies=None)

Create a WCS object.

Parameters:skydir (SkyCoord) – Sky coordinate of the WCS reference point.

fermipy.utils.create_xml_element(root, name, attrib)

fermipy.utils.delete_source_map(srcmap_file, name, logger=None)

Delete a map from a binned analysis source map file if it exists.

Parameters:

• srcmap_file (str) – Path to the source map file.
• name (str) – HDU key of source map.

fermipy.utils.edge_to_center(edges)

fermipy.utils.edge_to_width(edges)

fermipy.utils.eq2gal(ra, dec)

fermipy.utils.extract_mapcube_region(infile, skydir, outfile, maphdu=0)

Extract a region out of an all-sky mapcube file.

Parameters:

• infile (str) – Path to mapcube file.
• skydir (SkyCoord) –

fermipy.utils.find_function_root(fn, x0, xb, delta)

Find the root of a function: f(x)+delta in the interval encompassed by x0 and xb.

Parameters:

• fn (function) – Python function.
• x0 (float) – Fixed bound for the root search. This will either be used as the lower or upper bound depending on the relative value of xb.
• xb (float) – Upper or lower bound for the root search. If a root is not found in the interval [x0,xb]/[xb,x0] this value will be increased/decreased until a change in sign is found.

fermipy.utils.fit_parabola(z, ix, iy, dpix=2, zmin=None)

fermipy.utils.fits_recarray_to_dict(table)

Convert a FITS recarray to a python dictionary.

fermipy.utils.format_filename(outdir, basename, prefix=None, extension=None)

fermipy.utils.gal2eq(l, b)

fermipy.utils.get_coordsys(wcs)

fermipy.utils.get_parameter_limits(xval, logLike, ul_confidence=0.95)

Compute upper/lower limits, peak position, and 1-sigma errors from a 1-D likelihood function.

Parameters:

• xval (ndarray) – Array of parameter values.
• logLike (ndarray) – Array of log-likelihood values.
• ul_confidence (float) – Confidence level to use for limit calculation.

fermipy.utils.get_target_skydir(config, default=None)

fermipy.utils.join_strings(strings, sep='_')

fermipy.utils.load_xml_elements(root, path)

fermipy.utils.make_cdisk_kernel(psf, sigma, npix, cdelt, xpix, ypix, normalize=False)

Make a kernel for a PSF-convolved 2D disk.

Parameters:

• psf (PSFModel) –
• sigma (float) – 68% containment radius in degrees.

fermipy.utils.make_cgauss_kernel(psf, sigma, npix, cdelt, xpix, ypix, normalize=False)

Make a kernel for a PSF-convolved 2D gaussian.

Parameters:

• psf (PSFModel) –
• sigma (float) – 68% containment radius in degrees.

fermipy.utils.make_cgauss_mapcube(skydir, psf, sigma, outfile, npix=500, cdelt=0.01, rebin=1)

fermipy.utils.make_disk_kernel(sigma, npix=501, cdelt=0.01, xpix=0.0, ypix=0.0)

Make kernel for a 2D disk.

Parameters:sigma (float) – Disk radius in deg.

fermipy.utils.make_disk_spatial_map(skydir, sigma, outfile, npix=501, cdelt=0.01)

fermipy.utils.make_gaussian_kernel(sigma, npix=501, cdelt=0.01, xpix=0.0, ypix=0.0)

Make kernel for a 2D gaussian.

Parameters:sigma (float) – 68% containment radius in degrees.

fermipy.utils.make_gaussian_spatial_map(skydir, sigma, outfile, npix=501, cdelt=0.01)

fermipy.utils.make_pixel_offset(npix, xpix=0.0, ypix=0.0)

Make a 2D array with the distance of each pixel from a reference direction in pixel coordinates. Pixel coordinates are defined such that (0,0) is located at the center of the coordinate grid.

fermipy.utils.make_psf_kernel(psf, npix, cdelt, xpix, ypix, normalize=False)

Generate a kernel for a point-source.

Parameters:

• psf (PSFModel) –
• npix (int) – Number of pixels in X and Y dimensions.
• cdelt (float) – Pixel size in degrees.

fermipy.utils.make_psf_mapcube(skydir, psf, outfile, npix=500, cdelt=0.01, rebin=1)

fermipy.utils.make_srcmap(skydir, psf, spatial_model, sigma, npix=500, xpix=0.0, ypix=0.0, cdelt=0.01, rebin=1)

Compute the source map for a given spatial model.

Parameters:

• xpix (float) –
• ypix (float) –

fermipy.utils.merge_dict(d0, d1, add_new_keys=False, append_arrays=False)

Recursively merge the contents of python dictionary d0 with the contents of another python dictionary, d1.

add_new_keys : Do not skip keys that only exist in d1.

append_arrays : If an element is a numpy array set the value of that element by concatenating the two arrays.

fermipy.utils.mkdir(dir)

fermipy.utils.offset_to_sky(skydir, offset_lon, offset_lat, coordsys='CEL', projection='AIT')

Convert a cartesian offset (X,Y) in the given projection into a spherical coordinate.

fermipy.utils.offset_to_skydir(skydir, offset_lon, offset_lat, coordsys='CEL', projection='AIT')

Convert a cartesian offset (X,Y) in the given projection into a spherical coordinate.

fermipy.utils.parabola((x, y), amplitude, x0, y0, sx, sy, theta)

fermipy.utils.pix_to_skydir(xpix, ypix, wcs)

Convert pixel coordinates to a skydir object.

fermipy.utils.poly_to_parabola(coeff)

fermipy.utils.prettify_xml(elem)

Return a pretty-printed XML string for the Element.

fermipy.utils.read_energy_bounds(hdu)

Reads and returns the energy bin edges from a FITs HDU

fermipy.utils.read_spectral_data(hdu)

Reads and returns the energy bin edges, fluxes and npreds from a FITs HDU

fermipy.utils.rebin_map(k, nebin, npix, rebin)

fermipy.utils.sky_to_offset(skydir, lon, lat, coordsys='CEL', projection='AIT')

Convert sky coordinates to a projected offset. This function is the inverse of offset_to_sky.

fermipy.utils.skydir_to_pix(skydir, wcs)

Convert skydir object to pixel coordinates.

fermipy.utils.tolist(x)

convenience function that takes in a nested structure of lists and dictionaries and converts everything to its base objects. This is useful for dupming a file to yaml.

1. numpy arrays into python lists

   >>> type(tolist(np.asarray(123))) == int
   True
   >>> tolist(np.asarray([1,2,3])) == [1,2,3]
   True
   

2. numpy strings into python strings.

   >>> tolist([np.asarray('cat')])==['cat']
   True
   

3. an ordered dict to a dict

   >>> ordered=OrderedDict(a=1, b=2)
   >>> type(tolist(ordered)) == dict
   True
   

4. converts unicode to regular strings

   >>> type(u'a') == str
   False
   >>> type(tolist(u'a')) == str
   True
   

5. converts numbers & bools in strings to real represntation, (i.e. ‘123’ -> 123)

   >>> type(tolist(np.asarray('123'))) == int
   True
   >>> type(tolist('123')) == int
   True
   >>> tolist('False') == False
   True
   

fermipy.utils.update_source_maps(srcmap_file, srcmaps, logger=None)

fermipy.utils.val_to_bin(edges, x)

Convert axis coordinate to bin index.

fermipy.utils.val_to_bin_bounded(edges, x)

Convert axis coordinate to bin index.

fermipy.utils.val_to_edge(edges, x)

Convert axis coordinate to bin index.

fermipy.utils.write_fits_image(data, wcs, outfile)

fermipy.utils.write_hpx_image(data, hpx, outfile, extname='SKYMAP')

fermipy.utils.write_maps(primary_map, maps, outfile)

fermipy.tsmap module

class fermipy.tsmap.TSCubeGenerator(config=None, **kwargs)

Bases: fermipy.config.Configurable

defaults = {'do_sed': (True, 'Compute the energy bin-by-bin fits', <type 'bool'>), 'norm_sigma': (5.0, 'Number of sigma to use for the scan range ', <type 'float'>), 'remake_test_source': (False, 'If true, recomputes the test source image (otherwise just shifts it)', <type 'bool'>), 'logging': {'verbosity': (3, '', <type 'int'>), 'chatter': (3, 'Set the chatter parameter of the STs.', <type 'int'>)}, 'st_scan_level': (0, 'Level to which to do ST-based fitting (for testing)', <type 'int'>), 'cov_scale': (-1.0, 'Scale factor to apply to broadband fitting cov. matrix in bin-by-bin fits ( < 0 -> fixed ) ', <type 'float'>), 'max_iter': (30, 'Maximum number of iterations for the Newtons method fitter.', <type 'int'>), 'tol_type': (0, 'Absoulte (0) or relative (1) criteria for convergence.', <type 'int'>), 'cov_scale_bb': (-1.0, 'Scale factor to apply to global fitting cov. matrix in broadband fits. ( < 0 -> no prior ) ', <type 'float'>), 'fileio': {'workdir': (None, 'Override the working directory.', <type 'str'>), 'savefits': (True, 'Save intermediate FITS files.', <type 'bool'>), 'scratchdir': ('/scratch', 'Path to the scratch directory.', <type 'str'>), 'outdir': (None, 'Path of the output directory. If none this will default to the directory containing the configuration file.', <type 'str'>), 'logfile': (None, 'Path to log file. If None then log will be written to fermipy.log.', <type 'str'>), 'usescratch': (False, 'Run analysis in a temporary directory under ``scratchdir``.', <type 'bool'>)}, 'tol': (0.001, 'Critetia for fit convergence (estimated vertical distance to min < tol )', <type 'float'>), 'nnorm': (10, 'Number of points in the likelihood v. normalization scan', <type 'int'>), 'model': (None, 'Dictionary defining the properties of the test source. By default the test source will be a PointSource with an Index 2 power-law specturm.', <type 'dict'>)}

make_ts_cube(gta, prefix, src_dict=None, **kwargs)

class fermipy.tsmap.TSMapGenerator(config=None, **kwargs)

Bases: fermipy.config.Configurable

defaults = {'multithread': (False, '', <type 'bool'>), 'fileio': {'workdir': (None, 'Override the working directory.', <type 'str'>), 'savefits': (True, 'Save intermediate FITS files.', <type 'bool'>), 'scratchdir': ('/scratch', 'Path to the scratch directory.', <type 'str'>), 'outdir': (None, 'Path of the output directory. If none this will default to the directory containing the configuration file.', <type 'str'>), 'logfile': (None, 'Path to log file. If None then log will be written to fermipy.log.', <type 'str'>), 'usescratch': (False, 'Run analysis in a temporary directory under ``scratchdir``.', <type 'bool'>)}, 'logging': {'verbosity': (3, '', <type 'int'>), 'chatter': (3, 'Set the chatter parameter of the STs.', <type 'int'>)}, 'model': (None, 'Dictionary defining the properties of the test source.', <type 'dict'>), 'erange': (None, 'Lower and upper energy bounds in log10(E/MeV). By default the calculation will be performed over the full analysis energy range.', <type 'list'>), 'max_kernel_radius': (3.0, '', <type 'float'>)}

make_ts_map(gta, prefix, src_dict=None, **kwargs)

Make a TS map from a GTAnalysis instance. The spectral/spatial characteristics of the test source can be defined with the src_dict argument. By default this method will generate a TS map for a point source with an index=2.0 power-law spectrum.

Parameters:

• gta (GTAnalysis) – Analysis instance.
• src_dict (dict or Source object) – Dictionary or Source object defining the properties of the test source that will be used in the scan.

fermipy.tsmap.cash(counts, model)

Compute the Poisson log-likelihood function.

fermipy.tsmap.extract_array(array_large, array_small, position)

fermipy.tsmap.extract_large_array(array_large, array_small, position)

fermipy.tsmap.extract_small_array(array_small, array_large, position)

fermipy.tsmap.f_cash(x, counts, background, model)

Wrapper for cash statistics, that defines the model function.

Parameters:

• x (float) – Model amplitude.
• counts (ndarray) – Count map slice, where model is defined.
• background (ndarray) – Background map slice, where model is defined.
• model (ndarray) – Source template (multiplied with exposure).

fermipy.tsmap.f_cash_sum(x, counts, background, model)

fermipy.tsmap.overlap_slices(large_array_shape, small_array_shape, position)

Modified version of overlap_slices.

Get slices for the overlapping part of a small and a large array.

Given a certain position of the center of the small array, with respect to the large array, tuples of slices are returned which can be used to extract, add or subtract the small array at the given position. This function takes care of the correct behavior at the boundaries, where the small array is cut of appropriately.

Parameters:

• large_array_shape (tuple) – Shape of the large array.
• small_array_shape (tuple) – Shape of the small array.
• position (tuple) – Position of the small array’s center, with respect to the large array. Coordinates should be in the same order as the array shape.

Returns:

• slices_large (tuple of slices) – Slices in all directions for the large array, such that large_array[slices_large] extracts the region of the large array that overlaps with the small array.
• slices_small (slice) – Slices in all directions for the small array, such that small_array[slices_small] extracts the region that is inside the large array.

fermipy.tsmap.poisson_log_like(counts, model)

Compute the Poisson log-likelihood function for the given counts and model arrays.

fermipy.tsmap.sum_arrays(x)

fermipy.tsmap.truncate_array(array1, array2, position)

Truncate array1 by finding the overlap with array2 when the array1 center is located at the given position in array2.

fermipy.residmap module

class fermipy.residmap.ResidMapGenerator(config=None, **kwargs)

Bases: fermipy.config.Configurable

This class generates spatial residual maps from the difference of data and model maps smoothed with a user-defined spatial/spectral template. The resulting map of source significance can be interpreted in the same way as the TS map (the likelihood of a source at the given location). The algorithm approximates the best-fit source amplitude that would be derived from a least-squares fit to the data.

defaults = {'logging': {'verbosity': (3, '', <type 'int'>), 'chatter': (3, 'Set the chatter parameter of the STs.', <type 'int'>)}, 'model': (None, 'Dictionary defining the properties of the test source. By default the test source will be a PointSource with an Index 2 power-law specturm.', <type 'dict'>), 'fileio': {'workdir': (None, 'Override the working directory.', <type 'str'>), 'savefits': (True, 'Save intermediate FITS files.', <type 'bool'>), 'scratchdir': ('/scratch', 'Path to the scratch directory.', <type 'str'>), 'outdir': (None, 'Path of the output directory. If none this will default to the directory containing the configuration file.', <type 'str'>), 'logfile': (None, 'Path to log file. If None then log will be written to fermipy.log.', <type 'str'>), 'usescratch': (False, 'Run analysis in a temporary directory under ``scratchdir``.', <type 'bool'>)}, 'erange': (None, 'Lower and upper energy bounds in log10(E/MeV). By default the calculation will be performed over the full analysis energy range.', <type 'list'>)}

make_residual_map(gta, prefix, src_dict=None, **kwargs)

run(gta, prefix, **kwargs)

fermipy.residmap.convolve_map(m, k, cpix, threshold=0.001, imin=0, imax=None)

Perform an energy-dependent convolution on a sequence of 2-D spatial maps.

Parameters:

• m (ndarray) – 3-D map containing a sequence of 2-D spatial maps. First dimension should be energy.
• k (ndarray) – 3-D map containing a sequence of convolution kernels (PSF) for each slice in m. This map should have the same dimension as m.
• cpix (list) – Indices of kernel reference pixel in the two spatial dimensions.
• threshold (float) – Kernel amplitude
• imin (int) – Minimum index in energy dimension.
• imax (int) – Maximum index in energy dimension.

fermipy.residmap.get_source_kernel(gta, name, kernel=None)

Get the PDF for the given source.

fermipy.residmap.poisson_lnl(nc, mu)

fermipy.sed module

Utilities for dealing with SEDs

Many parts of this code are taken from dsphs/like/lnlfn.py by

Matthew Wood <mdwood@slac.stanford.edu> Alex Drlica-Wagner <kadrlica@slac.stanford.edu>

class fermipy.sed.CastroData(norm_vals, nll_vals, specData, fluxType)

Bases: object

This class wraps the data needed to make a “Castro” plot, namely the log-likelihood as a function of normalization for a series of energy bins

TS_spectrum(spec_vals)

Calculate and the TS for a given set of spectral values

__call__(x)

return the log-like for an array of values, summed over the energy bins

x : Array of nEbins x M values

returns an array of M values

__getitem__(i)

return the LnLFn object for the ith energy bin

buildTestSpectrumFunction(specType)

derivative(x, der=1)

return the derivate of the log-like summed over the energy bins

x : Array of nEbins x M values der : Order of the derivate

returns an array of M values

fitNorm_v2(specVals)

Fit the normalization given a set of spectral values that define a spectral shape

This version uses scipy.optimize.fmin

Parameters

specVals : an array of (nebin values that define a spectral shape xlims : fit limits

returns the best-fit normalization value

fitNormalization(specVals, xlims)

Fit the normalization given a set of spectral values that define a spectral shape

This version is faster, and solves for the root of the derivatvie

Parameters

specVals : an array of (nebin values that define a spectral shape xlims : fit limits

returns the best-fit normalization value

fit_spectrum(specFunc, initPars)

Fit for the free parameters of a spectral function

Parameters

specFunc : The Spectral Function initPars : The initial values of the parameters

Returns (result,spec_out,TS_spec)

result : The output of scipy.optimize.fmin spec_out : The best-fit spectral values TS_spec : The TS of the best-fit spectrum

fluxType

Return the Flux type flag

fn_mles()

returns the summed likelihood at the maximum likelihood estimate

Note that simply sums the maximum likelihood values at each bin, and does not impose any sort of constrain between bins

getLimits(alpha, upper=True)

Evaluate the limits corresponding to a C.L. of (1-alpha)%.

Parameters:

• alpha (limit confidence level.) –
• upper (upper or lower limits.) –
• an array of values, one for each energy bin (returns) –

mles()

return the maximum likelihood estimates for each of the energy bins

nll_null

Return the negative log-likelihood for the null-hypothesis

specData

Return the Spectral Data object

test_spectra(spec_types=['PowerLaw', 'LogParabola', 'PLExpCutoff'])

ts_vals()

returns test statistic values for each energy bin

class fermipy.sed.Interpolator(x, y)

Bases: object

Helper class for interpolating a 1-D function from a set of tabulated values.

Safely deals with overflows and underflows

__call__(x)

Return the interpolated values for an array of inputs

x : the inputs

Note that if any x value is outside the interpolation ranges this will return a linear extrapolation based on the slope at the endpoint

derivative(x, der=1)

return the derivative a an array of input values

x : the inputs der : the order of derivative

x

return the x values used to construct the split

xmax

return the maximum value over which the spline is defined

xmin

return the minimum value over which the spline is defined

y

return the y values used to construct the split

class fermipy.sed.LnLFn(x, y, fluxType=0)

Bases: object

Helper class for interpolating a 1-D log-likelihood function from a set of tabulated values.

TS()

return the Test Statistic

fluxType

return a code specifying the quantity used for the flux

0: Normalization w.r.t. to test source 1: Flux of the test source ( ph cm^-2 s^-1 ) 2: Energy Flux of the test source ( MeV cm^-2 s^-1 ) 3: Number of predicted photons 4: Differential flux of the test source ( ph cm^-2 s^-1 MeV^-1 ) 5: Differential energy flux of the test source ( MeV cm^-2 s^-1 MeV^-1 )

fn_mle()

return the function value at the maximum likelihood estimate

getInterval(alpha)

Evaluate the interval corresponding to a C.L. of (1-alpha)%.

Parameters:alpha (limit confidence level.) –

getLimit(alpha, upper=True)

Evaluate the limits corresponding to a C.L. of (1-alpha)%.

Parameters:

• alpha (limit confidence level.) –
• upper (upper or lower limits.) –

interp

return the underlying Interpolator object

mle()

return the maximum likelihood estimate

This will return the cached value, if it exists

fermipy.sed.LogParabola(evals, scale)

fermipy.sed.PLExpCutoff(evals, scale)

fermipy.sed.PowerLaw(evals, scale)

class fermipy.sed.SEDGenerator(config=None, **kwargs)

Bases: fermipy.config.Configurable

defaults = {'bin_index': (2.0, 'Spectral index that will be use when fitting the energy distribution within an energy bin.', <type 'float'>), 'fileio': {'workdir': (None, 'Override the working directory.', <type 'str'>), 'savefits': (True, 'Save intermediate FITS files.', <type 'bool'>), 'scratchdir': ('/scratch', 'Path to the scratch directory.', <type 'str'>), 'outdir': (None, 'Path of the output directory. If none this will default to the directory containing the configuration file.', <type 'str'>), 'logfile': (None, 'Path to log file. If None then log will be written to fermipy.log.', <type 'str'>), 'usescratch': (False, 'Run analysis in a temporary directory under ``scratchdir``.', <type 'bool'>)}, 'fix_background': (True, 'Fix background parameters when fitting the source flux in each energy bin.', <type 'bool'>), 'ul_confidence': (0.95, 'Confidence level for upper limit calculation.', <type 'float'>), 'logging': {'verbosity': (3, '', <type 'int'>), 'chatter': (3, 'Set the chatter parameter of the STs.', <type 'int'>)}, 'use_local_index': (False, 'Use a power-law approximation to the shape of the global spectrum in each bin. If this is false then a constant index set to `bin_index` will be used.', <type 'bool'>)}

make_sed(gta, name, profile=True, energies=None, **kwargs)

Generate an SED for a source. This function will fit the normalization of a given source in each energy bin.

Parameters:

• name (str) – Source name.
• profile (bool) – Profile the likelihood in each energy bin.
• energies (ndarray) – Sequence of energies in log10(E/MeV) defining the edges of the energy bins. If this argument is None then the analysis energy bins will be used. The energies in this sequence must align with the bin edges of the underyling analysis instance.
• bin_index (float) – Spectral index that will be use when fitting the energy distribution within an energy bin.
• use_local_index (bool) – Use a power-law approximation to the shape of the global spectrum in each bin. If this is false then a constant index set to bin_index will be used.
• fix_background (bool) – Fix background components when fitting the flux normalization in each energy bin. If fix_background=False then all background parameters that are currently free in the fit will be profiled. By default fix_background=True.

Returns:

sed – Dictionary containing results of the SED analysis. The same dictionary is also saved to the source dictionary under ‘sed’.

Return type:

dict

class fermipy.sed.SpecData(ebins, fluxes, npreds)

Bases: object

This class wraps spectral data, e.g., energy bin definitions, flux values and number of predicted photons

bin_widths

return the energy bin widths

ebins

return the energy bin edges

efluxes

return the energy flux values

evals

return the energy centers

fluxes

return the flux values

log_ebins

return the log10 of the energy bin edges

nE

return the number of energy bins

npreds

return the number of predicted events

class fermipy.sed.TSCube(tsmap, normmap, tscube, norm_vals, nll_vals, specData, fluxType)

Bases: object

castroData_from_ipix(ipix, colwise=False)

Build a CastroData object for a particular pixel

castroData_from_pix_xy(xy, colwise=False)

Build a CastroData object for a particular pixel

static create_from_fits(fitsfile, fluxType)

Build a TSCube object from a fits file created by gttscube

find_and_refine_peaks(threshold, min_separation=1.0, use_cumul=False)

find_sources(threshold, min_separation=1.0, use_cumul=False, output_peaks=False, output_castro=False, output_specInfo=False, output_src_dicts=False, output_srcs=False)

nE

return the number of energy bins

nN

return the number of sample points in each energy bin

normmap

return the Map of the Best-fit normalization value

specData

Return the Spectral Data object

test_spectra_of_peak(peak, spec_types=['PowerLaw', 'LogParabola', 'PLExpCutoff'])

ts_cumul

return the Map of the cumulative TestStatistic value per pixel (summed over energy bin)

tscube

return the Cube of the TestStatistic value per pixel / energy bin

tsmap

return the Map of the TestStatistic value

fermipy.sed.alphaToDeltaLogLike_1DOF(alpha)

return the delta log-likelihood corresponding to a particular C.L. of (1-alpha)%

fermipy.sed.build_source_dict(src_name, peak_dict, spec_dict, spec_type)

Module contents