@neural-trader/example-energy-forecasting

Self-learning energy forecasting with conformal prediction and swarm-based ensemble models.

Features

- Multi-Model Ensemble: ARIMA, LSTM, Transformer, and Prophet models
- Conformal Prediction: Guaranteed coverage prediction intervals with @neural-trader/predictor
- Swarm-Based Optimization: Parallel hyperparameter exploration for optimal model selection
- Adaptive Learning: Online model updates and horizon-specific model weighting
- Seasonal Pattern Detection: Automatic detection and modeling of seasonal components
- Dual Implementation: Pure TypeScript with automatic WASM/Native acceleration via @neural-trader/predictor
- Uncertainty Quantification: Statistically rigorous prediction intervals with configurable confidence levels

Supported Domains

- ☀️ Solar Generation: Photovoltaic power forecasting with daily cycles
- 💨 Wind Power: Wind turbine generation with high variability
- ⚡ Electricity Demand: Load forecasting with multi-seasonal patterns
- 🌡️ Temperature: Weather prediction with seasonal trends

Installation

``bash
npm install @neural-trader/example-energy-forecasting
`

Quick Start

`typescript
import { EnergyForecaster, EnergyDomain, ModelType } from '@neural-trader/example-energy-forecasting';

// Create forecaster
const forecaster = new EnergyForecaster(EnergyDomain.SOLAR, {
alpha: 0.1, // 90% confidence intervals
horizon: 48, // 48-hour forecast
seasonalPeriod: 24, // Daily seasonality
enableAdaptive: true,
ensembleConfig: {
models: [ModelType.ARIMA, ModelType.LSTM, ModelType.PROPHET]
}
});

// Train with historical data
const historicalData = [
{ timestamp: Date.now(), value: 150 },
// ... more data points
];
await forecaster.train(historicalData);

// Generate forecast
const forecast = await forecaster.forecast(48);

// Access predictions with confidence intervals
forecast.forecasts.forEach(f => {
console.log(Time: ${new Date(f.timestamp).toISOString()});
console.log(Forecast: ${f.pointForecast});
console.log(Interval: [${f.interval.lower}, ${f.interval.upper}]);
console.log(Confidence: ${f.confidence * 100}%);
});
`

Architecture

$3

#### 1. EnergyForecaster
Main forecasting system that orchestrates ensemble models and conformal prediction.

`typescript
const forecaster = new EnergyForecaster(EnergyDomain.SOLAR, config);
await forecaster.train(data);
const forecast = await forecaster.forecast(48);
`

#### 2. EnsembleSwarm
Swarm-based hyperparameter optimization and adaptive model weighting.

`typescript
const ensemble = new EnsembleSwarm({
models: [ModelType.ARIMA, ModelType.LSTM],
adaptiveLearningRate: 0.05,
retrainFrequency: 100
});
await ensemble.trainEnsemble(trainingData, validationData);
`

#### 3. EnergyConformalPredictor
Wrapper around @neural-trader/predictor for uncertainty quantification.

`typescript
const predictor = new EnergyConformalPredictor(ModelType.ARIMA, {
alpha: 0.1,
calibrationSize: 2000
}, true); // adaptive mode

await predictor.initialize();
await predictor.calibrate(historicalData, predictions);
`

$3

All models implement the ForecastingModel interface:

- ARIMAModel: Exponential smoothing with trend
- LSTMModel: Recurrent patterns with attention-like weights
- TransformerModel: Self-attention mechanism
- ProphetModel: Trend + seasonality decomposition

Examples

Run the included examples:

`bash


Solar generation forecasting

npm run example:solar

Wind power forecasting

npm run example:wind

Electricity demand forecasting

npm run example:demand

Temperature prediction

