gmn-python-api 0.0.4

GMN Python API

Python API for accessing open Global Meteor Network (GMN) meteor trajectory data. Global meteor data is generated by the GMN every 6 hours using a network of low-light cameras. Meteor properties (radiants, orbits, magnitudes and masses) are produced by the GMN and are available through this API.

Demo on Google Colab

Features

• Listing available daily and monthly csv trajectory summary files from the GMN data directory.

• Downloading specific daily and monthly csv trajectory summary files from the data directory.

• Functions for loading the trajectory summary data into a Pandas DataFrame or Numpy array.

• TODO: Functions for loading data from the future GMN Data Platform REST API.

Requirements

• Python 3.7, 3.8, 3.9 or 3.10

Installation

You can install GMN Python API via pip from PyPI:

$ pip install gmn-python-api

Or for the latest development code, through TestPyPI or directly from GitHub via pip:

$ pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple gmn-python-api==<version>
Or
$ pip install git+https://github.com/gmn-data-platform/gmn-python-api

See the Troubleshooting section if you encounter installation issues.

Usage

Simple example:

from datetime import datetime
from gmn_python_api.data_directory import get_daily_file_content_by_date
from gmn_python_api.trajectory_summary_reader import read_trajectory_summary_as_dataframe

# Load the contents of a specific daily trajectory summary file into a Pandas DataFrame
trajectory_summary_file_content = get_daily_file_content_by_date(datetime(2019, 7, 24))
trajectory_summary_dataframe = read_trajectory_summary_as_dataframe(trajectory_summary_file_content)

print("For the 24th of July 2019, the following data was recorded by the GMN:")
print(f"- {trajectory_summary_dataframe['Vgeo (km/s)'].max()} km/s was the fastest geostationary velocity out of all meteors for that day.")
print(f"- {trajectory_summary_dataframe.loc[trajectory_summary_dataframe['IAU (code)'] == 'PER'].shape[0]} meteors were estimated to be part of the Perseids shower.")
print(f"- Station #{trajectory_summary_dataframe['Num (stat)'].mode().values[0]} recorded the highest number of meteors.")

# Output:
# For the 24th of July 2019, the following data was recorded by the GMN:
# - 65.38499 km/s was the fastest geostationary velocity out of all meteors for that day.
# - 8 meteors were estimated to be part of the Perseids shower.
# - Station #2 recorded the highest number of meteors.

Please see the Usage and API section for more details. Or Troubleshooting for common problems.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, GMN Python API is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

Hypermodern Python Cookiecutter template.