Customizing the Model
The ROIModel class is responsible for managing the source and diffuse components in the ROI. Configuration of the model is controlled with the model block of YAML configuration file.
Configuring Diffuse Components
The simplest configuration uses a single file for the galactic and isotropic diffuse components. By default the galactic diffuse and isotropic components will be named galdiff and isodiff respectively. An alias for each component will also be created with the name of the mapcube or file spectrum. For instance the galactic diffuse can be referred to as galdiff or gll_iem_v07 in the following example.
model:
src_roiwidth : 10.0
galdiff : '$FERMI_DIR/refdata/fermi/galdiffuse/gll_iem_v07.fits'
isodiff : '$FERMI_DIR/refdata/fermi/galdiffuse/iso_P8R3_SOURCE_V3_v1.txt'
catalogs : ['4FGL-DR3']
To define two or more galactic diffuse components you can optionally define the galdiff and isodiff parameters as lists. A separate component will be generated for each element in the list with the name galdiffXX or isodiffXX where XX is an integer position in the list.
model:
galdiff :
- '$FERMI_DIFFUSE_DIR/diffuse_component0.fits'
- '$FERMI_DIFFUSE_DIR/diffuse_component1.fits'
To explicitly set the name of a component you can define any element as a dictionary containing name and file fields:
model:
galdiff :
- { 'name' : 'component0', 'file' : '$FERMI_DIFFUSE_DIR/diffuse_component0.fits' }
- { 'name' : 'component1', 'file' : '$FERMI_DIFFUSE_DIR/diffuse_component1.fits' }
Configuring Source Components
The list of sources for inclusion in the ROI model is set by defining a list of catalogs with the catalogs parameter. Catalog files can be in either XML or FITS format. Sources from the catalogs in this list that satisfy either the src_roiwidth or src_radius selections are added to the ROI model. If a source is defined in multiple catalogs the source definition from the last file in the catalogs list takes precedence.
model:
src_radius: 5.0
src_roiwidth: 10.0
catalogs :
- 'gll_psc_v31.fit'
- 'extra_sources.xml'
Individual sources can also be defined within the configuration file with the sources parameter. This parameter contains a list of dictionaries that defines the spatial and spectral parameters of each source. The keys of the source dictionary map to the spectral and spatial source properties as they would be defined in the XML model file.
model:
sources :
- { name: 'SourceA', glon : 120.0, glat : -3.0,
SpectrumType : 'PowerLaw', Index : 2.0, Scale : 1000, Prefactor : !!float 1e-11,
SpatialModel: 'PointSource' }
- { name: 'SourceB', glon : 122.0, glat : -3.0,
SpectrumType : 'LogParabola', norm : !!float 1E-11, Scale : 1000, beta : 0.0,
SpatialModel: 'PointSource' }
For parameters defined as scalars, the scale and value properties will be assigned automatically from the input value. To set these manually a parameter can also be initialized with a dictionary that explicitly sets the value and scale properties:
model:
sources :
- { name: 'SourceA', glon : 120.0, glat : -3.0,
SpectrumType : 'PowerLaw', Index : 2.0, Scale : 1000,
Prefactor : { value : 1.0, scale : !!float 1e-11, free : '0' },
SpatialModel: 'PointSource' }
Spatial Models
Fermipy supports four spatial models which are defined with the
SpatialModel
property:
PointSource : A point source (SkyDirFunction).
RadialGaussian : A symmetric 2D Gaussian with width parameter ‘Sigma’.
RadialDisk : A symmetric 2D Disk with radius ‘Radius’.
SpatialMap : An arbitrary 2D shape with morphology defined by a FITS template.
The spatial extension of RadialDisk and RadialGaussian can be
controlled with the SpatialWidth
parameter which sets the 68%
containment radius in degrees. Note for ST releases prior to
11-01-01, RadialDisk and RadialGaussian sources will be represented
with the SpatialMap
type.
model:
sources :
- { name: 'PointSource', glon : 120.0, glat : 0.0,
SpectrumType : 'PowerLaw', Index : 2.0, Scale : 1000, Prefactor : !!float 1e-11,
SpatialModel: 'PointSource' }
- { name: 'DiskSource', glon : 120.0, glat : 0.0,
SpectrumType : 'PowerLaw', Index : 2.0, Scale : 1000, Prefactor : !!float 1e-11,
SpatialModel: 'RadialDisk', SpatialWidth: 1.0 }
- { name: 'GaussSource', glon : 120.0, glat : 0.0,
SpectrumType : 'PowerLaw', Index : 2.0, Scale : 1000, Prefactor : !!float 1e-11,
SpatialModel: 'RadialGaussian', SpatialWidth: 1.0 }
- { name: 'MapSource', glon : 120.0, glat : 0.0,
SpectrumType : 'PowerLaw', Index : 2.0, Scale : 1000, Prefactor : !!float 1e-11,
SpatialModel: 'SpatialMap', Spatial_Filename : 'template.fits' }
Editing the Source List at Runtime
Tip
Many users chose to delete sources that are not signifcantly
detected (e.g. TS<1
and/or nPred<1
) from the model
after the optimize()
step.
The model can be manually editing at runtime with the
add_source()
and
delete_source()
methods.
Sources should be added after calling
setup()
as shown in the
following example.
from fermipy.gtanalysis import GTAnalysis
gta = GTAnalysis('config.yaml',logging={'verbosity' : 3})
gta.setup()
# Remove isodiff from the model
gta.delete_source('isodiff')
# Add SourceA to the model
gta.add_source('SourceA',{ 'glon' : 120.0, 'glat' : -3.0,
'SpectrumType' : 'PowerLaw', 'Index' : 2.0,
'Scale' : 1000, 'Prefactor' : 1e-11,
'SpatialModel' : 'PointSource' })
# Add SourceB to the model
gta.add_source('SourceB',{ 'glon' : 121.0, 'glat' : -2.0,
'SpectrumType' : 'PowerLaw', 'Index' : 2.0,
'Scale' : 1000, 'Prefactor' : 1e-11,
'SpatialModel' : 'PointSource' })
Sources added after calling
setup()
will be created
dynamically through the pyLikelihood object creation mechanism.
Freeing and Fixing Parameters
In addition to freeing and fixing parameters for a source or list
of sources as explained in
quickstart.html#creating-an-analysis-script, we can also
free and fix parameters by name using the
free_parameter()
method.
For example:
gta.free_parameter(name="SourceA", par="Index", free=False)
gta.free_parameter(name="SourceB", par="Prefactor", free=True)
Manual Setting of Parameters and Parameter Ranges
Note
As in fermitools, “The actual value of a given parameter that is used in the calculation is the value attribute multiplied by the scale attribute. The value attribute is what the optimizers see.”
In rare cases, the user may want to access or change the current
value or allowed range of a given parameter. The function
_get_param()
returns a
dictionary with information about a given parameter such as its
value and allowed range. Parameters can also accessed via the ROI
dictionsary. For example, the following are equivalent:
indexA = gta._get_param(name="SourceA", par="Index")["value"]
indexA = gta.roi["SourceA"].spectral_pars["Index"]["value"]
set_parameter()
can be
used to set the value or range. Note that the bounds
argument
is always unscaled. The following calls are equivalent:
gta.set_parameter("SourceA", "Prefactor", 1.236583491e-13, bounds=[0.01, 100], scale=1e-13, true_value=True)
gta.set_parameter("SourceA", "Prefactor", 1.236583491, bounds=[0.01, 100], scale=1e-13, true_value=False)
In either case, the allowed parameter values range from 1e-15
to 1e-11
.