README.md

---
title: ECMWF Complete Data Explorer
emoji: 🌍
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.42.0
app_file: app.py
pinned: false
license: gpl-3.0
---

# 🌍 ECMWF Complete Data Explorer

A comprehensive Gradio web application providing unified access to **all** ECMWF free meteorological data:

## 🚀 **Open Data** (No Authentication Required)
- **Real-time operational forecasts** from IFS and AIFS models
- **Ensemble forecasts** for uncertainty quantification
- Updated every 6 hours, available 7-9 hours after forecast initialization
- 0.25° resolution (~25km global coverage)

## 📊 **Climate Data Store (CDS)** (Free Account Required)
- **ERA5 reanalysis data** from 1940 to present
- **Seasonal forecasts** up to 7 months ahead
- Historical climate data and long-range predictions

## ✨ Key Features

### 🌟 **Comprehensive Data Access**
- **Open Data**: Real-time IFS & AIFS operational forecasts (no account needed)
- **Ensemble Forecasts**: 51-member ensemble predictions for uncertainty analysis
- **ERA5 Reanalysis**: Complete historical weather data from 1940-present
- **Seasonal Forecasts**: Long-range predictions up to 7 months ahead

### 🎨 **Advanced Visualization**
- Automatic spatial plots and time series generation
- Support for both NetCDF and GRIB2 file formats
- Interactive web interface with immediate data preview
- Comprehensive data information display

### ⚙️ **Flexible Configuration**
- Multiple forecast models (IFS traditional, AIFS AI-powered)
- Extensive parameter selection (temperature, precipitation, pressure, wind, etc.)
- Customizable forecast steps (0-360 hours)
- Geographic area filtering for targeted analysis

## 🚀 **INSTANT ACCESS - NO SETUP REQUIRED!**

### 🆓 **FREE Real-time Weather Maps (No Account Needed)**
```bash
# That's it - just run it!
pip install -r requirements.txt
python simple_app.py
```

**✅ Zero configuration needed for live weather maps!**
- No API keys required
- No account registration  
- No authentication setup
- Instant access to professional weather data

### 📊 **Historical Data (Optional - Free Account)**
Only needed if you want historical ERA5 data:
1. Create free [ECMWF account](https://accounts.ecmwf.int/) (optional)
2. Configure CDS access (only for historical data)

**🌟 Most users can start immediately with live forecasts!**

## 📦 Installation

```bash
# Clone repository
git clone [repository-url]
cd ECMWF_PLayground

# Install dependencies
pip install -r requirements.txt

# Run application (simplified version for stable deployment)
python simple_app.py

# Or run full version (may experience Gradio compatibility issues)
python ecmwf_gradio_app.py
```

### Dependencies
- `ecmwf-opendata>=0.3.0` - Access to real-time ECMWF forecasts
- `cdsapi>=0.7.4` - Climate Data Store API client
- `gradio>=5.9.1` - Web interface framework
- `xarray`, `matplotlib` - Data processing and visualization
- `cfgrib` - GRIB file support

## 🎯 Available Data & Parameters

### 🌊 **Open Data Parameters**
| Code | Description | Units |
|------|-------------|--------|
| **2t** | 2m Temperature | K |
| **msl** | Mean Sea Level Pressure | Pa |
| **10u/10v** | 10m Wind Components | m/s |
| **tp** | Total Precipitation | m |
| **2d** | 2m Dewpoint Temperature | K |
| **sp** | Surface Pressure | Pa |
| **tcwv** | Total Column Water Vapour | kg/m² |
| **100u/100v** | 100m Wind Components | m/s |
| **strd** | Surface Thermal Radiation | W/m² |
| **ssrd** | Surface Solar Radiation | W/m² |

### 🤖 **Forecast Models**
- **IFS (Integrated Forecast System)**: Traditional numerical weather prediction
- **AIFS (AI Forecast System)**: Machine learning-powered forecasting

### ⏰ **Forecast Types**
- **fc (Forecast)**: Future weather predictions (0-240+ hours)
- **an (Analysis)**: Current weather conditions 
- **pf (Ensemble)**: 51-member probability forecasts

### 📊 **CDS Historical Data**
- **ERA5 Reanalysis**: 1940-present, hourly data
- **Seasonal Forecasts**: Up to 7 months ahead
- Multiple variables with geographic subsetting

## Data Formats

- Downloaded data is in NetCDF format
- Visualizations are automatically generated as PNG images
- Data information includes dimensions, variables, and time ranges

## Important Notes

- **Open Data**: All data accessed through this application is provided under CC BY 4.0 license
- **Usage Limits**: Free accounts have usage limitations
- **Download Time**: Large datasets may take several minutes to download
- **Storage**: Downloaded files are stored in temporary directories
- **Internet Required**: Active internet connection needed for data retrieval

## Troubleshooting

### Current Known Issues

**⚠️ Gradio JSON Schema Error**: The main application (`ecmwf_gradio_app.py`) may experience compatibility issues with certain Gradio versions causing `TypeError: argument of type 'bool' is not iterable`. 

**✅ Workaround**: Use the simplified version (`simple_app.py`) for stable deployment.

### Common Issues

1. **API Key Error**: Ensure your `~/.cdsapirc` file is correctly formatted and contains valid credentials
2. **Download Failures**: Check internet connection and verify the requested data exists
3. **Plotting Errors**: Some datasets may have different structures that affect visualization
4. **Memory Issues**: Large datasets may require more RAM for processing
5. **Gradio Compatibility**: If experiencing deployment issues, switch to `simple_app.py`

### Getting Help

- [CDS Documentation](https://cds.climate.copernicus.eu/how-to-api)
- [ECMWF User Support](https://confluence.ecmwf.int/display/UDOC/ECMWF+User+Documentation)
- [CDS Forum](https://forum.ecmwf.int/)

## License

This application is provided as-is for educational and research purposes. All data accessed through the ECMWF CDS is subject to the respective dataset licenses.

## Acknowledgments

- ECMWF for providing free access to climate data
- Copernicus Climate Change Service (C3S) for the Climate Data Store
- The open-source Python scientific computing community