@sipemu/anofox-forecast 0.4.4 → 0.4.6

package/README.md

@@ -1,6 +1,6 @@
 # @sipemu/anofox-forecast
 
-WebAssembly bindings for [anofox-forecast](https://crates.io/crates/anofox-forecast), a comprehensive time series forecasting library.
+WebAssembly bindings for [anofox-forecast](https://crates.io/crates/anofox-forecast), a comprehensive time series forecasting library with 40+ models, automatic model selection, probabilistic postprocessing, and more.
 
 ## Installation
 
@@ -109,9 +109,27 @@ const ts = TimeSeries.withTimestamps(
 | `MSTLForecasterWrapper` | MSTL decomposition | `seasonal_periods[]` |
 | `GARCHForecaster` | GARCH volatility model | `p`, `q` |
 
+### Auto Selection
+
+| Forecaster | Description | Parameters |
+|------------|-------------|------------|
+| `AutoForecaster` | Best of ARIMA, ETS, Theta | - |
+| `AutoEnsembleForecaster` | Ensemble of top-K models | - |
+
+### Orchestration
+
+| Type | Description |
+|------|-------------|
+| `JsDataProfile` | Automated data profiling (stationarity, trend, quality) |
+| `JsPipelineBuilder` | Declarative pipeline construction |
+| `JsPipelineResult` | Pipeline result with forecast and diagnostics |
+| `JsPipelineReport` | Structured multi-section report |
+| `selectModels()` | Model recommendation from data profile |
+| `explainResult()` | Human-readable result explanation |
+
 ## Prediction Intervals
 
-Some models support prediction intervals:
+Most models support prediction intervals:
 
 ```javascript
 import { NaiveForecaster } from '@sipemu/anofox-forecast';
@@ -191,6 +209,163 @@ ETSForecaster.isValidSpec("M", "A", "M");  // true
 ETSForecaster.isValidSpec("M", "A", "A");  // false (unstable)
 ```
 
+## Probabilistic Postprocessing
+
+Generate calibrated prediction intervals using conformal prediction, historical simulation, or normal approximation:
+
+```javascript
+import { JsConformalPredictor, JsPointForecasts, JsPostProcessor } from '@sipemu/anofox-forecast';
+
+// Conformal prediction intervals (distribution-free)
+const predictor = new JsConformalPredictor(0.9); // 90% coverage
+predictor.calibrate(forecasts, actuals);
+const intervals = predictor.predictIntervals(newForecasts);
+console.log('Lower:', intervals.lower);
+console.log('Upper:', intervals.upper);
+
+// Unified PostProcessor API
+const processor = JsPostProcessor.conformal(0.95);
+const trained = processor.train(forecasts, actuals);
+const pi = processor.predictIntervals(trained, newForecasts);
+```
+
+### Available Methods
+- `JsConformalPredictor` — distribution-free intervals (split, cross-val, jackknife+)
+- `JsNormalPredictor` — Gaussian error assumption baseline
+- `JsHistoricalSimulator` — non-parametric empirical error distribution
+- `JsPostProcessor` — unified API wrapping all methods
+- `JsBacktestConfig` / `JsBacktestResult` — rolling/expanding window backtesting
+
+## Orchestration / Agent Forecasting
+
+Build autonomous forecasting pipelines with data profiling, multi-metric model selection, preprocessing, ensemble construction, and structured reporting:
+
+### Data Profiling
+
+```javascript
+import { JsDataProfile } from '@sipemu/anofox-forecast';
+
+// Profile a time series
+const profile = JsDataProfile.fromSeries(ts);
+console.log('Observations:', profile.nObservations);
+console.log('Trend:', profile.trendDirection);      // "Rising", "Falling", "Flat"
+console.log('Stationary?', profile.isStationary);
+console.log('Intermittent?', profile.isIntermittent);
+console.log('Quality:', profile.qualityScore);       // 0.0 to 1.0
+
+// Full profile as JSON
+const json = profile.toJSON();
+
+// Profile raw values (no timestamps needed)
+const profile2 = JsDataProfile.fromValues(new Float64Array([1, 2, 3, 4, 5]));
+```
+
+### Model Selection
+
+```javascript
+import { JsDataProfile, selectModels } from '@sipemu/anofox-forecast';
+
+const profile = JsDataProfile.fromSeries(ts);
+
+// Get model recommendations based on data characteristics
+const result = selectModels(profile);
+console.log('Recommended:', result.recommended);  // ["ARIMA", "ETS", "Naive", "SES"]
+console.log('Reasoning:', result.reasoning);       // ["High autocorrelation...", ...]
+
+// Filter to available models
+const filtered = selectModels(profile, ["Naive", "SES", "ARIMA"]);
+```
+
+### Pipeline Builder
+
+```javascript
+import { JsPipelineBuilder } from '@sipemu/anofox-forecast';
+
+// Build and execute a forecasting pipeline
+const result = new JsPipelineBuilder()
+  .profile()                 // enable data profiling
+  .preprocess('auto')        // auto Box-Cox + outlier treatment
+  .metric('auto')            // data-aware metric selection
+  .ensemble('auto')          // ensemble if MCS includes > 1 model
+  .addModel('Naive')
+  .addModel('SES')
+  .addModel('SMA')
+  .withFallback()            // Naive → SMA fallback chain
+  .nonNegative()             // clamp forecasts >= 0
+  .execute(ts, 12);          // 12-step forecast
+
+console.log('Model:', result.modelName);
+console.log('Forecast:', result.forecast.values);
+console.log('Decision log:', result.decisionLog);
+
+// Access diagnostics
+const profile = result.profile;            // JsDataProfile or undefined
+const mcs = result.modelConfidenceSet;     // { included, pValue, singleWinner }
+const scores = result.metricScores;        // [{ model, score, components }]
+const weights = result.ensembleWeights;    // [{ model, weight }] or undefined
+const preprocess = result.preprocessInfo;  // { boxcoxLambda, outliersReplaced, stepsApplied }
+```
+
+#### Builder Options
+
+| Method | Options | Description |
+|--------|---------|-------------|
+| `profile()` | — | Enable data profiling |
+| `preprocess(mode)` | `"auto"`, `"none"` | Preprocessing (Box-Cox, outlier replacement) |
+| `metric(strategy)` | `"auto"`, `"mae"`, `"mse"`, `"rmse"`, `"smape"`, `"wape"`, `"mda"` | Metric for model ranking |
+| `ensemble(mode)` | `"auto"`, `"none"`, `"mean"`, `"median"`, `"weighted"` | Ensemble construction |
+| `addModel(name)` | `"Naive"`, `"SES"`, `"SMA"`, `"SMA3"`, `"SMA5"`, `"SMA10"`, `"SeasonalNaive"` | Register a model |
+| `addSeasonalModel(name, period)` | — | Register a seasonal model |
+| `selectModels(k)` | — | Select top-K models |
+| `crossValidate(folds, horizon)` | — | Enable cross-validation |
+| `withFallback()` | — | Enable fallback chain |
+| `nonNegative()` | — | Clamp forecasts to non-negative |
+| `seasonalPeriod(p)` | — | Set seasonal period hint |
+
+### Pipeline Report
+
+```javascript
+// Generate a structured report
+const report = result.report();
+console.log(report.title);             // "Pipeline Report: SES"
+console.log(report.sectionCount);      // number of sections
+console.log(report.toString());        // full formatted text
+
+// Report as JSON with typed sections
+const json = report.toJSON();
+// { title, sections: [{ heading, content: { type, ... } }] }
+// Content types: "text", "keyValue" (with pairs), "table" (with headers + rows)
+```
+
+### Explain Result
+
+```javascript
+import { explainResult } from '@sipemu/anofox-forecast';
+
+// Generate a human-readable explanation
+const brief = explainResult(result, 'brief');
+console.log(brief.summary);  // "Selected SES for 12-step forecast."
+
+const detailed = explainResult(result, 'detailed');
+console.log(detailed.summary);
+detailed.sections.forEach(s => console.log(s.heading, s.content));
+```
+
+## Calendar Annotations
+
+Add holidays and named regressors for models that support exogenous variables:
+
+```javascript
+import { CalendarAnnotations } from '@sipemu/anofox-forecast';
+
+const calendar = new CalendarAnnotations();
+calendar.addHoliday(Date.parse('2024-12-25'));
+calendar.addRegressor('temperature', new Float64Array([20, 22, 25, 23]));
+
+ts.setCalendar(calendar);
+model.fit(ts); // ARIMA, MFLES, etc. will automatically use the regressors
+```
+
 ## Browser Usage
 
 ```html
@@ -232,8 +407,8 @@ const forecast = model.predict(10);
 ## Limitations
 
 - The `parallel` feature from the Rust crate is not available in WASM
-- Postprocessing features (conformal prediction, IDR) are not yet exposed
-- Cross-validation utilities are not yet exposed
+- IDR (Isotonic Distributional Regression) and QRA are not yet exposed in WASM
+- Abstract storage (`PipelineStore`) is not exposed — use the report JSON output for persistence
 
 ## License