Metadata-Version: 2.4
Name: TeamOverbyeWeather
Version: 0.3.0
Summary: Python client for Team Overbye weather data (Texas A&M)
Project-URL: Homepage, https://github.com/ChunSikPark/Weather_data_GUI
Project-URL: Documentation, https://teamoverbye-weather.readthedocs.io
Project-URL: Repository, https://github.com/ChunSikPark/Weather_data_GUI
Project-URL: Web Portal, https://weather-data-gui.pages.dev
Project-URL: Bug Tracker, https://github.com/ChunSikPark/Weather_data_GUI/issues
Author-email: Team Overbye <overbye@tamu.edu>
License: MIT
Keywords: climate,era5,gfs,hrrr,noaa,weather
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: requests>=2.31
Requires-Dist: tqdm>=4.66
Description-Content-Type: text/markdown

# TeamOverbyeWeather

Python client for the **Team Overbye Weather Data API** at Texas A&M University —
ERA5 reanalysis, HRRR history and forecasts, and NOAA/GFS forecasts, as
PowerWorld `.pww` files.

Download, crop to a region, and crop in time, in one call.

## Installation

Not on PyPI yet — install from the repository (needs `git` on your PATH):

```bash
pip install "git+https://github.com/ChunSikPark/Weather_data_GUI.git#subdirectory=package"
```

Python 3.10 or newer. No credentials needed.

## Quick start

```python
from TeamOverbyeWeather import WeatherClient

client = WeatherClient()

# What is available?
client.sources()                        # ['era5', 'hrrr', 'noaa']
client.types("hrrr")                    # ['archive', 'current', 'forecast', ...]
client.list("hrrr", "hourly_current")   # ['2026-07-21', '2026-07-20', ...]

# Download, cropped to Texas and to a six-hour window
client.download(
    "hrrr",
    type="hourly_current",
    dates="2026-07-21",
    region="TX",
    time_start="2026-07-21T06:00",
    time_end="2026-07-21T18:00",
    dest="./data",
)
```

Cropping happens server-side, so only what you asked for crosses the network — a
Texas six-hour NOAA slice is 240 KB instead of the 120 MB full file.

One file is written per date key, already cropped, ready to open in PowerWorld.

## Selecting a region

Use exactly one of:

```python
client.download(..., region="TX")                       # one state
client.download(..., region=["TX", "OK", "NM"])         # union bounding box
client.download(..., iso="ERCOT")                       # ISO zone
client.download(..., bbox=(33.0, -100.0, 30.0, -96.0))  # lat_max, lon_min, lat_min, lon_max
```

List valid ids with `client.region_ids("states")` and `client.region_ids("iso")`.
Multiple states crop to the union rectangle, not to the state outlines.

## Selecting a time window

```python
client.download(..., time_start="2026-07-21T06:00", time_end="2026-07-21T18:00")
client.download(..., time_start="2026-07-21T06:00")   # to the end of the file
client.download(..., time_end="2026-07-21T18:00")     # from the start
```

Times are UTC and both bounds are inclusive. `datetime` objects work too.

## Data sources

| Source | Types | Date key |
|---|---|---|
| `era5` | `historical`, `texas` | `YYYY-Qn` |
| `hrrr` | `current`, `archive` (15-min), `hourly_current`, `hourly_archive`, `forecast` | `YYYY-MM-DD`, `YYYY-MM`, `YYYY-MM-DDTHHZ` |
| `noaa` | `recent`, `archive` | `YYYY-MM-DDTHHZ` |

Always take date keys from `client.list(source, type)` — formats differ per
source, and NOAA `recent` / `archive` are separate folders rather than a date
split.

## Reading the data

```python
from TeamOverbyeWeather import pww_io

header, stations, arr = pww_io.read_pww(open(path, "rb").read())
arr.shape        # (time, variable, latitude, longitude)
```

`255` marks missing data. Latitude ascends, longitude descends.

## Documentation

Full guides and API reference: **https://teamoverbye-weather.readthedocs.io**

Point-and-click alternative: **https://weather-data-gui.pages.dev**

## License

MIT
