@sipemu/anofox-forecast 0.4.9 → 0.5.0

package/README.md

@@ -278,23 +278,67 @@ model.fit(ts);
 const forecast = model.predict(10);
 ```
 
-## What's New in the Rust Crate (v0.4.8)
+## Calendar Feature Engineering
 
-These features are available in the Rust crate but not yet exposed as WASM bindings:
+```javascript
+import { FeatureGenerator, generateFutureTimestamps } from '@sipemu/anofox-forecast';
+
+// Build a feature generator
+const gen = new FeatureGenerator();
+gen.fourier(7, 2);              // weekly Fourier terms
+gen.cyclical('month');           // sin/cos month encoding
+gen.cyclical('day_of_week');     // sin/cos day-of-week
+gen.binary('weekend');           // 0/1 weekend indicator
+gen.binary('month_end');         // 0/1 month-end
+gen.advanced('days_in_month');   // 28-31
+
+// Generate features from timestamps (ms since epoch)
+const features = gen.generate(timestamps);  // { month_sin: [...], weekend: [...], ... }
+const names = gen.featureNames();
+
+// Generate future timestamps (calendar-aware)
+const future = generateFutureTimestamps(lastTimestampMs, '1mo', 12);  // monthly
+const weekly = generateFutureTimestamps(lastTimestampMs, '1w', 4);    // weekly
+
+// Auto-infer from TimeSeries
+const futureTs = ts.futureTimestamps(12);
+```
+
+## Bootstrap Prediction Intervals
+
+```javascript
+import { JsBootstrapPredictor } from '@sipemu/anofox-forecast';
+
+const bp = new JsBootstrapPredictor(0.95);
+bp.nReplicates(1000);
+bp.seed(42);
+
+const result = bp.fit(fittedValues, actuals);
+const intervals = bp.predictIntervals(result, pointForecast);
+console.log(intervals.lower, intervals.upper);
 
