Skip to main content

Vantage Forecaster - Complete Beginner's Guide

This guide walks you through every feature of the Vantage Forecaster portable application.

Table of Contents​

  1. Getting Started
  2. Interface Overview
  3. Data Source Configuration
  4. Running Demand Forecasts
  5. Running Capacity Factor Forecasts
  6. Scheduler Tab
  7. Settings Tab
  8. Output Files
  9. Troubleshooting

Getting Started​

Installation​

  1. Extract the ZIP file to any folder (e.g., C:\VantageForecaster\)
  2. Double-click Vantage Forecaster.exe
  3. No installation wizard - it just works!

First Launch Checklist​

  • Application opens without errors
  • Main window displays correctly
  • All tabs are visible (Forecast, Scheduler, Settings)

Interface Overview​

The application has three main tabs:

Forecast Tab (Main)​

  • Data Source Selection - Choose CSV folders or SQLite database
  • Forecast Options - Enable/disable Demand and CFAC forecasts
  • Date Range - Set forecast start and end dates
  • Run Button - Execute the forecast
  • Status Panel - Real-time progress and output

Scheduler Tab​

  • Automated Forecasts - Set up recurring forecasts
  • Run History - View past forecast runs
  • Gateway Integration - Push forecasts to remote server

Settings Tab​

  • Data Paths - Configure training data locations
  • API Keys - Weather API configuration
  • Gateway Settings - SFTP server configuration
  • Display Options - UI preferences

Data Source Configuration​

  1. Click "Select Database"
  2. Navigate to data\iload.db (regional) or data\iload_zonal.db (zonal)
  3. The Database Info Panel will display:
    • Total demand records
    • Date range coverage
    • Detected regions/zones

Auto-Detection:

  • 3 regions (CLUZ, CVIS, CMIN) = Regional mode
  • 14 zones (01NLUZ, 02METRO, etc.) = Zonal mode

Option 2: CSV Directory Mode​

  1. Toggle to CSV Mode
  2. Set paths for:
    • Demand Data Directory: Folder with demand CSV files
    • CFAC Data Directory: Folder with capacity factor CSVs
    • Weather Cache Directory: weather_cache

Running Demand Forecasts​

Step 1: Enable Demand Forecast​

Check the "Enable Demand Forecast" checkbox.

Step 2: Select Demand Mode​

ModeDescriptionOutput File
Regional (3)3 main regions: CLUZ, CVIS, CMINFC_DEM_*.csv
Zonal (14)14 sub-regions for granular analysisFC_ZDEM_*.csv
BothGenerate both regional and zonalBoth files

Step 3: Set Date Range​

  • Start Date: First day of forecast
  • End Date: Last day of forecast

Step 4: Configure Options​

OptionDescriptionDefault
ModelHybrid (recommended) or XGBoostHybrid
LSTM CorrectionImproves morning ramp accuracyOff
Scaling %Scale output values100%

Step 5: Run Forecast​

  1. Click "Run Forecast"
  2. Watch progress bar and status messages
  3. Output file saved to configured output directory

Output Format​

datetime,CLUZ,CVIS,CMIN
2026-03-11 00:00,8500.5,2100.3,1800.2
2026-03-11 01:00,8200.1,2050.8,1750.6
...

Running Capacity Factor Forecasts​

Step 1: Enable CFAC Forecast​

Check the "Enable CFAC Forecast" checkbox.

Step 2: Select Model​

ModelBest ForAccuracy
Hybrid (Default)General useWind: ~73% MAPE, Solar: ~16% MAPE
Hybrid + LSTMTemporal patternsExperimental
Legacy XGBoostComparison onlyLower accuracy

Step 3: Configure Station-Type Settings​

Per-Type Model Settings:

For Wind Stations:

SettingRecommendedWhy
Use XGBoostOffHybrid is better for wind
Asymmetric LossOffWind patterns are symmetric
Bias CorrectionOffAuto-calibration handles this

For Solar Stations:

SettingRecommendedWhy
Use XGBoostOnBetter for solar variation
Asymmetric LossOnPenalizes under-prediction
Bias CorrectionOptionalPer-station calibration active

Step 4: Run Forecast​

  1. Click "Run Forecast"
  2. Training phase (may take several minutes)
  3. Prediction phase
  4. Auto-calibration applies corrections

Output Format​

datetime,01BURGOS,01LAOAG,01CURIMAO_S,...
2026-03-11 00:00,0.42,0.38,0.00,...
2026-03-11 01:00,0.45,0.41,0.00,...
...

Note: Solar stations show 0.00 at night (expected behavior).

Scheduler Tab​

Overview​

The Scheduler automates daily and weekly forecast generation.

