This package contains functions which can be used to create an estimated NICER background spectrum based on the "environmental" model
developed by the NICER Guest Observer Facility. The environmental model uses a combination of the cut-off rigidity (COR_SAX)
and the Planetary K index (KP) which gives an estimate of the space weather environment.  This model also uses the SUN_ANGLE parameter
which helps describe the low-energy background produced by optical loading.  COR_SAX and SUN_ANGLE are contained in the
"make filter" file (either the standard auxil/ni*.mkf file distributed with processed data or -recommended- the augmented MKF file produced by
the "niprefilter2" tool distributed with the NICERDAS HEASoft package).  The KP values are not currently included in either the .mkf or the
enhanced (.mkf2) makefilter files, and must be added using the add_kp function defined here.

METHOD:

The background estimator uses an event file (given as the bevt parameter in the code) created from
NICER Òblank skyÓ observations. These background observations are obtained over a range of parameters
which are correlated with background, namely sun angle (which is correlated with light leakage at low energies)
and cut-off rigidity and the space-weather KP parameter (which are correlated with
charged-particle background which may dominate at high energies).  The background estimator
determines the range of these parameters in the observation and extracts the events from the
background events file which match these parameters.  If there are ranges of parameters in the
observation which are not sampled in the background events file then the estimated background m
ight be underestimated.

REQUIREMENTS:

You'll need access to these files:
    a) The background events file 30nov18targskc_enhanced.evt (current version:
    https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nicer/xti/bcf/bkgparam/nixtispaceweather20170601v001.evt)
    b) the KP.fits file (the current version, updated daily, is at https://heasarc.gsfc.nasa.gov/FTP/caldb/data/gen/pcf/kp.fits)
You can access these files virtually by specifying the URLs given above (the default for the functions defined below) or
you can download them to a local directory for faster access.

EXAMPLE of creating an estimated NICER background spectrum:

  Assumptions:
  - the NICER data is stored in subdirectories of a root directory called "testdata" of the current working directory.
  - the NICER observation obsid is 1200040103
  - a extracted spectrum (which contains background) is called src.pha and is located in the current working directory.
  - a NICER make filter file created using the niprefilter2 NICERDAS tool exists.

    1) Use the niprefilter2 tool from NICERDAS to create a .mkf2 file from the .mkf file in the <obsid>/auxil directory (where <obsid> is the nicer  10-digit observation ID, and the standard NICER data directory structure is assumed).   

    2) after making sure that the nicergof/bkg directories are in your $PYTHONPATH, import this package as "be":

        >>> from nicergof.bkg import bkg_estimator as be

    3) (HEASOFT 6.29C NOTE: as of NICERDAS software version 8c, distributed with HEASOFT 6.29c, both nicerl2 and niprefilter2 can produce filter files which include the KP values and other geomagnetic values.  See https://heasarc.gsfc.nasa.gov/docs/nicer/analysis_threads/geomag/ for details.  If you already have an mkf file with the KP values added, you can SKIP this step.)  
    
    Update the .mkf2 file to include the KP values, using the "add_kp" function (assume this is for an observation with obsid=1200040103):

        >>> mkf3 = be.add_kp("testdata/1200040103/auxil/ni1200040103.mkf2")

    This will create a ".mkf3" file in the 11200040103/auxil directory

    4) use the mk_bkg_spec_evt function to create the background spectrum:

        >>> bkg_chan, bkgspectot, btotexpo = mk_bkg_spec_evt('src.pha', mkf3file='testdata/1200040103/auxil/ni1200040103.mkf3')
        
        where the mkf3file parameter should be set equal to the full path to the file produed by be.add_kp

    This will create a HEASARC-compliant background PHA file (with .pha replaced by _bkg.pha, i.e. the background file for "./nicer.pha" is
    "./nicer_bkg.pha") and also return the background channels, spectrum and exposure as the python variables bkg_chan, bkgspectot, btotexpo.

CAVEATS:

    * This is PRE-RELEASE software.
    * This software estimates the instrumental background.  X-ray cosmic background (sky background)
    appropriate to your source is NOT included in the estimated background spectrum produced by
    mk_bkg_spec_evt().  However, cosmic X-ray background in the NICER blank fields
    is included in the estimated background.
    * Note that the background events file excludes FPMs #14 & 34, so it uses data from
    50 out of the 52 active FPMs.  The estimated background
    * There may be combinations of (KP, COR_SAX, SUN_ANGLE) which are not contained in the
    background events file; in this case these times are ignored in the output background spectrum.
    * there may be other parameters that are important in determining background, or other
    parameters which give a better estimate of the background.  This is still under investigation.
    * Check your estimated background at high energies by comparing the source+background spectrum  with the
    estimated background spectrum at energies above 12 keV.  The estimated background should approximately
    match the source+background spectrum above 12 keV, since this band is dominated by charged-particle
    background.
    * there are undoubtedly other issues.


Version history:

0.2 - initial release
0.3 - convert KP file TIME column (in MJD) to MET using nicertimeconv (Mar 12 2020 MFC)
0.4 - fixed calculation of exposure time to address issues from DR and DE (Mar 25 2020 MFC)
0.5 - fixed deadtime correction (h/t Jack Steiner  (DT correction factor: 1 - mkf.mpu_deadtime * 7 / 52.) & update EXPOSURE
      keyword in all extensions (and primary header)
0.6 - fixed error calculation and some keywords for mk_bkg_lc_evt