14 Commits

Author SHA1 Message Date
Vinayak Agarwal
f6f3023d3d Update allowed-tools formatting in SKILL.md files across multiple scientific skills to improve consistency and readability. 2026-02-23 12:36:05 -08:00
Timothy Kassis
f8da4bf9a7 Forecasting examples 2026-02-23 10:50:24 -08:00
Clayton Young
df58339850 feat(timesfm): complete all three examples with quality docs
- anomaly-detection: full two-phase rewrite (context Z-score + forecast PI),
  2-panel viz, Sep 2023 correctly flagged CRITICAL (z=+3.03)
- covariates-forecasting: v3 rewrite with variable-shadowing bug fixed,
  2x2 shared-axis viz showing actionable covariate decomposition,
  108-row CSV with distinct per-store price arrays
- global-temperature: output/ subfolder reorganization (all 6 output files
  moved, 5 scripts + shell script paths updated)
- SKILL.md: added Examples table, Quality Checklist, Common Mistakes (8 items),
  Validation & Verification with regression assertions
- .gitattributes already at repo root covering all binary types
2026-02-23 07:43:04 -05:00
Clayton Young
509190118f fix(examples): correct quantile indices, variable shadowing, and test design in anomaly + covariates examples
Anomaly detection fixes:
- Fix critical quantile index bug: index 0 is mean not q10; correct indices are q10=1, q20=2, q80=8, q90=9
- Redesign test: use all 36 months as context, inject 3 synthetic anomalies into future
- Result: 3 CRITICAL detected (was 11/12 — caused by test-set leakage + wrong indices)
- Update severity labels: CRITICAL = outside 80% PI, WARNING = outside 60% PI

Covariates fixes:
- Fix variable-shadowing bug: inner dict comprehension overwrote outer loop store_id
  causing all stores to get identical covariate arrays (store_A's price for everyone)
- Give each store a distinct price baseline (premium $12, standard $10, discount $7.50)
- Trim CONTEXT_LEN from 48 → 24 weeks; CSV now 108 rows (was 180)
- Add NOTE ON REAL DATA comment: temp file pattern for large external datasets

Both scripts regenerated with clean outputs.
2026-02-23 07:43:04 -05:00
Clayton Young
0d98fa353c feat(examples): add anomaly detection and covariates examples
Anomaly Detection Example:
- Uses quantile forecasts as prediction intervals
- Flags values outside 80%/90% CI as warnings/critical anomalies
- Includes visualization with deviation plot

Covariates (XReg) Example:
- Demonstrates forecast_with_covariates() API
- Shows dynamic numerical/categorical covariates
- Shows static categorical covariates
- Includes synthetic retail sales data with price, promotion, holiday

SKILL.md Updates:
- Added anomaly detection section with code example
- Expanded covariates section with covariate types table
- Added XReg modes explanation
- Updated 'When not to use' section to note anomaly detection workaround
2026-02-23 07:43:04 -05:00
Clayton Young
1a65439ebf fix(html): embed animation data for CORS-safe local file access
- Created generate_html.py to embed JSON data directly in HTML
- No external fetch() needed - works when opened directly in browser
- File size: 149.5 KB (self-contained)
- Shows forecast horizon (12-36 months) in stats
2026-02-23 07:43:04 -05:00
Clayton Young
96372cee99 feat(animation): extend forecasts to final date with dynamic horizon
- Each forecast now extends to 2025-12 regardless of historical data length
- Step 1 (12 points): forecasts 36 months ahead to 2025-12
- Step 25 (36 points): forecasts 12 months ahead to 2025-12
- GIF shows full forecast horizon at every animation step
2026-02-23 07:43:04 -05:00
Clayton Young
7b7110eebb fix(animation): use fixed axes showing full observed data in background
- X-axis fixed to 2022-01 to 2025-12 (full data range)
- Y-axis fixed to 0.72°C to 1.52°C (full value range)
- Background shows all observed data (faded gray) + final forecast reference (faded red dashed)
- Foreground shows current step data (bright blue) + current forecast (bright red)
- GIF size reduced from 918KB to 659KB
2026-02-23 07:43:04 -05:00
Clayton Young
1506a60993 feat(example): add interactive forecast animation with slider
Create an all-out demonstration showing how TimesFM forecasts evolve
as more historical data is added:

- generate_animation_data.py: Runs 25 incremental forecasts (12→36 points)
- interactive_forecast.html: Single-file HTML with Chart.js slider
  - Play/Pause animation control
  - Shows historical data, forecast, 80%/90% CIs, and actual future data
  - Live stats: forecast mean, max, min, CI width
- generate_gif.py: Creates animated GIF for embedding in markdown
- forecast_animation.gif: 25-frame animation (896 KB)

Interactive features:
- Slider to manually step through forecast evolution
- Auto-play with 500ms per frame
- Shows how each additional data point changes the forecast
- Confidence intervals narrow as more data is added
2026-02-23 07:43:04 -05:00
Clayton Young
910bcfdc8b fix(example): update visualization title to clarify demo purpose
- Change title from 'Above 1951-1980 Baseline' to clearer example description
- New title: 'TimesFM Zero-Shot Forecast Example / 36-month Temperature Anomaly → 12-month Forecast'
- Makes it clear this is a demonstration with limited input data
2026-02-23 07:43:04 -05:00
Clayton Young
dcde063723 chore: remove markdown-mermaid-writing skill from this branch
This branch was originally created from feat/markdown-mermaid-writing-skill
for development purposes, but the timesfm-forecasting skill should be
independent of PR #50.

- Remove scientific-skills/markdown-mermaid-writing/ directory
- Remove reference to markdown-mermaid-writing from SKILL.md integration section
- This PR now stands alone and does not require PR #50 to be merged first
2026-02-23 07:43:04 -05:00
Clayton Young
88300014e2 docs(skill): add note that model weights are not stored in repo
Model weights (~800 MB) download on-demand from HuggingFace when skill
is first used. Preflight checker ensures sufficient resources before
any download begins.
2026-02-23 07:43:04 -05:00
Clayton Young
c7c5bc21ff feat(example): add working TimesFM forecast example with global temperature data
- Add NOAA GISTEMP global temperature anomaly dataset (36 months, 2022-2024)
- Run TimesFM 1.0 PyTorch forecast for 2025 (12-month horizon)
- Generate fan chart visualization with 80%/90% confidence intervals
- Create comprehensive markdown report with findings and API notes

API Discovery:
- TimesFM 2.5 PyTorch checkpoint has file format issue (model.safetensors
  vs expected torch_model.ckpt)
- Working API uses TimesFmHparams + TimesFmCheckpoint + TimesFm() constructor
- Documented API in GitHub README differs from actual pip package

Includes:
- temperature_anomaly.csv (input data)
- forecast_output.csv (point forecast + quantiles)
- forecast_output.json (machine-readable output)
- forecast_visualization.png (LFS-tracked)
- run_forecast.py (reusable script)
- visualize_forecast.py (chart generation)
- run_example.sh (one-click runner)
- README.md (full report with findings)
2026-02-23 07:43:04 -05:00
Clayton Young
98670bcf47 feat(skill): add timesfm-forecasting skill for time series forecasting
Add comprehensive TimesFM forecasting skill with mandatory system
preflight checks (RAM/GPU/disk), end-to-end CSV forecasting script,
full API reference, data preparation guide, and hardware requirements
documentation. Supports TimesFM 2.5 (200M), 2.0 (500M), and legacy
v1.0 with automatic batch size recommendations based on hardware.
2026-02-23 07:43:04 -05:00