BatAnalysis

<!-- *** Thanks for checking out the Best-README-Template. If you have a suggestion *** that would make this better, please fork the repo and create a pull request *** or simply open an issue with the tag "enhancement". *** Thanks again! Now go create something AMAZING! :D *** *** *** *** To avoid retyping too much info. Do a search and replace for the following: *** lazzati-astro, MCRaT, twitter_handle, email, project_title, project_description steps to upload a distribution to PyPi is at: https://stackoverflow.com/questions/1471994/what-is-setup-py --> <!-- PROJECT SHIELDS --> <!-- *** I'm using markdown "reference style" links for readability. *** Reference links are enclosed in brackets [ ] instead of parentheses ( ). *** See the bottom of this document for the declaration of the reference variables *** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use. *** https://www.markdownguide.org/basic-syntax/#reference-style-links -->

[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]
<a href="https://ascl.net/2304.003"><img src="https://img.shields.io/badge/ascl-2304.003-blue.svg?colorB=262255" alt="ascl:2304.003" /></a>

<!-- PROJECT LOGO --> <br /> <p align="center"> <a href="https://github.com/parsotat/BatAnalysis"> <img src="./batanalysis/data/batanalysis_logo.jpg" alt="Logo"> </a> <h3 align="center">The BatAnalysis Pipeline </h3> <p align="center"> The BatAnalysis python pipeline is brings the analysis of BAT data to the convenience offered by Python. <br /> <a href="https://github.com/parsotat/BatAnalysis/tree/master/notebooks"><strong>Explore the docs »</strong></a> <br /> <br /> <!-- <a href="https://github.com/parsotat/BatAnalysis">View Demo</a> · --> <a href="https://github.com/parsotat/BatAnalysis/issues">Report Bug</a> · <a href="https://github.com/parsotat/BatAnalysis/issues">Request Feature</a> </p> </p> <!-- TABLE OF CONTENTS --> <details open="open"> <summary><h2 style="display: inline-block">Table of Contents</h2></summary> <ol> <li> <a href="#about-the-project">About The Project</a> <ul> <li><a href="#built-with">Built With</a></li> </ul> </li> <li> <a href="#getting-started">Getting Started</a> <ul> <li><a href="#prerequisites">Prerequisites</a></li> <li><a href="#installation">Installation</a></li> </ul> </li> <li><a href="#usage">Usage</a></li> <li><a href="#roadmap">Roadmap</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#contact">Contact</a></li> <li><a href="#acknowledgements">Acknowledgements</a></li> </ol> </details> <!-- ABOUT THE PROJECT -->

About The Project

<!-- [![Product Name Screen Shot][product-screenshot]](https://example.com) -->

BatAnalysis is a python package that allows for the convenient analysis of BAT Survey and Time-tagged Event (TTE) data. This code allows users to:

• easily download BAT data,
• batch process the observations,
• extract light curves and spectra for each observation for a given source

For survey data in particular it allows users to:

• create mosaiced images at different time bins, and
• extract light curves and spectra from the mosaiced images for a given source.

This project was developed in collaboration with the members of the BAT Team including: David Palmer, Sibasish Laha, Amy Lien, and Craig Markwardt.

Built With

• Python 3
• HEASoftPy
• PyXspec
• swiftbat_python
• Swifttools
• typical python modules (astropy, numpy, scipy, etc.)

<!-- GETTING STARTED -->

Getting Started

It is easy to get started on your local computer or on SciServer

Prerequisites

The following software are necessary for the BatAnalysis python module.

1. Python 3.9 or greater
   • We recommend installing via Anaconda
2. swiftbat_python
   • This will be installed via the pip command below
3. Swifttools
   • This will also installed via the pip command below
4. HEASoftPy >= v1.4.1 (HEASoft >= v6.33.2)
   • The installation is included with HEASoft and the steps can be found here: https://heasarc.gsfc.nasa.gov/docs/software/lheasoft/
5. PyXspec
   • The installation is included with HEASoft but there may be additional steps to take if you have changed your anaconda version after building HEASoft. More information can be found here: https://heasarc.gsfc.nasa.gov/xanadu/xspec/python/html/buildinstall.html
6. Swift BAT Pattern Noise Maps (necessary for the analysis of survey data)
   • The pattern maps used by the BAT team are available on zenodo for download. These maps shoud be downloaded and placed into a place where the BatAnalysis code will be able to access them.
     • This data is most easily downloaded using the zenodo_get utility, especially for installation on remote servers

Using the SciServer interface it is easier to start using BatAnalysis since HEASoftpy and pyXspec are already installed.

Getting Started on SciServer

1. To get started on Sciserver, first follow the instructions outlined here to get an account set up and get a container up and running.

Be sure that the container that is created has a compatible python and HEASoft version

2. With the container created, the user can install BatAnalysis through pip:

    pip install BatAnalysis

3. The Pattern Noise Maps can easily be downloaded into the /home/idies/workspace/Temporary/<username>/scratch/ directory with the use of the zenodo_get utility. If the analyses that will be conducted will not involve survey data being mosaiced then this step can be skipped.

Getting Started on a Local Computer

To get up and running on a local computer once the prerequisites met is very simple. All that is needed to install the package is either:

A. Pip install the BatAnalysis package:

    pip install BatAnalysis

B. Clone the repo and install

git clone https://github.com/parsotat/BatAnalysis.git
cd BatAnalysis/
pip install -e .

<!-- USAGE EXAMPLES -->

Usage

a) Survey Data

The typical BatAnalysis workflow for analyzing survey data is as follows:

1. Use astroquery to queue HEASARC for obervations within a given date range for an RA/DEC coordinate corresponding to a source of interest
2. Download the data
3. Run batsurvey on each observation ID
4. Calculate the detector response matrix for each survey pointing
5. Calculate the spectrum in each pointing
6. Fit the spectra to obtain spectral information
7. Calculate the light curve for the time period of interest
8. Plot the light curve/spectral information
9. Create mosaiced images for the time binning of interest (days, weeks, months, years)
10. Create the total "time-integrated" mosaiced image
11. Extract the spectra of the mosaiced images and fit them
12. Calculate the light curve of the source from the mosaiced images
13. Plot the light curve/spectral information for the mosaiced images

b) TTE Data

The typical BatAnalysis workflow for analyzing TTE data is as follows:

1. Query TTE data based on different criteria
2. Download the data
3. Load the data with BatEvent
4. Calculate sky images with the data to identify a source
5. Mask-weight the data based on the source of interest
6. Calculate lightcurves arbitarily binned in time and energy with the mask-weighted data
7. Calculate spectra and the detector response matrices for a given time interval
8. Fit the spectra to obtain spectral information
9. Plot the light curve/spectral information

For more details and additional examples please refer to the Notebooks directory

<!-- ROADMAP -->

Roadmap

Next, this package will be modified to:

• include analysis of BAT scaled map data
• interface with 3ML for multi-wavelength spectral fitting

See the open issues for a list of proposed features (and known issues).

<!-- CONTRIBUTING -->

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

<!-- LICENSE -->

License

Distributed under the MIT License. See LICENSE for more information.

<!-- CONTACT -->

Contact

Tyler Parsotan - [Personal Website](https://asd.gsfc.nasa.gov/Tyler.Parsotan/