A specialized wind analysis dashboard for wing foiling conditions in Morrison, Colorado. Analyzes morning wind patterns to identify ideal wing foiling sessions based on sustained average wind speeds.

# Setup
cp .env.example .env  # Add your Ecowitt credentials
pip install -r requirements.txt

# Run dashboard
streamlit run app.py

• 🟥 Strong Gear Day (≥20 mph avg): Use smaller wing/board
• 🟨 Perfect Foiling (15-19 mph avg): Ideal sustained winds
• ⬜ Too Light (<15 mph avg): Below foiling minimum

• Wing Foiling Guide - Complete usage guide and features
• Development Setup - Setup, troubleshooting, and architecture
• Changelog - Recent updates and changes
• API Documentation - Ecowitt API integration details

• Real-time wind analysis with 5-minute data resolution
• Automatic data collection for today's data when accessed after 8am
• Wing foiling condition detection based on sustained winds
• Interactive charts showing time series and daily patterns
• Gear recommendations for different wind conditions
• Export functionality for detailed analysis and debugging support
• Morrison timezone handling for accurate morning hours
• 🔮 Prediction tracking with accuracy analysis and verification
• 🎯 Model improvement through systematic forecast verification

1. Data Status - 7-day data availability overview
2. Weather Analysis - Current katabatic scoring and conditions
3. 🔮 Prediction Tracking - Forecast accuracy and verification
4. Key Metrics - Weekly wind event summary
5. Wind Charts - Time series and daily average patterns
6. Foiling Analysis - Detailed condition comparison
7. Data Tables - Events, measurements, and export tools

Built specifically for wing foiling enthusiasts who need reliable morning wind analysis in Morrison, Colorado.
Purpose: Detect and analyze strong wind events during morning hours

• 📊 Data Collection: Retrieve wind history from Ecowitt API with 5-minute resolution
• 🔄 Automatic Collection: Today's data collected automatically when accessed after 8am Morrison time
• 🌪️ Katabatic Detection: Identify wind speeds >15mph between 6-8am local time
• 📈 Interactive Dashboard: Visual representation of wind patterns and events
• 🗄️ Local Storage: SQLite database for historical data
• 🕐 Timezone Handling: All data normalized to Morrison, CO local time
• 📋 Data Tables: Human-readable tabular data display
• 🔍 Gap Management: Detect and fill missing data days

# Clone and navigate to project
cd katabatic-analyzer

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Use the interactive setup script:

# Run the interactive setup
python setup.py

Or configure manually:

# Copy environment template
cp .env.example .env

# Edit .env file with your Ecowitt API credentials
# Get credentials from: https://www.ecowitt.net/

Required environment variables in .env:

ECOWITT_APPLICATION_KEY=your_application_key_here
ECOWITT_API_KEY=your_api_key_here
ECOWITT_DEVICE_MAC=FF:FF:FF:FF:FF:FF

# Run foundation tests
python test_foundation.py

# Test API connection (requires credentials)
python test_api.py

# Start Streamlit dashboard
streamlit run app.py

Open http://localhost:8501 in your browser.

The dashboard provides several data collection options:

1. Collect Today: Get data for the current day (only available after 8am Morrison time)
2. Collect Yesterday: Get data for the previous day
3. Fill Missing Days: Automatically collect data for any missing days in the last week
4. Custom Date Range: Collect data for a specific date range

Automatic Collection: When you open the dashboard after 8am Morrison time, the system will automatically check if today's data is available and collect it if needed. This ensures you always have current data for wind analysis.

For troubleshooting and analysis support, the dashboard includes comprehensive debug export tools:

Use the "Export Data" tab in the dashboard for:

• Quick Export: Standard CSV exports with date ranges and filters
• Debug Export: Comprehensive multi-file export including:
  • Raw measurements, morning data, and strong wind events
  • Daily summaries and data quality metrics
  • System configuration and database statistics

# Quick 14-day debug export
python quick_export.py

# Custom debug export with options
python export_debug_data.py --days 30 --output-dir ./debug_exports

The debug export creates 8 files with complete system state for analysis:

• *_raw_measurements.csv - All wind measurements
• *_morning_hours.csv - 6-8am data only
• *_strong_wind_events.csv - Events ≥15mph during morning hours
• *_daily_summaries.csv - Daily statistics and foiling conditions
• *_data_quality.csv - Data coverage and gap analysis
• *_config.json - System configuration and analysis settings
• *_database_stats.json - Database schema and statistics
• *_summary.json - Export overview and data counts

💡 Perfect for sharing with support or detailed offline analysis!

The application now includes comprehensive prediction tracking to measure forecast accuracy and improve the katabatic wind model over time.

• Automatic Prediction Storage: All katabatic wind predictions are automatically stored when generated
• Smart Verification: Predictions are verified against actual wind data after target dates pass
• Accuracy Analytics: Detailed statistics show model performance by confidence level
• Historical Analysis: Track prediction accuracy trends over time
• Model Insights: Identify areas for prediction algorithm improvement

1. Prediction Generation: Weather analysis generates katabatic predictions daily
2. Auto-Storage: Predictions are stored with timestamps, confidence levels, and expected conditions
3. Verification Process: After target dates pass, predictions are compared with actual wind data
4. Accuracy Scoring: Each prediction gets an accuracy score (0.0-1.0) based on multiple factors:
   • Peak wind detection accuracy
   • Wind direction accuracy within predicted ranges
   • Wind strength correlation with katabatic score
   • Confidence level calibration

