Package: makebininf
Author: Paul Ray <paul.s.ray3.civ@us.navy.mil>
Description: Contains some codes to convert Fermi LAT event ("FT1") files into
  a format compatible with PRESTO codes, particularly prepfold.  This is useful if you
  want to use prepfold to search for pulsations, refine pulsar candidates, or time pulsars
  using Fermi LAT data.
Version: 2.0
Date: 2025 January 6

*** NOTICE *** This code is provided as contributed code in hopes that 
it will be helpful. The authors do not warrant that the code is bug free, 
or even correct. E-mail questions and requests are welcomed, but support 
can only be provided on a time-available basis.

REREQUISITES:

* Python (>= 3.8)
* astropy
* A C compiler (typically gcc).
* The C package cfitsio, which can be obtained from HEASARC 
  at this site <http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html>
* A working PRESTO installation so that you have "prepfold" and
  can "import presto.psr_utils" in python without error.
  This can be obtained from <https://github.com/scottransom/presto>

SYSTEM REQUIREMENTS:

This code has been tested on Linux and Mac OS X. 

INSTALLATION:

* Unpack the tar.gz file.  It will create the directory makebininf-2.0
  Change into that directory.

* Edit the Makefile and tell it where to find cfitsio and specify an install directory and any needed compiler options.
  
* Make the code by typing "make", then install with "make install"

* Make sure that the install directory is in your PATH so that both executables can be found
  
* Make sure that the python that you get by typing "python" at the command line
  (i.e. the first "python" in your PATH) is the one you want.
  
DESCRIPTION OF CODES:

* makebininf.py is the top-level code that you run to convert your FT1 file into
  a pair of files that PRESTO can use.  It writes a ".events" file, which is just
  a binary file of double precision floats with photon times in MJD(TDB), i.e.
  barycenterd event MJDs.  It also writes a ".inf" file that describes the contents
  of the .events file in a format that PRESTO needs.
  *** IMPORTANT *** The input FT1 file MUST be barycentered using gtbary before
  using this script!
  
* fits2bin is a C code that is called by the python script to do the work.

USAGE:

* Make an FT1 file that has all the appropriate cuts applied for your application.
  This is typically done using a call to gtselect.
  
* Barycenter the event times using gtbary.  Here, we assume the output file is 
  called "FT1_filt_bary.fits", but you can call it whatever you want. An example file
  with this name is included with the distribution.
  
* Run the code:
  % makebininf.py --source='J1907+06' FT1_filt_bary.fits
  
  Alternatively, you can leave off the --source option and you will be prompted
  for the source name to embed in the .inf file.
  
  The files FT1_filt_bary.events and FT1_filt_bary.inf will be written in the
  current directory.  (The .inf file is ASCII, so you can read or edit it if
  needed).

* Now, you can use prepfold to fold the events in the file, but note that it
  requires the following options (at a minimum): "-events -double -mjds".  So,
  this would be an example:
  % prepfold -events -mjds -double -par 1907.par FT1_filt_bary.events

-- END --