npm run example:temperature
`

Configuration

$3

`typescript
interface ForecasterConfig {
alpha?: number; // Conformal prediction miscoverage rate (default: 0.1)
calibrationSize?: number; // Max calibration samples (default: 2000)
horizon?: number; // Default forecast horizon (default: 24)
seasonalPeriod?: number; // Seasonal period in hours (default: 24)
enableAdaptive?: boolean; // Enable adaptive conformal prediction (default: true)
ensembleConfig?: EnsembleConfig; // Ensemble configuration
weatherIntegration?: WeatherConfig; // Weather API integration
}
`

$3

`typescript
interface EnsembleConfig {
models: ModelType[]; // Models to include in ensemble
horizonWeights?: Map>; // Custom horizon weights
adaptiveLearningRate?: number; // Learning rate for weight updates (default: 0.05)
retrainFrequency?: number; // Retraining frequency (default: 100)
minCalibrationSamples?: number; // Min samples for calibration (default: 50)
}
`

Conformal Prediction

This package uses @neural-trader/predictor for statistically rigorous uncertainty quantification:

- Split Conformal Prediction: Distribution-free prediction intervals
- Adaptive Conformal Inference: Dynamic alpha adjustment for target coverage
- Multiple Implementations: Pure TypeScript with automatic WASM/Native acceleration

$3

With conformal prediction, the forecaster provides mathematically guaranteed coverage:

`
P(y_true ∈ [lower, upper]) ≥ 1 - α
`

For α = 0.1, at least 90% of true values will fall within the prediction intervals.

Performance

$3

Recommended models for each domain based on empirical performance:

- Solar: Prophet, ARIMA (strong daily seasonality)
- Wind: LSTM, Transformer (high variability)
- Demand: Prophet, LSTM (multi-seasonal patterns)
- Temperature: Prophet, Transformer (seasonal trends)

$3

- Training: O(n·m·k) where n=samples, m=models, k=hyperparameter candidates
- Prediction: O(h·m) where h=horizon, m=models in ensemble
- Calibration: O(n log n) for conformal predictor
- Update: O(log n) for online learning

$3

The swarm exploration runs hyperparameter search in parallel:

`typescript
// All model types explored concurrently
const explorationPromises = models.map(modelType =>
ensemble.exploreHyperparameters(modelType, data, validation)
);
await Promise.all(explorationPromises);
`

Testing

Comprehensive test suite with >90% coverage:

`bash
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
`

API Reference

$3

- EnergyForecaster: Main forecasting system
- EnsembleSwarm: Swarm-based ensemble learning
- EnergyConformalPredictor: Conformal prediction wrapper
- ARIMAModel, LSTMModel, TransformerModel, ProphetModel: Model implementations

$3

- TimeSeriesPoint: Time series data point
- ForecastResult: Single forecast with prediction interval
- MultiStepForecast: Multi-step forecast results
- ModelPerformance: Model performance metrics
- EnergyDomain: Energy domain enum
- ModelType: Model type enum

Advanced Usage

$3

`typescript
const horizonWeights = new Map([
[1, new Map([[ModelType.LSTM, 0.6], [ModelType.ARIMA, 0.4]])],
[24, new Map([[ModelType.PROPHET, 0.5], [ModelType.LSTM, 0.5]])],
]);

const forecaster = new EnergyForecaster(domain, {
ensembleConfig: {
models: [ModelType.LSTM, ModelType.ARIMA, ModelType.PROPHET],
horizonWeights
}
});
`

$3

`typescript
// Initial training
await forecaster.train(historicalData);

// Generate forecast
const forecast = await forecaster.forecast(24);

// Update with new observations as they arrive
for (const observation of newData) {
await forecaster.update(observation);
}
`

$3

`typescript
const stats = forecaster.getStats();

console.log('Domain:', stats.domain);
console.log('Training points:', stats.trainingPoints);
console.log('Models:', stats.ensembleStats.modelCount);
console.log('Seasonal strength:', stats.seasonalPattern?.strength);

// Per-model performance
stats.ensembleStats.performances.forEach(({ model, performance }) => {
console.log(${model}: MAPE=${performance.mape}%, RMSE=${performance.rmse});
});
`

Integration with Neural Trader

This package integrates seamlessly with the Neural Trader ecosystem:

- @neural-trader/predictor: Conformal prediction core
- agentdb: Memory-persistent model performance tracking (optional)
- claude-flow: Swarm orchestration (optional)
- openrouter: Weather pattern interpretation (optional)

Contributing

Contributions welcome! Please ensure:

- Tests pass: npm test
- Linting passes: npm run lint
- Types check: npm run typecheck
- Coverage >90%: npm run test:coverage`

License

MIT

See Also

- @neural-trader/predictor - Conformal prediction core
- Neural Trader - Main repository
- Examples - More example packages