Dashboard View: Check the "🔮 Prediction Tracking & Accuracy" section to see:

• Recent predictions with verification status
• Accuracy statistics by confidence level
• Model performance insights and recommendations
• Manual verification controls

Automated Verification:

# Run daily verification (can be automated via cron)
python3 daily_verification.py

Key Metrics Tracked:

• Overall prediction accuracy
• Accuracy by confidence level (HIGH, MODERATE, LOW, VERY LOW)
• Peak detection rate (did predicted winds actually occur?)
• Direction accuracy (were winds from predicted directions?)
• Model calibration (do confidence levels match actual accuracy?)

• Automatic Data Collection: Today's data is automatically collected when accessing the dashboard after 8am Morrison time
• Data Collection Panel: One-click data collection with progress indicators
• Data Status: Visual calendar showing available data for the last 7 days with gap detection
• Weather Analysis: Real-time katabatic scoring with current conditions analysis
• 🔮 Prediction Tracking: Forecast accuracy analysis with verification controls
• Key Metrics: Summary of strong wind events, strongest winds, and recent activity
• Interactive Charts: Time series plots of morning wind speeds with strong wind event highlights
• Data Tables: Detailed views of strong wind events, recent measurements, and daily summaries
• Export Functionality: Download data as CSV files with customizable filters, plus comprehensive debug exports for analysis support

The system automatically:

• Converts all timestamps to Morrison, CO local time (America/Denver)
• Flags measurements during morning hours (6-8am)
• Identifies strong wind events (wind speed >15mph during morning hours)
• Calculates daily, weekly, and trend statistics
• Validates data quality and filters invalid readings
• Provides comprehensive error handling and user feedback

katabatic-analyzer/
├── README.md                 # This file
├── requirements.txt          # Python dependencies
├── .env.example             # Environment template
├── config.py               # Configuration settings
├── app.py                  # Main Streamlit dashboard
├── data_collector.py       # Ecowitt API integration
├── analyzer.py            # Wind analysis and katabatic detection
├── database.py            # SQLite database operations
├── timezone_utils.py      # Morrison, CO timezone handling
├── test_foundation.py     # Foundation validation script
├── test_api.py           # API connection test script
├── setup.py              # Interactive setup script
├── reset_database.py     # Database reset/migration script
├── data/
│   ├── wind_data.db       # SQLite database (created automatically)
│   └── logs/              # Application logs
├── tests/                 # Unit tests
└── docs/                  # Documentation

Default katabatic detection parameters (configurable in config.py):

• Threshold: 15 mph wind speed
• Morning Hours: 6:00 AM - 8:00 AM (Morrison time)
• Timezone: America/Denver

The application uses Ecowitt's device history API:

• Resolution: 5-minute intervals for recent data
• Data Fields: Wind speed, wind gust, wind direction
• Rate Limits: Respectful request timing with delays

The SQLite database stores wind measurements with these key fields:

• datetime_local: Morrison, CO local time
• wind_speed: Wind speed in mph
• wind_gust: Wind gust in mph
• wind_direction: Wind direction in degrees
• is_morning_hours: Boolean flag for 6-8am period
• is_strong_wind_event: Boolean flag for strong wind events

# Run unit tests
pytest tests/

# Run with coverage
pytest tests/ --cov=.

# Run foundation tests
python test_foundation.py

# Format code
black .

# Lint code
flake8 .

Logs are written to ./data/logs/wind_analyzer.log with configurable verbosity.

This project uses the Ecowitt Weather API. Key endpoints:

• Device History: /api/v3/device/history
• Documentation: See docs/api-docs/Get-Device-History.md

• Respectful request timing (1 second between requests)
• Daily data collection in single-day chunks
• Automatic retry with exponential backoff

1. "Configuration error": Check that your .env file has valid API credentials
2. "No data collected": Verify your device MAC address and API permissions
3. "Import errors": Ensure all dependencies are installed: pip install -r requirements.txt

1. Check the logs in ./data/logs/ for detailed error messages
2. Run python test_foundation.py to validate setup
3. Verify your Ecowitt device is online and reporting data

• Local Only: All data stored locally in SQLite database
• No Cloud: No data transmitted to external services (except Ecowitt API)
• Backup: Database file at ./data/wind_data.db can be backed up manually

This is a personal analysis project for Morrison, CO wind patterns. The codebase is designed to be modular and extensible.

• Local Operation: No cloud dependencies beyond API calls
• Manual Control: User-triggered data collection and analysis
• Timezone Accuracy: All data properly normalized to Morrison time
• Data Integrity: Comprehensive validation and error handling

This project is for personal use analyzing local wind patterns in Morrison, Colorado.

• ✅ Foundation Implementation - Complete core architecture
• ✅ Data Collection - Ecowitt API integration with proper error handling
• ✅ Database - SQLite schema with wind data storage and indexing
• ✅ Dashboard - Streamlit interface with data collection controls
• ✅ Katabatic Detection - Algorithm for identifying >15mph morning winds
• ✅ Timezone Handling - Morrison, CO timezone conversion and validation
• ✅ Testing - Comprehensive unit tests and validation scripts
• ✅ Documentation - User guide and setup instructions
• ✅ Export Features - CSV data export with filtering options
• ✅ Enhanced UI - Progress bars, status indicators, and error feedback
• ✅ Setup Tools - Interactive configuration and testing scripts