{
  "method": "XPATCH_BLOCK",
  "slug": "xpatch-block",
  "title": "xPatch block: exponential level updates",
  "summary": "The implemented xPatch-inspired block offers EMA and a Holt-style level/slope option named dema. This animation uses EMA with alpha = 0.25, followed by the optional five-sample smoother of the nontrend stream. It shows the exact two-term update and the effect of a second alpha. The raw EMA is one-sided; the selected centered seasonal smoother changes that information boundary.",
  "steps": [
    {
      "title": "Mix observation and state",
      "text": "Initialize the level with the first sample, then update it as alpha times the observation plus one minus alpha times the previous level."
    },
    {
      "title": "Advance the recurrence",
      "text": "Continue the EMA update through the record. A second, explicitly labelled alpha illustrates a parameter change."
    },
    {
      "title": "Smooth the difference",
      "text": "This example smooths input minus trend with the requested five-sample centered mean; the remaining difference becomes residual."
    },
    {
      "title": "Inspect all three streams",
      "text": "The final display matches the public xPatch-inspired operator at the stated configuration."
    }
  ],
  "parameters": [
    {
      "name": "alpha",
      "effect": "Weights the newest observation in the EMA level update; the other weight is 1 - alpha."
    },
    {
      "name": "ma_type",
      "effect": "Selects ema or the implemented Holt-style level/slope recurrence called dema."
    },
    {
      "name": "season_smooth",
      "effect": "Optionally smooths the nontrend stream with an odd centered mean; omission leaves a zero derived residual."
    },
    {
      "name": "beta",
      "effect": "Controls the slope update when ma_type='dema'; it does not affect the EMA path shown."
    }
  ],
  "cautions": [
    "This operator does not run the complete xPatch forecasting architecture.",
    "The source's dema option is a level/slope recurrence; interpret it from the code rather than assuming every library uses the same DEMA definition.",
    "With season_smooth enabled, the seasonal stream uses centered smoothing even though EMA itself is one-sided.",
    "When alpha is omitted, trend_window can derive it. Explicit alpha takes precedence."
  ],
  "references": [
    {
      "title": "Implemented DeTime operator",
      "url": "https://github.com/systems-mechanobiology/DeTime/blob/main/src/detime/methods/neural_blocks/xpatch_block.py"
    },
    {
      "title": "Stitsyuk and Choi (2024), xPatch: Dual-Stream Time Series Forecasting with Exponential Seasonal-Trend Decomposition",
      "url": "https://arxiv.org/abs/2412.17323"
    }
  ],
  "trace_kind": "computed_operator_trace",
  "trace_note": "Intermediate arrays are computed with the implemented operator helpers. The final trend, season and residual are checked against public decompose(). The animation explains this standalone experimental block; its source architecture is cited for provenance.",
  "input_note": "Deterministic synthetic teaching signal; not a benchmark.",
  "example_config": {
    "method": "XPATCH_BLOCK",
    "params": {
      "ma_type": "ema",
      "alpha": 0.25,
      "season_smooth": 5
    },
    "backend": "python"
  },
  "checks": {
    "public_method_executed": true,
    "method_output_max_abs_errors": {
      "trend": 0.0,
      "season": 0.0,
      "residual": 0.0
    },
    "reconstruction_max_abs_error": 2.220446049250313e-16,
    "validation_scope": "One deterministic teaching input; no benchmark claim."
  },
  "source_files": [
    "src/detime/methods/neural_blocks/xpatch_block.py"
  ],
  "frames": 32,
  "duration_ms": 12050,
  "poster_frame": 15,
  "width": 1280,
  "height": 820,
  "artifacts": {
    "gif": {
      "file": "xpatch-block.gif",
      "bytes": 410144,
      "sha256": "f4173936d517a865481558a7c5ef8a0ce137e8d52f226f62d041f70784e9ad98"
    },
    "poster": {
      "file": "xpatch-block.png",
      "bytes": 165512,
      "sha256": "662d4d1ddc0504fa7f3a82f9e5084843d1ccb23b01c56abddb52a6b65e4d1dfd"
    },
    "data": {
      "file": "xpatch-block.npz",
      "bytes": 8113,
      "sha256": "45edaa61c89af20902adb6fe88cf5f2b001f0892bad9b8e78a9f357786c81393"
    }
  },
  "source_arrays": {
    "observed": [
      144
    ],
    "trend": [
      144
    ],
    "raw_difference": [
      144
    ],
    "season": [
      144
    ],
    "residual": [
      144
    ],
    "alpha_065_trend": [
      144
    ]
  },
  "render_provenance": {
    "python_version": "3.12.14",
    "dependencies": {
      "numpy": "2.3.5",
      "scipy": "1.17.0",
      "statsmodels": "0.15.0",
      "matplotlib": "3.10.8",
      "Pillow": "12.3.0",
      "PyWavelets": "1.10.0",
      "EMD-signal": "1.10.0",
      "vmdpy": "0.2",
      "PySDKit": "0.5.0"
    },
    "source_hashes": {
      "scripts/generate_method_animations.py": "f62989af55a7e48495c24afcfee31751d3785e5f78bb4b900bef23a429deaa84",
      "scripts/method_animations/common.py": "73ad7e8b4e5b67f87d13e59adab2c93e983fe1aaf06ee627d22cb7c7e696016a",
      "scripts/method_animations/neural.py": "fc1c2a73490391f0f863ede52e38f12924cc1fec572b7188356a2308216716e6",
      "src/detime/backends.py": "7432dcf59e382580dfb32f1f57e61ff71a30567c049b35243e24e3644523eda6",
      "src/detime/core.py": "d95b348cd8b16b56d18840965579c947a11628d969dd6c32c4af7723f5a027f4",
      "src/detime/methods/neural_blocks/xpatch_block.py": "4630da9874dd75fbc23dc688b29124ec6944d2dc9f56a200929a36ace4919ffc",
      "src/detime/registry.py": "e934ffca17880cefe5add728aa497e63ea811d7ae43abec1ea498de718094066"
    }
  }
}