{
  "method": "TIMEKAN_BLOCK",
  "slug": "timekan-block",
  "title": "TimeKAN block: template–harmonic blending",
  "summary": "The current standalone TimeKAN-inspired operator combines familiar numerical estimates. It smooths a trend, selects periods from a prefix FFT, averages phase templates, and fits a harmonic projection at the supplied primary period. A fixed rule blends the two seasonal estimates. The animation shows that rule directly; it does not portray the complete frequency-decomposition KAN architecture from the cited paper.",
  "steps": [
    {
      "title": "Smooth and inspect prefix frequencies",
      "text": "Estimate the trend from the selected prefix and use the detrended prefix FFT to obtain candidate periods."
    },
    {
      "title": "Fit two kinds of seasonal estimate",
      "text": "Average phase templates at selected periods and separately fit a harmonic projection at primary_period."
    },
    {
      "title": "Apply the implemented fixed blend",
      "text": "Combine the template average and harmonic projection using a weight determined by num_bands. No KAN is optimized in this operator."
    },
    {
      "title": "Inspect the checked output",
      "text": "Return the smoothed trend, blended seasonal estimate and input-minus-components residual."
    }
  ],
  "parameters": [
    {
      "name": "num_bands",
      "effect": "Controls the selected template periods and the fixed blend weight 0.35 + 0.1 × min(num_bands, 4), clipped by the implementation."
    },
    {
      "name": "kan_width",
      "effect": "Maps to max(1, kan_width // 32) harmonics in this operator."
    },
    {
      "name": "primary_period",
      "effect": "Sets the harmonic projection's period; FFT-selected periods define the separate templates."
    },
    {
      "name": "fit_scope / train_fraction",
      "effect": "The animation explicitly fits on the first two thirds of the record."
    }
  ],
  "cautions": [
    "No KAN coefficients or neural network are fitted by this standalone implementation.",
    "Template and harmonic components can overlap spectrally; the displayed blend is an explicit heuristic.",
    "Prefix fitting and suffix extension do not establish forecast accuracy or causal identification.",
    "The residual is defined from the observed series after forming both named components."
  ],
  "references": [
    {
      "title": "Implemented DeTime operator",
      "url": "https://github.com/systems-mechanobiology/DeTime/blob/main/src/detime/methods/neural_blocks/neural_block_portfolio.py"
    },
    {
      "title": "Huang et al. (2025), TimeKAN: KAN-based Frequency Decomposition Learning Architecture for Long-term Time Series Forecasting",
      "url": "https://arxiv.org/abs/2502.06910"
    }
  ],
  "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": "TIMEKAN_BLOCK",
    "params": {
      "primary_period": 24,
      "trend_window": 25,
      "num_bands": 2,
      "kan_width": 64,
      "fit_scope": "prefix",
      "train_fraction": 0.6666666666666666
    },
    "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.",
    "selected_periods": [
      24,
      12
    ],
    "template_blend_weight": 0.55
  },
  "source_files": [
    "src/detime/methods/neural_blocks/neural_block_portfolio.py"
  ],
  "frames": 32,
  "duration_ms": 12050,
  "poster_frame": 15,
  "width": 1280,
  "height": 820,
  "artifacts": {
    "gif": {
      "file": "timekan-block.gif",
      "bytes": 257497,
      "sha256": "01cfe15be7bbe059b4fbf5810756f0410d540652e772bfbf47d910d348a85960"
    },
    "poster": {
      "file": "timekan-block.png",
      "bytes": 171621,
      "sha256": "2e0a856c6e19a1b9b1299870c6ab804933b47feee7729690db707d93173c588b"
    },
    "data": {
      "file": "timekan-block.npz",
      "bytes": 7762,
      "sha256": "df3ef98ddd8e49cb6164cd0682f8bbef61269ffb06b2ac5a525023190138f29f"
    }
  },
  "source_arrays": {
    "observed": [
      144
    ],
    "trend": [
      144
    ],
    "detrended": [
      144
    ],
    "templates": [
      2,
      144
    ],
    "selected_periods": [
      2
    ],
    "template_mean": [
      144
    ],
    "harmonic_fit": [
      144
    ],
    "blend_weights": [
      2
    ],
    "season": [
      144
    ],
    "residual": [
      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/neural_block_portfolio.py": "2aab635b9927d1d42bbcd8e0b4f37cb9fcdcf85cbd0331b5011621b495c4acfa",
      "src/detime/registry.py": "e934ffca17880cefe5add728aa497e63ea811d7ae43abec1ea498de718094066"
    }
  }
}