Metadata-Version: 2.2
Name: meteora
Version: 0.3.0
Summary: Pythonic interface to access data from meteorological stations
Author-email: Martí Bosch <marti.bosch@epfl.ch>
License: GPL-3.0
Project-URL: Repository, https://github.com/martibosch/meteora
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dask
Requires-Dist: geopandas>=1.0.0
Requires-Dist: matplotlib
Requires-Dist: polars
Requires-Dist: pyarrow
Requires-Dist: requests
Requires-Dist: requests-cache
Requires-Dist: requests-oauthlib
Requires-Dist: tqdm
Provides-Extra: cx
Requires-Dist: contextily; extra == "cx"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: commitizen; extra == "dev"
Requires-Dist: pip; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: toml; extra == "dev"
Requires-Dist: tox; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: doc
Requires-Dist: myst-parser; extra == "doc"
Requires-Dist: nbsphinx; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: sphinxemoji; extra == "doc"
Provides-Extra: ox
Requires-Dist: osmnx; extra == "ox"
Provides-Extra: test
Requires-Dist: coverage[toml]; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: python-dotenv[cli]; extra == "test"
Requires-Dist: requests-mock; extra == "test"
Requires-Dist: ruff; extra == "test"

[![PyPI version fury.io](https://badge.fury.io/py/meteora.svg)](https://pypi.python.org/pypi/meteora)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/meteora.svg)](https://anaconda.org/conda-forge/meteora)
[![Documentation Status](https://readthedocs.org/projects/meteora/badge/?version=latest)](https://meteora.readthedocs.io/en/latest/?badge=latest)
[![tests](https://github.com/martibosch/meteora/actions/workflows/tests.yml/badge.svg)](https://github.com/martibosch/meteora/blob/main/.github/workflows/tests.yml)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/martibosch/meteora/main.svg)](https://results.pre-commit.ci/latest/github/martibosch/meteora/main)
[![codecov](https://codecov.io/gh/martibosch/meteora/graph/badge.svg?token=smWkIfB7mM)](https://codecov.io/gh/martibosch/meteora)
[![GitHub license](https://img.shields.io/github/license/martibosch/meteora.svg)](https://github.com/martibosch/meteora/blob/main/LICENSE)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/martibosch/meteora/HEAD?labpath=docs%2Fuser-guide%2Fasos-example.ipynb)

# Meteora

Pythonic interface to access data from meteorological stations. Key features:

- easily stream data [from multiple providers (e.g., Automated Surface/Weather Observing Systems (ASOS/AWOS), MetOffice...)](https://meteora.readthedocs.io/en/latest/supported-providers.html) into pandas data frames.
- user-friendly arguments to filter data by region, variables or date ranges.
- request caching with [requests-cache](https://github.com/requests-cache/requests-cache) to avoid re-downloading data and help bypassing API limits.

## Overview

Meteora provides a set of provider-specific clients to get observations from meteorological stations. For instance, it can be used to stream [the one-minute ASOS data](https://madis.ncep.noaa.gov/madis_OMO.shtml) from the [Iowa Environmental Mesonet](https://mesonet.agron.iastate.edu/request/asos/1min.phtml) into a pandas data frame:

```python
from meteora.clients import ASOSOneMinIEMClient

region = "Oregon"
variables = ["temperature", "pressure", "precipitation", "surface_wind_speed"]
start = "2021-08-13"
end = "2021-08-16"

client = ASOSOneMinIEMClient(region=region)
ts_df = client.get_ts_df(variables, start=start, end=end)
ts_df.head()
```

<div>
<table border="1" class="dataframe">
  <thead>
    <tr style="text-align: right;">
      <th></th>
      <th></th>
      <th>temperature</th>
      <th>pressure</th>
      <th>precipitation</th>
      <th>surface_wind_speed</th>
    </tr>
    <tr>
      <th>station</th>
      <th>valid(UTC)</th>
      <th></th>
      <th></th>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th rowspan="5" valign="top">AST</th>
      <th>2021-08-13 00:00:00</th>
      <td>68.0</td>
      <td>29.942</td>
      <td>0.0</td>
      <td>10.0</td>
    </tr>
    <tr>
      <th>2021-08-13 00:01:00</th>
      <td>67.0</td>
      <td>29.942</td>
      <td>0.0</td>
      <td>10.0</td>
    </tr>
    <tr>
      <th>2021-08-13 00:02:00</th>
      <td>67.0</td>
      <td>29.942</td>
      <td>0.0</td>
      <td>10.0</td>
    </tr>
    <tr>
      <th>2021-08-13 00:03:00</th>
      <td>67.0</td>
      <td>29.942</td>
      <td>0.0</td>
      <td>9.0</td>
    </tr>
    <tr>
      <th>2021-08-13 00:04:00</th>
      <td>68.0</td>
      <td>29.942</td>
      <td>0.0</td>
      <td>8.0</td>
    </tr>
  </tbody>
</table>
</div>

We can also get the station locations using the `stations_gdf` property:

```python
import contextily as cx

ax = client.stations_gdf.plot()
cx.add_basemap(ax, crs=client.stations_gdf.crs)
```

![oregon-stations](https://github.com/martibosch/meteora/raw/main/docs/figures/oregon-stations.png)

See [the user guide](https://meteora.readthedocs.io/en/latest/user-guide.html) for more details about the features of Meteora as well as the [list of supported providers](https://meteora.readthedocs.io/en/latest/supported-providers.html).

## Installation

The easiest way to install Meteora is with conda/mamba:

```bash
conda install -c conda-forge meteora
```

Alternatively, if [geopandas dependencies are installed correctly](https://geopandas.org/en/latest/getting_started/install.html), you can install Meteora using pip:

```bash
pip install meteora
```

## See also

Meteora intends to provide a unified way to access data from meteorological stations from multiple providers. The following libraries provide access to data from a specific provider:

- [martibosch/agrometeo-geopy](https://github.com/martibosch/agrometeo-geopy)
- [martibosch/netatmo-geopy](https://github.com/martibosch/netatmo-geopy)

Eventually these packages will be fully integrated into Meteora.

## Acknowledgements

- The logging system is based on code from [gboeing/osmnx](https://github.com/gboeing/osmnx).
- This package was created with the [martibosch/cookiecutter-geopy-package](https://github.com/martibosch/cookiecutter-geopy-package) project template.
- With the support of the École Polytechnique Fédérale de Lausanne (EPFL).