-- **Per-horizon-step conformal prediction** — separate interval widths per forecast step
-- **Bootstrap prediction intervals** — model-agnostic residual resampling with cumulative error paths
-- **Calendar feature engineering** — cyclical sin/cos encoding, binary indicators (weekend, month-end, etc.)
-- **Future timestamp generation** — calendar-aware (`generate_future_timestamps`)
-- **Auto-lag selection** for RegressionForecaster (BIC/AIC)
-- **Differencing** for RegressionForecaster (regular + seasonal)
-- **Reworked cross-validation** — backward-anchored folds, n_folds-driven
+// Multi-quantile forecasts
+const quantiles = bp.predictQuantiles(result, pointForecast, [0.10, 0.25, 0.50, 0.75, 0.90]);
+```
+
+## Per-Step Conformal Prediction
+
+```javascript
+// Per-horizon-step intervals (tighter at h=1, wider at h=12)
+const perStep = predictor.fitPerStep(foldForecasts, foldActuals);
+console.log(perStep.halfWidths);  // different width per step
+
+const intervals = perStep.predictIntervals(pointForecast);
+
+// Multi-quantile conformal forecasts
+const quantiles = predictor.predictQuantiles(result, pointForecast, [0.10, 0.50, 0.90]);
+```
 
 ## Limitations
 
 - The `parallel` feature from the Rust crate is not available in WASM
 - IDR (Isotonic Distributional Regression) and QRA are not yet exposed in WASM
-- Per-step conformal, bootstrap predictor, and calendar features are Rust-only (not yet in WASM)
+- RegressionForecaster (11 regression backends) is Rust-only (not yet in WASM)
 
 ## License
 

package/anofox_forecast_js.d.ts

@@ -510,6 +510,73 @@ export class EnsembleForecaster {
   readonly name: string;
 }
 
+export class FeatureGenerator {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Add day-of-week one-hot indicators (Mon-Sat, Sunday dropped).
+   */
+  dayOfWeek(): void;
+  /**
+   * Return the sorted list of column names this generator will produce.
+   *
+   * @returns Array of feature name strings
+   */
+  featureNames(): any;
+  /**
+   * Add month-of-year one-hot indicators (Feb-Dec, January dropped).
+   */
+  monthOfYear(): void;
+  /**
+   * Create an empty feature generator.
+   */
+  constructor();
+  /**
+   * Add a binary (0/1) calendar indicator.
+   *
+   * @param indicator - One of: "weekend", "month_start", "month_end",
+   *   "quarter_start", "quarter_end", "year_start", "year_end"
+   */
+  binary(indicator: string): void;
+  /**
+   * Add Fourier terms for a given period and order.
+   *
+   * Produces `2 * order` columns (`fourier_{period}_sin{k}`,
+   * `fourier_{period}_cos{k}` for k in 1..=order).
+   *
+   * @param period - Period in observation units (e.g. 7 for weekly in daily data)
+   * @param order  - Number of harmonics
+   */
+  fourier(period: number, order: number): void;
+  /**
+   * Add quarter one-hot indicators (Q2-Q4, Q1 dropped).
+   */
+  quarter(): void;
+  /**
+   * Add an advanced numeric calendar feature.
+   *
+   * @param feature - One of: "leap_year", "days_in_month"
+   */
+  advanced(feature: string): void;
+  /**
+   * Add cyclical sin/cos encoding of a time component.
+   *
+   * Produces 2 columns: `{name}_sin` and `{name}_cos`.
+   *
+   * @param component - One of: "month", "quarter", "semester",
+   *   "week_of_year", "day_of_week", "day_of_month", "day_of_year",
+   *   "hour", "minute", "second"
+   */
+  cyclical(component: string): void;
+  /**
+   * Generate features for the given timestamps.
+   *
+   * @param timestamps - Array of timestamps as milliseconds since Unix epoch
+   * @returns Object mapping feature names to Float64Array values
+   */
+  generate(timestamps: Float64Array): any;
+}
+
 export class Forecast {
   private constructor();
   free(): void;
@@ -674,9 +741,96 @@ export class JsBacktestResult {
   readonly coverage: number;
 }
 
+export class JsBootstrapPredictor {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Use block bootstrap with the given block size.
+   *
+   * Preserves autocorrelation in residuals.
+   *
+   * @param size - Block size (0 falls back to IID)
+   */
+  blockSize(size: number): JsBootstrapPredictor;
+  /**
+   * Set the number of bootstrap replicates (default: 1000).
+   *
+   * @param n - Number of replicates (minimum 10)
+   */
+  nReplicates(n: number): JsBootstrapPredictor;
+  /**
+   * Generate prediction intervals for new point forecasts.
+   *
+   * Returns a JsPredictionIntervals with lower and upper bounds.
+   *
+   * @param result - A fitted JsBootstrapResult from fit()
+   * @param pointForecasts - New point forecast values
+   */
+  predictIntervals(result: JsBootstrapResult, point_forecasts: Float64Array): JsPredictionIntervals;
+  /**
+   * Generate quantile forecasts at multiple quantile levels.
+   *
+   * Returns a serialized object with `quantiles` (levels) and `values` (matrix).
+   *
+   * @param result - A fitted JsBootstrapResult from fit()
+   * @param pointForecasts - New point forecast values
+   * @param levels - Quantile levels in (0, 1), e.g. [0.1, 0.25, 0.5, 0.75, 0.9]
+   */
+  predictQuantiles(result: JsBootstrapResult, point_forecasts: Float64Array, levels: Float64Array): any;
+  /**
+   * Fit the predictor on historical forecasts and actuals.
+   *
+   * Computes residuals and stores them for resampling.
+   *
+   * @param forecasts - Historical point forecast values
+   * @param actuals - Corresponding actual observed values
+   */
+  fit(forecasts: Float64Array, actuals: Float64Array): JsBootstrapResult;
+  /**
+   * Create a bootstrap predictor with the given coverage level.
+   *
+   * @param coverage - Target coverage level in (0, 1), e.g. 0.90
+   */
+  constructor(coverage: number);
+  /**
+   * Set random seed for reproducibility.
+   *
+   * @param seed - Random seed value
+   */
+  seed(seed: bigint): JsBootstrapPredictor;
+}
+
+export class JsBootstrapResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get the residuals used for resampling.
+   */
+  residuals(): Float64Array;
+  /**
+   * Get the number of replicates.
+   */
+  readonly nReplicates: number;
+  /**
+   * Get the coverage level.
+   */
+  readonly coverage: number;
+}
+
 export class JsConformalPredictor {
   free(): void;
   [Symbol.dispose](): void;
+  /**
+   * Fit per-horizon-step conformal intervals.
+   *
+   * Each horizon step gets its own interval half-width, allowing tighter
+   * intervals for near-horizon steps and wider for far-horizon steps.
+   *
+   * @param foldForecasts - Per-fold forecast arrays (array of arrays), each of length `horizon`
+   * @param foldActuals - Per-fold actual arrays (array of arrays), each of length `horizon`
+   */
+  fitPerStep(fold_forecasts: any, fold_actuals: any): JsPerStepConformalResult;
   /**
    * Create a conformal predictor with the Jackknife+ method.
    *
@@ -690,6 +844,16 @@ export class JsConformalPredictor {
    * @param pointForecasts - New point forecast values
    */
   predictIntervals(result: JsConformalResult, point_forecasts: Float64Array): JsPredictionIntervals;
+  /**
+   * Generate quantile forecasts at multiple quantile levels.
+   *
+   * Returns a serialized object with `quantiles` (levels) and `values` (matrix).
+   *
+   * @param result - A fitted JsConformalResult from calibrate()
+   * @param pointForecasts - New point forecast values
+   * @param levels - Quantile levels in (0, 1), e.g. [0.1, 0.5, 0.9]
+   */
+  predictQuantiles(result: JsConformalResult, point_forecasts: Float64Array, levels: Float64Array): any;
   /**
    * Create a split conformal predictor.
    *
@@ -874,6 +1038,40 @@ export class JsNormalResult {
   readonly mean: number;
 }
 
+export class JsPerStepConformalResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Apply per-step intervals to a point forecast.
+   *
+   * Returns a JsPredictionIntervals with per-step lower and upper bounds.
+   *
+   * @param pointForecasts - Point forecast values (length must match horizon)
+   */
+  predictIntervals(point_forecasts: Float64Array): JsPredictionIntervals;
+  /**
+   * Apply per-step intervals and return lower/upper as a plain object.
+   *
+   * Returns a serialized object with `lower` and `upper` arrays.
+   *
+   * @param pointForecasts - Point forecast values (length must match horizon)
+   */
+  predict(point_forecasts: Float64Array): any;
+  /**
+   * Get the per-step interval half-widths.
+   */
+  readonly halfWidths: Float64Array;
+  /**
+   * Get the number of horizon steps.
+   */
+  readonly horizon: number;
+  /**
+   * Get the coverage level.
+   */
+  readonly coverage: number;
+}
+
 export class JsPointForecasts {
   free(): void;
   [Symbol.dispose](): void;
@@ -984,6 +1182,13 @@ export class KalmanForecaster {
    * @param state_noise - State (level) noise variance
    */
   static localLevel(obs_noise: number, state_noise: number): KalmanForecaster;
+  /**
+   * Compute the log-likelihood of the observations under the model.
+   *
+   * @param series - TimeSeries to evaluate
+   * @returns Log-likelihood value
+   */
+  logLikelihood(series: TimeSeries): number;
   /**
    * Create a local linear trend model.
    *
@@ -1006,9 +1211,23 @@ export class KalmanForecaster {
    * @param series - TimeSeries to fit
    */
   fit(series: TimeSeries): void;
+  /**
+   * Create a custom state-space model from matrices.
+   *
+   * @param transition - State transition matrix F (n_state x n_state), flat row-major
+   * @param observation - Observation matrix H (n_obs x n_state), flat row-major
+   * @param processNoise - Process noise covariance Q (n_state x n_state), flat row-major
+   * @param observationNoise - Observation noise covariance R (n_obs x n_obs), flat row-major
+   * @param nState - Number of state dimensions
+   * @param nObs - Number of observation dimensions
+   */
+  static custom(transition: Float64Array, observation: Float64Array, process_noise: Float64Array, observation_noise: Float64Array, n_state: number, n_obs: number): KalmanForecaster;
   /**
    * Apply the Kalman smoother (RTS smoother) and return smoothed observations.
    *
+   * Uses the same state-space model that was configured (local level, local linear
+   * trend, or custom). Fits the filter first, then runs the RTS smoother.
+   *
    * @param series - TimeSeries to smooth
    * @returns Array of smoothed observation values
    */
@@ -1024,6 +1243,14 @@ export class KalmanForecaster {
    * Get the model name.
    */
   readonly name: string;
+  /**
+   * Get the number of observation dimensions.
+   */
+  readonly nObs: number;
+  /**
+   * Get the number of state dimensions.
+   */
+  readonly nState: number;
 }
 
 export class MFLESForecaster {
@@ -1272,6 +1499,16 @@ export class TimeSeries {
    * @returns A new TimeSeries instance
    */
   static withTimestamps(values: Float64Array, timestamps_ms: Float64Array): TimeSeries;
+  /**
+   * Generate future timestamps by inferring the series frequency.
+   *
+   * Detects whether the data is daily, weekly, monthly, quarterly, or
+   * yearly from the existing timestamps and extrapolates forward.
+   *
+   * @param horizon - Number of future timestamps to generate
+   * @returns Array of timestamps as milliseconds since Unix epoch
+   */
+  futureTimestamps(horizon: number): Float64Array;
   /**
    * Check if the series has missing values (NaN).
    */
@@ -1486,6 +1723,17 @@ export function diagnoseResiduals(residuals: Float64Array, fitted_params?: numbe
  */
 export function durbinWatson(residuals: Float64Array): any;
 
+/**
+ * Generate future timestamps starting after a given last timestamp.
+ *
+ * @param lastTimestampMs - Last known timestamp as milliseconds since epoch
+ * @param frequency - Polars-style frequency string: "1d", "1w", "1mo",
+ *   "1q", "1y", "1h", "30m", "30s", etc.
+ * @param horizon - Number of future timestamps to generate
+ * @returns Float64Array of timestamps as milliseconds since epoch
+ */
+export function generateFutureTimestamps(last_timestamp_ms: number, frequency: string, horizon: number): Float64Array;
+
 /**
  * Initialize the WASM module.
  *
@@ -1644,6 +1892,7 @@ export interface InitOutput {
   readonly __wbg_dynamicthetaforecaster_free: (a: number, b: number) => void;
   readonly __wbg_ensembleforecaster_free: (a: number, b: number) => void;
   readonly __wbg_etsforecaster_free: (a: number, b: number) => void;
+  readonly __wbg_featuregenerator_free: (a: number, b: number) => void;
   readonly __wbg_forecast_free: (a: number, b: number) => void;
   readonly __wbg_garchforecaster_free: (a: number, b: number) => void;
   readonly __wbg_holtforecaster_free: (a: number, b: number) => void;
@@ -1651,13 +1900,15 @@ export interface InitOutput {
   readonly __wbg_imapaforecaster_free: (a: number, b: number) => void;
   readonly __wbg_jsbacktestconfig_free: (a: number, b: number) => void;
   readonly __wbg_jsbacktestresult_free: (a: number, b: number) => void;
+  readonly __wbg_jsbootstrappredictor_free: (a: number, b: number) => void;
+  readonly __wbg_jsbootstrapresult_free: (a: number, b: number) => void;
   readonly __wbg_jsconformalpredictor_free: (a: number, b: number) => void;
-  readonly __wbg_jsconformalresult_free: (a: number, b: number) => void;
   readonly __wbg_jshistoricalsimresult_free: (a: number, b: number) => void;
   readonly __wbg_jshistoricalsimulator_free: (a: number, b: number) => void;
   readonly __wbg_jsmodeldiagnostics_free: (a: number, b: number) => void;
   readonly __wbg_jsnormalpredictor_free: (a: number, b: number) => void;
   readonly __wbg_jsnormalresult_free: (a: number, b: number) => void;
+  readonly __wbg_jsperstepconformalresult_free: (a: number, b: number) => void;
   readonly __wbg_jspointforecasts_free: (a: number, b: number) => void;
   readonly __wbg_jspostprocessor_free: (a: number, b: number) => void;
   readonly __wbg_jspredictionintervals_free: (a: number, b: number) => void;
@@ -1788,6 +2039,16 @@ export interface InitOutput {
   readonly etsforecaster_name: (a: number) => [number, number];
   readonly etsforecaster_new: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
   readonly etsforecaster_predict: (a: number, b: number) => [number, number, number];
+  readonly featuregenerator_advanced: (a: number, b: number, c: number) => [number, number];
+  readonly featuregenerator_binary: (a: number, b: number, c: number) => [number, number];
+  readonly featuregenerator_cyclical: (a: number, b: number, c: number) => [number, number];
+  readonly featuregenerator_dayOfWeek: (a: number) => void;
+  readonly featuregenerator_featureNames: (a: number) => [number, number, number];
+  readonly featuregenerator_fourier: (a: number, b: number, c: number) => void;
+  readonly featuregenerator_generate: (a: number, b: number, c: number) => [number, number, number];
+  readonly featuregenerator_monthOfYear: (a: number) => void;
+  readonly featuregenerator_new: () => number;
+  readonly featuregenerator_quarter: (a: number) => void;
   readonly forecast_clamp: (a: number, b: number, c: number) => number;
   readonly forecast_hasLower: (a: number) => number;
   readonly forecast_hasUpper: (a: number) => number;
@@ -1802,6 +2063,7 @@ export interface InitOutput {
   readonly garchforecaster_new: (a: number, b: number) => number;
   readonly garchforecaster_predict: (a: number, b: number) => [number, number, number];
   readonly garchforecaster_predictWithIntervals: (a: number, b: number, c: number) => [number, number, number];
+  readonly generateFutureTimestamps: (a: number, b: number, c: number, d: number) => [number, number, number, number];
   readonly holtforecaster_fit: (a: number, b: number) => [number, number];
   readonly holtforecaster_name: (a: number) => [number, number];
   readonly holtforecaster_new: (a: number, b: number) => number;
@@ -1830,14 +2092,24 @@ export interface InitOutput {
   readonly jsbacktestresult_coverage: (a: number) => number;
   readonly jsbacktestresult_intervalWidths: (a: number) => number;
   readonly jsbacktestresult_numFolds: (a: number) => number;
+  readonly jsbootstrappredictor_blockSize: (a: number, b: number) => number;
+  readonly jsbootstrappredictor_fit: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+  readonly jsbootstrappredictor_nReplicates: (a: number, b: number) => number;
+  readonly jsbootstrappredictor_new: (a: number) => number;
+  readonly jsbootstrappredictor_predictIntervals: (a: number, b: number, c: number, d: number) => number;
+  readonly jsbootstrappredictor_predictQuantiles: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+  readonly jsbootstrappredictor_seed: (a: number, b: bigint) => number;
+  readonly jsbootstrapresult_coverage: (a: number) => number;
+  readonly jsbootstrapresult_nReplicates: (a: number) => number;
+  readonly jsbootstrapresult_residuals: (a: number) => [number, number];
   readonly jsconformalpredictor_calibrate: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
   readonly jsconformalpredictor_crossVal: (a: number, b: number) => number;
+  readonly jsconformalpredictor_fitPerStep: (a: number, b: any, c: any) => [number, number, number];
   readonly jsconformalpredictor_jackknifePlus: (a: number) => number;
   readonly jsconformalpredictor_new: (a: number) => number;
   readonly jsconformalpredictor_predictIntervals: (a: number, b: number, c: number, d: number) => number;
-  readonly jsconformalresult_coverage: (a: number) => number;
+  readonly jsconformalpredictor_predictQuantiles: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
   readonly jsconformalresult_quantileValue: (a: number) => number;
-  readonly jsconformalresult_scores: (a: number) => [number, number];
   readonly jshistoricalsimresult_errors: (a: number) => [number, number];
   readonly jshistoricalsimresult_quantileValues: (a: number) => [number, number];
   readonly jshistoricalsimulator_new: (a: number, b: number) => number;
@@ -1857,6 +2129,10 @@ export interface InitOutput {
   readonly jsnormalpredictor_fit: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
   readonly jsnormalpredictor_new: (a: number, b: number) => number;
   readonly jsnormalpredictor_predictIntervals: (a: number, b: number, c: number, d: number) => [number, number, number];
+  readonly jsperstepconformalresult_halfWidths: (a: number) => [number, number];
+  readonly jsperstepconformalresult_horizon: (a: number) => number;
+  readonly jsperstepconformalresult_predict: (a: number, b: number, c: number) => [number, number, number];
+  readonly jsperstepconformalresult_predictIntervals: (a: number, b: number, c: number) => number;
   readonly jspointforecasts_isEmpty: (a: number) => number;
   readonly jspointforecasts_length: (a: number) => number;
   readonly jspointforecasts_new: (a: number, b: number) => number;
@@ -1872,9 +2148,13 @@ export interface InitOutput {
   readonly jspredictionintervals_midpoints: (a: number) => [number, number];
   readonly jspredictionintervals_upper: (a: number) => [number, number];
   readonly jspredictionintervals_widths: (a: number) => [number, number];
+  readonly kalmanforecaster_custom: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number];
   readonly kalmanforecaster_fit: (a: number, b: number) => [number, number];
   readonly kalmanforecaster_localLevel: (a: number, b: number) => number;
   readonly kalmanforecaster_localLinearTrend: (a: number, b: number, c: number) => number;
+  readonly kalmanforecaster_logLikelihood: (a: number, b: number) => [number, number, number];
+  readonly kalmanforecaster_nObs: (a: number) => number;
+  readonly kalmanforecaster_nState: (a: number) => number;
   readonly kalmanforecaster_name: (a: number) => [number, number];
   readonly kalmanforecaster_predict: (a: number, b: number) => [number, number, number];
   readonly kalmanforecaster_predictWithIntervals: (a: number, b: number, c: number) => [number, number, number];
@@ -1959,6 +2239,7 @@ export interface InitOutput {
   readonly thetaforecaster_predict: (a: number, b: number) => [number, number, number];
   readonly thetaforecaster_predictWithIntervals: (a: number, b: number, c: number) => [number, number, number];
   readonly timeseries_clearCalendar: (a: number) => void;
+  readonly timeseries_futureTimestamps: (a: number, b: number) => [number, number, number, number];
   readonly timeseries_hasCalendar: (a: number) => number;
   readonly timeseries_hasMissingValues: (a: number) => number;
   readonly timeseries_isEmpty: (a: number) => number;
@@ -1989,11 +2270,15 @@ export interface InitOutput {
   readonly __wbg_smaforecaster_free: (a: number, b: number) => void;
   readonly __wbg_tsbforecaster_free: (a: number, b: number) => void;
   readonly __wbg_windowaverageforecaster_free: (a: number, b: number) => void;
+  readonly jsconformalresult_scores: (a: number) => [number, number];
+  readonly jsconformalresult_coverage: (a: number) => number;
   readonly jsmodeldiagnostics_heteroscedasticityPvalue: (a: number) => number;
   readonly jsmodeldiagnostics_jarqueBeraPvalue: (a: number) => number;
   readonly jsnormalresult_mean: (a: number) => number;
   readonly jsnormalresult_stdDev: (a: number) => number;
+  readonly jsperstepconformalresult_coverage: (a: number) => number;
   readonly jspredictionintervals_coverage: (a: number) => number;
+  readonly __wbg_jsconformalresult_free: (a: number, b: number) => void;
   readonly __wbindgen_malloc: (a: number, b: number) => number;
   readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
   readonly __wbindgen_exn_store: (a: number) => void;