####Changelog:
##v01r06 -- Changed default isotropic template to P8R3_SOURCE_V3 version.  Fixed issue with extended sources directory when using XML version of the catalog. -- 08 October 2020
##v01r05 -- Enables the use of the -varFree parameter with the xml version of the 4FGL catalogi and improves identification of diffuse components. -- 01 June 2020
##v01r04 -- Fixes bug which led to Diffuse Components not being written to the output model. -- 02 April 2019
##v01r03 -- Fix script to account for how energy dispersion is used with gll_iem_v07 -- 26 March 2019
####

The make4FGLxml.py script functions similarly to make3FGLxml.py, with the exception of (currently) not being able to set sources free based on their variability index.  This tool reads in the 4FGL catalog 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 4FGL catalog.

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 but you must tell it where the 4FGL extended source templates are on your system; however, 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 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.

Make sure the file make4FGLxml.py is executable and in your PATH, and that your default python is either the ScienceTools version.

command line usage is:

make4FGLxml.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

  -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

  -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)

  -p, flag to force extended sources to be cast as point sources, default is False

  -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
  
  -P7, flag to note make a model for use with P7REP data, all this does is change the default diffuse files and names.

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 very simliar to make3FGLxml.py.