Metadata-Version: 2.1
Name: wtlike
Version: 0.2.2
Summary: Time-dependent analysis of point sources in Fermi-LAT data
Home-page: https://github.com/tburnett/wtlike/tree/master/
Author: Toby Burnett
Author-email: tburnett@uw.edu
License: Apache Software License 2.0
Keywords: fermi gamma-rays
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: astropy

# The `wtlike` package
> Code for generating fermi-LAT light curves.


### GitHub Links

- [this document](https://tburnett.github.io/wtlike/)
-  [repository](https://github.com/tburnett/wtlike)

## Introductinon

This package has code that was adapted to the [nbdev](https://nbdev.fast.ai/) code/tests/documentation environment from the [github package lat-timing](https://github.com/tburnett/lat-timing) to manage light curves of Fermi-LAT sources.  
It is based on a [paper](https://arxiv.org/pdf/1910.00140.pdf) by Matthew Kerr, which derives the [weighted likelihood formalism](https://tburnett.github.io/wtlike/loglike#The-Kerr-likelihood-formula) used here, specifically with
the [Bayesian Block](https://arxiv.org/pdf/1207.5578.pdf) to detect and characterize variability of a gamma-ray source.

Also, I've ported some code from  my [jupydoc](https://github.com/tburnett/jupydoc) documentation package supporting enhanced documentation combining Markdown and code, such that the 
Markdown reflects execution of the code.

## Installation

Note that this is still in alpha mode. 

To install from pip:

```
pip install wtlike
```
Data requirements: There are three sets of files:

- **photon data**<br> 
These are a set of weekly pickled python `dict` objects with compressed condensed photon and spacecraft data extracted from the GSFC FTP site. They contain every photon above 100 MeV, and less than $100^\circ$ 
from the zenith.

- **weight tables**<br>
Each source to be analyzed needs a table defining the photon weight as a function of position, energy, and event type. These are currently generated by pointlike. (A `fermipy`-generated version would be preferable.)

- **effective area**<br>
A standard fermi instrument response file (IRF) defining the effective area as a function of detector angle and energy. 

A set of these is available as a 1.6 GB zip file.

## Quick Demo

The following code cell loads the data for the BL Lac blazar, and plots by default, a weekly light curve for the full *fermi* mission.

```python
from wtlike import *
weekly = WtLike('BL Lac') # how to define 7-day bins for the full dataset.
weekly.plot(ylim=(-0.8,15)); #plot takes plt.plot args.
```

    SourceData: photons and exposure for BL Lac: Saving to cache with key "BL Lac_data"
    	Assembling photon data and exposure for source BL Lac from folder "/home/burnett/wtlike_data/data_files",
    	 with 665 files, last file:  week_674.pkl: loading all files
    .........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
    Load weights from file /mnt/d/wtlike/wtlike_data/weight_files/BL_Lac_weights.pkl
    	Found: P88Y6076 at (92.60, -10.44)
    	Applyng weights: 0 / 406640 photon pixels are outside weight region
    	95671 weights set to NaN
    WtLike: Source BL Lac with:
    	 data:       310,969 photons from   2008-08-04 to 2021-05-06
    	 exposure: 3,177,752 intervals from 2008-08-04 to 2021-05-06
    CellData: Bin photon data into 665 1-week bins from 54683.0 to 59338.0
    LightCurve: select 656 cells for fitting with e>0.5 & n>2



![png](docs/images/output_2_1.png)


The variable `weekly` has lots of capabilities.
To examine a subset of the data at the end of the current data, we use `view` to create a new `WtLike` object and plot it.

```python
hourly_at_end = weekly.view((-5,0, 1/24)) # for the last 5 days, 1-hour bins
hourly_at_end.plot(); # Accepts plt.plot args, e.g. xlim, ylim, etc.
```

    CellData: Bin photon data into 120 1-hour bins from 59335.0 to 59340.0
    LightCurve: select 81 cells for fitting with e>0.5 & n>2



![png](docs/images/output_4_1.png)


Or, to do a Bayesian Block partition with these 1-hour bins, perform fits, and overplot the result, just run the following.

```python
bb_hourly = hourly_at_end.bb_view()
bb_hourly.plot();
```

    LightCurve: select 81 cells for fitting with e>0.5 & n>2
    Partitioned 81 cells into 4 blocks, using LikelihoodFitness 
    LightCurve: Loaded 4 / 4 cells for fitting



![png](docs/images/output_6_1.png)


Finally, let's look at the values plotted above:

```python
bb_hourly.fluxes
```




<div>
<style scoped>
    .dataframe tbody tr th:only-of-type {
        vertical-align: middle;
    }

    .dataframe tbody tr th {
        vertical-align: top;
    }

    .dataframe thead th {
        text-align: right;
    }
</style>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th>t</th>
      <th>tw</th>
      <th>n</th>
      <th>ts</th>
      <th>flux</th>
      <th>errors</th>
      <th>limit</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>0</th>
      <td>59335.42</td>
      <td>0.83</td>
      <td>178</td>
      <td>404.1</td>
      <td>6.70</td>
      <td>(-0.655, 0.689)</td>
      <td>7.89</td>
    </tr>
    <tr>
      <th>1</th>
      <td>59336.69</td>
      <td>1.71</td>
      <td>205</td>
      <td>170.0</td>
      <td>2.38</td>
      <td>(-0.308, 0.323)</td>
      <td>2.93</td>
    </tr>
    <tr>
      <th>2</th>
      <td>59338.02</td>
      <td>0.96</td>
      <td>222</td>
      <td>573.6</td>
      <td>8.70</td>
      <td>(-0.734, 0.767)</td>
      <td>10.01</td>
    </tr>
    <tr>
      <th>3</th>
      <td>59339.23</td>
      <td>1.46</td>
      <td>217</td>
      <td>369.4</td>
      <td>4.48</td>
      <td>(-0.434, 0.454)</td>
      <td>5.25</td>
    </tr>
  </tbody>
</table>
</div>



## Input data

There are three data sources which `wtlike` needs to function:


-	The photon/spacecraft data
-	A table of weights for each source
-	An effective area IRF table 

These must be found under a folder, which by default is `~/wtlike_data`. In that folder there must be (perhaps links to) three folders named `data_files`, `weight_files`, `aeff_files`.  A copy of what I'm using is at `/afs/slac/g/glast/users/burnett/wtlike_data`

## Module summary

### Configuration [config](https://tburnett.github.io/wtlike/config)
Implements basic configuration information, [Config](https://tburnett.github.io/wtlike/config#Config), a cache system [Cache](https://tburnett.github.io/wtlike/config#Cache), point source info [PointSource](https://tburnett.github.io/wtlike/config#PointSource), and [time conversion](https://tburnett.github.io/wtlike/config#Time-conversion)

### Photon and Spacecraft Data  [data_man](https://tburnett.github.io/wtlike/data_man)
This module manages conversion of the weekly FT1 (photons) and FT2 (spacecraft) files, downloaded from  [GSFC](https://heasarc.gsfc.nasa.gov/FTP/fermi/data/lat/weekly), to a folder containing  pickled files, each with tables of photons, space craft data, and a list of GTI times derived from the FT1 file. A class [WeeklyData](https://tburnett.github.io/wtlike/data_man#WeeklyData) exports the results.

### Source data  [source_data](https://tburnett.github.io/wtlike/source_data)
The module depends on a specific source. It extracts the photons within a disk, and calculates the exposure for this direction. It assumes that a weigtht analysis has been done for this source, which it uses to apply a weight to each photon. This is handled by the class [SourceData](https://tburnett.github.io/wtlike/source_data#SourceData). It depends on [weights](https://tburnett.github.io/wtlike/weights) and [effective_ares](https://tburnett.github.io/wtlike/effective_area) to evaluate exposure.

### Cell data [cell_data](https://tburnett.github.io/wtlike/cell_data)
The next step is to define a set of time bins, or "cells". This module, implementing the class [CellData(SourceData)](https://tburnett.github.io/wtlike/cell_data#CellData), creates a set of cells.

### The light-curve  [lightcurve](https://tburnett.github.io/wtlike/lightcurve)
The the class [LightCurve(CellData)](https://tburnett.github.io/wtlike/lightcurve#LightCurve) uses the set of cells created by its superclass, and generates a likelihood function for each according to Kerr Eqn 2. These functions are represented by 3-parameter Poisson-like (see [poisson](https://tburnett.github.io/wtlike/poisson)) functions for further analysis. It creates a table with this information for plotting a light curve.

### Bayesian Blocks [bayesian](https://tburnett.github.io/wtlike/bayesian) 
This module contains the code implementing the  Bayesian block capability. 

### Simulation [simulation](https://tburnett.github.io/wtlike/simulation)
A light curve can be also generated with a simulation.

### Main [main](https://tburnett.github.io/wtlike/main)
Implements [WtLike(LightCurve)](https://tburnett.github.io/wtlike/main#WtLike/), a subclass of `LightCurve`, to which it adds the function `bb_view`, returning a new object with BB cells. Its `plot` funtion generates a light-curve plot showing the cells of its parent, overplotted tiwh the BB points.


