==========   ReadMe for add_weights.py   ==============

Calculate Fermi LAT photon weights using the simple method of Bruel (A&A submitted, Fall 2018) Equation 11.
Also described by Equation 2 in Smith et al. (ApJ submitted, Fall 2018).
This script originally written by D.A. Smith, L. Guillemot, and P.S. Ray, Fall 2016.

(The pulsar software package PINT includes a more versatile (and more actively maintained) routine to calculate the same weights.
See https://github.com/nanograv/PINT/blob/master/pint/fermi_toas.py .)

Compute photon weights for a LAT FT1 file, based on an empirical approximation
to the LAT PSF. Optionally, search over LogERef to maximize the weights, as Philippe Bruel's
SearchPulsation code does.  Writes an output FT1 file with a weight column, if desired.

Coordinates can be read from a .par file, or specified with --ra and --dec options.
--ra and --dec can be in the form --ra=HH:MM:SS.s --dec=DD:MM:SS.d or --ra=ddd.d --dec=ddd.d.

REQUIREMENTS: 
1) The FT1 file must have a pulse phase column if you want to fit for the best LogERef.
   This is usually done with the Tempo2 fermi plugin.
   https://fermi.gsfc.nasa.gov/ssc/data/analysis/user/Fermi_plug_doc.pdf
   https://github.com/aarchiba/tempo2/blob/master/plugin/fermi_plug.C

2) add_weights.py imports numpy, astropy, scipy, and argparse.
   For some user options it also imports matplotlib, and psr_par from
   https://github.com/scottransom/presto/blob/master/lib/python/parfile.py

3) add_weights.py imports conv_dates_lib.py, which is provided in the .tar package.
  Change the line
     sys.path.insert(0,'/home/local1/myPython/') # for met, mjd conversions.
  to point to your directory containing conv_dates_lib.py

   ===== Example 1   ============

The FT1 file J0437-4715.fits contains a PULSE_PHASE column created by executing a command such as
tempo2 -gr fermi -ft1 J0437-4715.fits -ft2 lat_spacecraft_merged.fits -f J0437-4715_20cm_pdfb3.par -phase -graph 0 -cacheft2

This command then plots 20 values of H-test for 20 trial values of logeref:

python add_weights.py --ra 69.316239 --dec -47.252533 --plot --neref 20 J0437-4715.fits

The output plot is shown in add_weights_J0437-4715.png .
For a gamma-ray pulsar, it is a bell-shaped curve peaking above H-test 25.
Nota bene, logeref is called $\mu_w$ in the two references cited above.

A phased FT1 file is included in the .tar file.
J0437-4715_powGraph.ps is the unweighted phase histogram of the PULSE_PHASE column of the FT1 fits file.

   ===== Example 2   ============

If you have the modules,
                from astropy.coordinates import SkyCoord
		from parfile import psr_par
(see requirement 2, above to find the latter in PRESTO)

then you can read the coordinates from an ephemeris file:

python add_weights.py --par J0437-4715_20cm_pdfb3.par --plot --neref 20 J0437-4715.fits

The ephemeris is included in the .tar file.

   ===== Example 3   ============

Here is how to create an FT1 file with a WEIGHTS column, calculated using logeref=3.2

python add_weights.py --par J0205+6449.par -e 3.2 -w WEIGHTS -o J0205+6449_weights.fits J0205+6449.fits

   ===== Example 4   ============

Here is the "help" feature:

python add_weights.py -h
usage: add_weights.py [-h] (--par PAR | -r RA) [-d DEC] [-e LOGEREF]
                      [-n NEREF] [-w WEIGHTCOL] [-o OUTFILE]
                      [--phasecol PHASECOL] [--plot] [--tmin TMIN]
                      [--tmax TMAX]
                      FT1

Compute photon weights for a LAT FT1 file, based on an empirical approximation
to the LAT PSF. Optionally, search over LogERef to maximize the weights, as
Philippe Bruel's SearchPulsation code does. Writes an output FT1 file with a
weight column, if desired. Coordinates can be read from a .par file, or
specified with --ra and --dec options. --ra and --dec can be in the form
--ra=HH:MM:SS.s --dec=DD:MM:SS.d or --ra=ddd.d --dec=ddd.d. NOTE: The FT1 file
must have a pulse phase column if you want to fit for the best LogERef. This
is usually done with the Tempo2 fermi plugin.

positional arguments:
  FT1                   Input FT1 file name

optional arguments:
  -h, --help            show this help message and exit
  --par PAR             Name of par file to read pulsar position from
  -r RA, --ra RA        RA of the pulsar
  -d DEC, --dec DEC     DEC of the pulsar
  -e LOGEREF, --logeref LOGEREF
                        LogERef to use, default is to find optimal
  -n NEREF, --neref NEREF
                        Number of LogERef trials
  -w WEIGHTCOL, --weightcol WEIGHTCOL
                        Name of weight column in FT1 file
  -o OUTFILE, --outfile OUTFILE
                        Output file name, if desired
  --phasecol PHASECOL   Name of pulse phase column in FT1 file (default
                        PULSE_PHASE)
  --plot
  --tmin TMIN           Earliest MJD date used.
  --tmax TMAX           Latest MJD date used.


ReadMe created by David A. Smith, 27 September 2018, with contributions from Donald Horner.
Updated: never yet.
Send questions, comments to   smith AT cenbg.in2p3.fr 

tar -cvf add_weights.tar /work/txt/papers/PsrCata/3rd/parfiles/J0437-4715_20cm_pdfb3.par /mnt/hgfs/echanges/J0437-4715.fits add_weights_J0437-4715.png ReadMe add_weights.py ~/myPython/conv_dates_lib.py J0437-4715_powGraph.ps