Running Scheduled Forecasts​

  1. Go to Scheduler tab
  2. Set the As-of Date (defaults to today)
  3. Choose forecast types:
    • Daily: Next-day forecast (D+1)
    • Weekly: 7-day forecast (D+7)
  4. Click "Run Scheduled Forecast"

Output Structure​

output/forecasts/
└── 2026-03-10/
    ├── DA_DEM_2026-03-11.csv      # Day-ahead demand
    ├── DA_MHCF_2026-03-11.csv     # Day-ahead capacity factor
    ├── WA_DEM_2026-03-11_17.csv   # Week-ahead demand
    └── WA_MHCF_2026-03-11_17.csv  # Week-ahead capacity factor

Gateway Push​

If configured, forecasts can be automatically pushed to the Vantage Gateway:

  1. Enable "Auto Push to Gateway" in Settings
  2. Configure gateway credentials
  3. Forecasts are pushed after each run

Settings Tab​

Data Paths​

SettingDescriptionExample
Demand Training PathHistorical demand dataData Samples\Demand
CFAC Training PathCapacity factor dataData Samples\Capacity Factor
Weather CacheCached weather filesweather_cache
Output DirectoryForecast output locationoutput

API Configuration​

Visual Crossing API Key:

  • Required for fetching weather forecasts
  • Enter your API key in the Settings tab
  • Or edit config.json directly

Gateway Settings​

SettingDescription
HostGateway server IP/hostname
PortSSH port (default: 22)
UsernameSFTP username
PasswordSFTP password

Display Settings​

SettingDescription
Window SizeRemembered between sessions
ThemeLight/Dark mode (if available)

Output Files​

Naming Convention​

PrefixMeaning
FC_Full-range forecast
DA_Day-ahead forecast
WA_Week-ahead forecast
DEM_Demand forecast
ZDEM_Zonal demand forecast
MHCF_ / CF_Capacity factor forecast

Examples​

FilenameDescription
FC_DEM_2026-03-11_2026-03-17.csvRegional demand, Mar 11-17
FC_ZDEM_2026-03-11_2026-03-17.csvZonal demand, Mar 11-17
FC_CF_2026-03-11_2026-03-17.csvCapacity factor, Mar 11-17
DA_DEM_2026-03-11.csvDay-ahead demand for Mar 11

Custom Naming​

  1. Click "Naming Options" on the Forecast tab
  2. Set custom prefix, suffix, or full filename
  3. Example: FORECAST_ prefix + _v2 suffix = FORECAST_2026-03-11_v2.csv

Troubleshooting​

Application Won't Start​

Symptoms: Double-clicking exe does nothing or shows error.

Solutions:

  1. Check Windows Defender isn't blocking the app
  2. Ensure you extracted the full ZIP (not running from within the archive)
  3. Verify cli\node\node.exe exists in the folder

"Database Not Found" Error​

Symptoms: Error when selecting database mode.

Solutions:

  1. Verify data\iload.db exists
  2. Use full path if relative path doesn't work
  3. Check file isn't locked by another application

Forecast Runs But Output is Empty​

Symptoms: Forecast completes but CSV has no data.

Solutions:

  1. Check date range is valid (not in the future beyond weather data)
  2. Verify training data covers the forecast period
  3. Check status panel for specific errors

Weather Fetch Fails​

Symptoms: "Failed to fetch weather" errors.

Solutions:

  1. Check internet connection
  2. Verify API key in Settings or config.json
  3. Weather cache may be corrupted - delete and retry

Slow Performance​

Symptoms: Forecasts take very long or application hangs.

Solutions:

  1. Close other applications to free memory
  2. Use shorter date ranges for testing
  3. Check disk space (needs ~5GB free)

Status Panel Shows Errors​

Common Errors:

ErrorCauseSolution
SQLITE_CANTOPENDatabase path wrongReconfigure in Settings
Weather data missingNo cached weatherCheck internet, verify cache path
Training data insufficientNot enough historyNeed at least 30 days of data
Model failed to convergePoor data qualityCheck for gaps in training data

Tips for Best Results​

Demand Forecasting​

  • Use Hybrid model for best accuracy
  • Enable LSTM Correction for improved morning ramps
  • Regional mode is faster; Zonal mode is more detailed

Capacity Factor Forecasting​

  • Hybrid model is always recommended
  • Enable XGBoost + Asymmetric Loss for solar
  • Keep default settings for wind
  • Allow 2-5 minutes for model training

General Tips​

  • Run forecasts during off-peak hours for faster weather fetching
  • Keep weather cache up to date for offline operation
  • Use the Scheduler for daily automated runs
  • Check output files immediately after running to verify success

Getting Help​

  1. Check this guide first
  2. Review TESTING_CHECKLIST.md for known issues
  3. Check the status panel for detailed error messages
  4. Contact the development team with:
    • Screenshot of the error
    • Steps to reproduce
    • Contents of the output folder