####Changelog: ##v01r07 -- Made for use with 4FGL-DR3 catalog/source list only, 12 January 2022 ##v01r08 -- Updated to make useable with 4FGL, 4FGL-DR2, and 4FGL-DR3 by specifying DataRelease value ##v01r09 -- Corrected mistake in setting sigma parameter for extended sources with RadialGaussian shape function from FITS version of catalog ## mistake did not affect sources if input 4FGL catalog was in XML format #### The make4FGLxml.py script functions reads in the 4FGL-DR3, 4FGL-DR2, or 4FGL catalog/source list and will output an XML model of the region for use with the Fermi ScienceTools, it will also, by default, produce a ds9-style region file for ease of displaying sources in your model on a counts map. It can be called in a python script or run directly from the command line. You can use either the FITS or XML version of the catalog/source list. The tool reads the ROI information from the input event file and adds all point and extended sources from the 4FGL catalog within the ROI radius plus an extra radial distance (10 degrees by default) to account for the large PSF (at lower energies) of the LAT. The tool will automatically get the correct spectral form and best-fit parameters for each source. For extended sources, it will find the correct spatial template, assuming the default directory path for the fermitools. You can force all extended sources to be cast as point sources but this should only be done if you are sure that doing so will not affect your analysis. The tool will decide which sources will have free parameters (either all parameters or just normalizations) using the following criteria. --the source must be within a specified radius limit (defaults to ROI radius) --the source must have been found in 4FGL-DR3 with an average significance greater than the specified lower limit (default is 5 sigma). Note that when using the XML version of the catalog this becomes a cut on TS, not average significance, so you should adjust the lower limit accordingly. --if the source has variability index greather than the 4FGL-DR3 threshold of 24.725 the normalization will be free if outside the specified radius, but within a max radius, even if the source fails the significance check. This behavior can be disabled. Make sure the file make4FGLDR3xml.py is executable and in your PATH, and that your default python is either the fermitools version or one with access to astropy, numpy, etc. command line usage is: make4FGLDR3xml.py catalog ev --optional_arguments catalog is the path to the FITS or XML version of the 4FGL catalog ev is the path to the event file describing your ROI optional arguments are: -o, name of output xml file, defaults to mymodel.xml if making the ds9 region file, the code simply appends "ROI_" to the XML file name and gives it the proper extension -DR, 4FGL data release version, 3 for 4FGL-DR3, 2 for 4FGL-DR2, or 1 for 4FGL; defaults to 3. This changes the variability threshold and the version of PowerLawSuperExpCutoff used. -G, path to Galactic diffuse model FITS file, the default should be such that the user won't need to change this if using the FermiTools and doing a standard SOURCE class analysis with P8R3. -g, name of Galactic diffuse component in output XML file -I, path to isotropic diffuse template file, the default should be such that the user won't need to change this if using the FermiTools and doing a standard SOURCE class analysis with P8R3. -i, name of isotropic diffuse component in output XML file -N, flag to only have normalization parameters free for sources passing radius, significance, and variability cuts -e, path to directory with extended source templates if not default fermitools directory -r, radius in degrees from ROI center beyond which sources will be fixed, defaults to selection radius in event file -R, absolutely the maximum radius from ROI center beyond which all source parameters will be fixed, even for variable sources, this avoids issues with binned analysis where the event file has to be larger than the square region you're later going to use, defaults to the -r value. -ER, this is the extra radius beyond the ROI radius out to which sources will be included (sources outside the ROI will be fixed of course), default is 10 degrees, but that may be too much for an analysis above a few GeV (for instance), thus the flexibility -s, this is the average significance below which all source parameters are fixed (if using the 4FGL XML file, this is actually a cut on TS) -v, flag to let normalizations of sources with 4FGL (1-year) Variability_Index > 18.48 be free if they would normally be fixed if they are still within the radius specified by the -R option -p, flag to force extended sources to be cast as point sources, default is False -E2C, use 4FGL-DR3 names for extended sources instead of full names, such as 'Vela X' -m, flag to make the ds9 region file, default is True -GIF, flag to modify the Galactic diffuse model spectrum by a power law with a free index, default is False -wd, directory to write the output ds9 region file to if not the current working directory -ON, flag to use the naming convention of make2FGLxml.py, preceed name with an underscore and remove all spaces For the optional arguments that are "flags", the value can be specified from the following choices: True, False, T, F, t, f, TRUE, FALSE, true, false, 1, or 0. For the -N, -p, and -GIF options since the default is False, instead of specifying the value you can just turn the option on, e.g., "make4FGLxml.py catalog.fits events.fits -p" (the -p bit is enough to tell the code to cast extended sources as point sources, no need to do "-p True" or similar) For calling the functions directly in a python script, the usage is simliar to make3FGLxml.py with the one exception that making the srcList object also takes a DRversion optional argument (defaults to 3) to specify the DataRelease version.