=======
bolides
=======

**A package to analyze bolide data in Python.**

|pypi-badge| |rtd-badge| |binder-badge|

.. |rtd-badge| image:: https://readthedocs.org/projects/bolides/badge/?version=latest
               :target: https://bolides.readthedocs.io/en/latest
               :alt: Documentation Status
.. |pypi-badge| image:: https://img.shields.io/pypi/v/bolides.svg
                :target: https://pypi.org/project/bolides/
                :alt: PyPI link
.. |binder-badge| image:: https://mybinder.org/badge_logo.svg
                :target: https://mybinder.org/v2/gh/SETI/bolides/master?labpath=notebooks%2Ftutorial.ipynb
                :alt: Binder link

.. image:: https://raw.githubusercontent.com/SETI/bolides/master/docs/preview.gif

``bolides`` is a community package primarily designed to work with bolide detections from the Geostationary Lightning Mapper instruments aboard GOES-16 and GOES-17 that are published at `neo-bolide.ndc.nasa.gov <https://neo-bolide.ndc.nasa.gov>`_. But ``bolides`` can also read bolide data from ZODB database files produced by the GLM bolide detection pipeline, from `US Government sensors <https://cneos.jpl.nasa.gov/fireballs/>`_, and from your own .csv files containing bolide data.

Functionality
=============

``bolides`` puts bolide detections from various sources into a common BolideDataFrame format. With this, ``bolides`` can do things like:

- Automatically add metadata like lunar phase, solar time, and solar altitude to bolide detections.
- Filter the data sets by any variable.
- Search the data sets for particular bolides by time or location.
- Make histograms of bolides over time.
- Plot detections on arbitrary map projections, coloring by any categorical or quantitative variables.
- Plot GLM fields-of-view in the GOES-West and GOES-East positions, and filter bolide detections by the FOV.
- Augment one data set with data from another, automatically matching bolide detections from different sources.
- Pull corresponding bolide light curves from `neo-bolide.ndc.nasa.gov <https://neo-bolide.ndc.nasa.gov>`_ and plot them.
- Pull meteor shower data from the `IAU Meteor Data Center <https://www.ta3.sk/IAUC22DB/MDC2007/>`_ and plot their orbits.
- Run an `interactive webapp <https://bolides.seti.org>`_.

.. end-before-here

Documentation
=============

All package documentation is hosted at `bolides.readthedocs.io <https://bolides.readthedocs.io>`_.

Installation
============

.. installation-start

We want to make installation as easy as possible. If you have any problems with the installation process, please `open an issue <https://github.com/SETI/bolides/issues/new/choose>`_.

Dependencies
------------

If using Conda, just use Conda to install cartopy: ``conda install -c conda-forge cartopy``.

If using pip:

#. First, `PROJ <https://proj.org/install.html>`_ needs to be installed on your system using the installation instructions at the link. `GEOS <https://libgeos.org/usage/install/>`_ also needs to be installed. On Ubuntu both can be installed with ``sudo apt install proj-bin libproj-dev libgeos-dev``
#. Next, due to `known Cartopy and Shapely problems <https://github.com/SciTools/cartopy/issues/738>`_, Cartopy and Shapely need to be installed manually. This is done with: ``pip install numpy && pip install cartopy==0.18.0 shapely --no-binary cartopy --no-binary shapely``. Note that an older Cartopy version is recommended to prevent it from requiring PROJ versions not yet in common repositories. If you already have PROJ 8.0.0, you may omit the ``==0.18.0`` and install the latest Cartopy version.


The package
-----------

While the package is still in development we recommend installing from source:

#. Download this repository: ``git clone https://github.com/SETI/bolides.git``
#. Move into it: ``cd bolides``
#. Install the package in editable mode: ``pip install -e .``

Once this package is on the Python Package Index, you can install via pip using ``pip install bolides``.

.. installation-end

Tutorial
========

For a usage tutorial, go `here <https://bolides.readthedocs.io/en/latest/tutorials>`_. An interactive version is hosted on `binder <https://mybinder.org/v2/gh/SETI/bolides/master?labpath=notebooks%2Ftutorial.ipynb>`_.

.. start-after-here

Historical Note
===============

The original version of ``bolides`` was developed by Clemens Rumpf and Geert Barentsen. It has been rewritten since then, but all of the original code and functionality is still present.

Maintaining
===========

Several informational files are located throughout this repository to help in understanding and maintaining the package:

- Uploading to the Python Package Index: `<PYPI.txt>`_
- Documentation building: `<docs/README.txt>`_
- Webapp setup and maintenance: `<webapp/README.txt>`_
- Binder setup: `<binder/README.txt>`_


Acknowledgments
===============

This development is supported through NASA's Asteroid Threat Assessment Project (ATAP), which is funded through NASA's Planetary Defense Coordination Office (PDCO).
Anthony Ozerov is supported through NASA Cooperative Agreement 80NSSC19M0089.
