Skip to content

Commit 070ddb8

Browse files
eddmpythoneddmpython
committed
2026-03-04 docs: sync all documentation with API_SPEC.md as single source of truth
1 parent 94e38b8 commit 070ddb8

11 files changed

Lines changed: 360 additions & 143 deletions

File tree

‎docs/api/adaptive.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,13 @@ Forecast using the current regime context.
4343

4444
Profile time series characteristics for meta-learning.
4545

46+
```python
47+
from vectrix import ForecastDNA
48+
49+
dna = ForecastDNA()
50+
profile = dna.analyze(values, period=7)
51+
```
52+
4653
### Methods
4754

4855
- `analyze(y, period=1)` → `DNAProfile`
@@ -51,12 +58,23 @@ Profile time series characteristics for meta-learning.
5158

5259
| Attribute | Type | Description |
5360
|---|---|---|
54-
| `.category` | `str` | Series type |
55-
| `.difficulty` | `str` | 'easy', 'medium', 'hard' |
61+
| `.features` | `dict[str, float]` | 65+ statistical features |
62+
| `.fingerprint` | `str` | 8-char hex hash |
63+
| `.difficulty` | `str` | 'easy', 'medium', 'hard', 'very_hard' |
5664
| `.difficultyScore` | `float` | 0–100 score |
57-
| `.fingerprint` | `str` | Unique fingerprint code |
58-
| `.recommendedModels` | `list` | Recommended model IDs |
59-
| `.features` | `dict` | Extracted features |
65+
| `.recommendedModels` | `list[str]` | Sorted by fitness |
66+
| `.category` | `str` | 'trending', 'seasonal', 'stationary', etc. |
67+
| `.summary` | `str` | Natural language summary |
68+
69+
!!! warning "Feature values are inside the `features` dict"
70+
```python
71+
# CORRECT
72+
profile.features['trendStrength']
73+
profile.features['seasonalStrength']
74+
75+
# WRONG — AttributeError
76+
profile.trendStrength
77+
```
6078

6179
## SelfHealingForecast
6280

‎docs/api/easy.md‎

Lines changed: 152 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -8,117 +8,180 @@ The simplest way to use Vectrix. One function call for each task.
88

99
## Functions
1010

11-
### `forecast(data, date=None, value=None, steps=30, frequency='auto', verbose=False)`
11+
### `forecast()`
12+
13+
```python
14+
forecast(
15+
data, # str | DataFrame | ndarray | list | Series | dict
16+
date=None, # str — date column name
17+
value=None, # str — value column name
18+
steps=30, # int — forecast horizon
19+
verbose=False, # bool
20+
models=None, # list[str] | None — model IDs to evaluate
21+
ensemble=None, # str | None — 'mean', 'weighted', 'median', 'best'
22+
confidence=0.95 # float — 0.80, 0.90, 0.95, 0.99
23+
) -> EasyForecastResult
24+
```
25+
26+
**Available model IDs:** `'dot'`, `'auto_ets'`, `'auto_arima'`, `'auto_ces'`, `'four_theta'`, `'auto_mstl'`, `'tbats'`, `'theta'`, `'dtsf'`, `'esn'`, `'garch'`, `'croston'`, `'ets_aan'`, `'ets_aaa'`, `'naive'`, `'mean'`, `'rwd'`, `'window_avg'`, `'egarch'`, `'gjr_garch'`, `'seasonal_naive'`, `'mstl'`
27+
28+
### `analyze()`
29+
30+
```python
31+
analyze(
32+
data, # str | DataFrame | ndarray | list | Series | dict
33+
date=None, # str
34+
value=None, # str
35+
period=None, # int | None — seasonal period (auto if None)
36+
features=True, # bool
37+
changepoints=True, # bool
38+
anomalies=True, # bool
39+
anomalyThreshold=3.0 # float — z-score threshold
40+
) -> EasyAnalysisResult
41+
```
42+
43+
### `regress()`
44+
45+
```python
46+
regress(
47+
y=None, # ndarray | Series | None (direct mode)
48+
X=None, # ndarray | DataFrame | None (direct mode)
49+
data=None, # DataFrame | None (formula mode)
50+
formula=None, # str | None — "y ~ x1 + x2"
51+
method='ols', # str — 'ols', 'ridge', 'lasso', 'huber', 'quantile'
52+
summary=True, # bool — auto-print summary
53+
alpha=None, # float | None — regularization strength
54+
diagnostics=False # bool — auto-run diagnostics
55+
) -> EasyRegressionResult
56+
```
57+
58+
### `compare()`
59+
60+
```python
61+
compare(
62+
data, # str | DataFrame | ndarray | list | Series | dict
63+
date=None, # str
64+
value=None, # str
65+
steps=30, # int
66+
verbose=False, # bool
67+
models=None # list[str] | None
68+
) -> pd.DataFrame # Returns DataFrame directly, NOT a Result object
69+
```
70+
71+
**Returned DataFrame columns:** `model`, `mape`, `rmse`, `mae`, `smape`, `time_ms`, `selected`
72+
73+
### `quickReport()`
74+
75+
```python
76+
quickReport(
77+
data, date=None, value=None, steps=30
78+
) -> dict # Returns dict, NOT a Result object
79+
```
80+
81+
**Returned dict keys:** `'forecast'` (EasyForecastResult), `'analysis'` (EasyAnalysisResult), `'summary'` (str)
82+
83+
**Alias:** `quick_report` = `quickReport` (backward compatibility)
84+
85+
### `loadSample()`
86+
87+
```python
88+
loadSample(name: str) -> pd.DataFrame
89+
```
1290

13-
One-call forecasting with automatic model selection.
14-
15-
**Parameters:**
16-
- `data` — Input data (list, ndarray, Series, DataFrame, dict, or CSV path)
17-
- `date` — Date column name (optional, auto-detected)
18-
- `value` — Value column name (optional, auto-detected)
19-
- `steps` — Number of forecast steps (default: 30)
20-
- `frequency` — Frequency hint (default: `'auto'`, auto-detected)
21-
- `verbose` — Print progress (default: False)
22-
23-
**Returns:** `EasyForecastResult`
24-
25-
### `analyze(data, date=None, value=None, period=None)`
26-
27-
Time series DNA profiling, changepoint detection, anomaly identification.
28-
29-
**Parameters:**
30-
- `data` — Input data (same formats as forecast)
31-
- `date` — Date column name (optional)
32-
- `value` — Value column name (optional)
33-
- `period` — Seasonal period (optional, auto-detected)
34-
35-
**Returns:** `EasyAnalysisResult`
36-
37-
### `regress(y=None, X=None, data=None, formula=None, method="ols", **kwargs)`
38-
39-
R-style formula regression with full diagnostics.
40-
41-
**Parameters:**
42-
- `y` — Dependent variable (ndarray)
43-
- `X` — Independent variables (ndarray)
44-
- `data` — DataFrame (use with formula)
45-
- `formula` — R-style formula string (e.g. `"y ~ x1 + x2"`)
46-
- `method` — `"ols"`, `"ridge"`, `"lasso"`, `"huber"`, `"quantile"`
47-
- `summary` — Print summary automatically (default: True)
48-
49-
**Returns:** `EasyRegressionResult`
50-
51-
### `compare(data, date=None, value=None, steps=30, verbose=False)`
52-
53-
Compare all models on the given data and return a ranked DataFrame.
54-
55-
**Returns:** `DataFrame` — Models ranked by accuracy (sMAPE, MAPE, RMSE, MAE)
56-
57-
### `quick_report(data, date=None, value=None, steps=30)`
91+
Load a built-in sample dataset.
5892

59-
Combined analysis + forecast report generation.
93+
**Available samples:** `'airline'`, `'retail'`, `'stock'`, `'temperature'`, `'energy'`, `'web'`, `'intermittent'`
6094

61-
**Returns:** `Dict[str, Any]` — Report dictionary with `'summary'`, `'forecast'`, `'analysis'` keys
95+
| Sample | date col | value col |
96+
|--------|----------|-----------|
97+
| airline | date | passengers |
98+
| retail | date | sales |
99+
| stock | date | close |
100+
| temperature | date | temperature |
101+
| energy | date | consumption_kwh |
102+
| web | date | pageviews |
103+
| intermittent | date | demand |
62104

63105
### `listSamples()`
64106

65-
List available built-in sample datasets.
66-
67-
**Returns:** `DataFrame` — Dataset names and descriptions
68-
69-
### `loadSample(name)`
70-
71-
Load a built-in sample dataset.
72-
73-
**Parameters:**
74-
- `name` — Dataset name (e.g. `"airline"`, `"retail"`, `"stock"`)
107+
```python
108+
listSamples() -> pd.DataFrame
109+
```
75110

76-
**Returns:** `DataFrame`
111+
List available built-in sample datasets.
77112

78113
## Result Classes
79114

80115
### EasyForecastResult
81116

117+
**Attributes:**
118+
82119
| Attribute | Type | Description |
83120
|---|---|---|
84121
| `.predictions` | `np.ndarray` | Forecast values |
85-
| `.dates` | `list` | Forecast date strings |
86-
| `.lower` | `np.ndarray` | 95% lower bound |
87-
| `.upper` | `np.ndarray` | 95% upper bound |
88-
| `.model` | `str` | Selected model name |
89-
| `.mape` | `float` | Validation MAPE (%) |
90-
| `.rmse` | `float` | Validation RMSE |
91-
| `.mae` | `float` | Validation MAE |
92-
| `.smape` | `float` | Validation sMAPE |
93-
| `.models` | `list` | All evaluated model names |
94-
| `.compare()` | `DataFrame` | All models ranked by MAPE |
95-
| `.all_forecasts()` | `DataFrame` | Every model's predictions |
96-
| `.summary()` | `str` | Formatted text summary |
97-
| `.to_dataframe()` | `DataFrame` | date, prediction, lower95, upper95 |
98-
| `.to_csv(path)` | `self` | Save to CSV |
99-
| `.to_json(path)` | `str` | Save to JSON |
100-
| `.describe()` | `DataFrame` | Pandas-style statistics |
122+
| `.dates` | `list[str]` | Forecast dates |
123+
| `.lower` | `np.ndarray` | Lower CI |
124+
| `.upper` | `np.ndarray` | Upper CI |
125+
| `.model` | `str` | Best model name |
126+
| `.mape` | `float` | MAPE % |
127+
| `.rmse` | `float` | RMSE |
128+
| `.mae` | `float` | MAE |
129+
| `.smape` | `float` | sMAPE |
130+
| `.models` | `list[str]` | All valid model names (sorted by MAPE) |
131+
132+
**Methods:**
133+
134+
| Method | Alias | Returns | Description |
135+
|--------|-------|---------|-------------|
136+
| `summary()` | — | `str` | Text summary |
137+
| `toDataframe()` | `to_dataframe()` | `DataFrame` | date, prediction, lower95, upper95 |
138+
| `compare()` | — | `DataFrame` | All models ranked by MAPE |
139+
| `allForecasts()` | `all_forecasts()` | `DataFrame` | date + one col per model |
140+
| `describe()` | — | `DataFrame` | `.describe()` style stats |
141+
| `toCsv(path)` | `to_csv(path)` | `self` | Save to CSV |
142+
| `toJson(path=None)` | `to_json(path=None)` | `str` | JSON string or save to file |
143+
| `save(path)` | — | `self` | Alias for `toJson(path)` |
144+
| `plot()` | — | `Figure` | matplotlib plot (optional dep) |
101145

102146
### EasyAnalysisResult
103147

104148
| Attribute | Type | Description |
105149
|---|---|---|
106150
| `.dna` | `DNAProfile` | DNA profile object |
107-
| `.changepoints` | `np.ndarray` | Changepoint indices |
108-
| `.anomalies` | `np.ndarray` | Anomaly indices |
109-
| `.features` | `dict` | Extracted features |
110-
| `.characteristics` | `DataCharacteristics` | Data properties |
151+
| `.changepoints` | `np.ndarray` | Changepoint **int indices** (NOT dicts) |
152+
| `.anomalies` | `np.ndarray` | Anomaly **int indices** (NOT dicts) |
153+
| `.features` | `dict` | Statistical features dict |
154+
| `.characteristics` | `DataCharacteristics` | Data characteristics |
111155
| `.summary()` | `str` | Formatted report |
112156

157+
!!! warning "anomalies/changepoints are int arrays"
158+
```python
159+
# CORRECT
160+
for idx in analysis.anomalies:
161+
print(f"Anomaly at index {idx}")
162+
163+
# WRONG — will crash
164+
for a in analysis.anomalies:
165+
print(a['index'], a['value']) # TypeError!
166+
```
167+
113168
### EasyRegressionResult
114169

115-
| Attribute | Type | Description |
116-
|---|---|---|
117-
| `.coefficients` | `np.ndarray` | Regression coefficients |
118-
| `.pvalues` | `np.ndarray` | P-values |
119-
| `.r_squared` | `float` | R² |
120-
| `.adj_r_squared` | `float` | Adjusted R² |
121-
| `.f_stat` | `float` | F-statistic |
122-
| `.summary()` | `str` | Regression table |
123-
| `.diagnose()` | `str` | Full diagnostics |
124-
| `.predict(X)` | `DataFrame` | Predictions with intervals |
170+
**Attributes (camelCase primary, snake_case aliases):**
171+
172+
| Primary | Alias | Type | Description |
173+
|---------|-------|------|-------------|
174+
| `coefficients` | — | `np.ndarray` | Including intercept |
175+
| `pvalues` | — | `np.ndarray` | P-values |
176+
| `rSquared` | `r_squared` | `float` | R² |
177+
| `adjRSquared` | `adj_r_squared` | `float` | Adjusted R² |
178+
| `fStat` | `f_stat` | `float` | F-statistic |
179+
| `durbinWatson` | `durbin_watson` | `float` | Durbin-Watson statistic |
180+
181+
**Methods:**
182+
183+
| Method | Returns | Description |
184+
|--------|---------|-------------|
185+
| `summary()` | `str` | Regression summary table |
186+
| `diagnose()` | `str` | Full diagnostics report |
187+
| `predict(X, interval, alpha)` | `DataFrame` | Predictions with intervals |

‎docs/api/types.md‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Core data types and result objects used throughout Vectrix.
88

99
## ForecastResult
1010

11-
Main result from `Vectrix.forecast()`.
11+
Main result from `Vectrix.forecast()`. Not the same as `EasyForecastResult` from the Easy API.
1212

1313
| Field | Type | Description |
1414
|---|---|---|
@@ -19,19 +19,26 @@ Main result from `Vectrix.forecast()`.
1919
| `upper95` | `np.ndarray` | 95% upper bound |
2020
| `bestModelId` | `str` | Selected model ID |
2121
| `bestModelName` | `str` | Model display name |
22-
| `allModelResults` | `dict` | All model results |
22+
| `allModelResults` | `dict[str, ModelResult]` | All model results |
2323
| `characteristics` | `DataCharacteristics` | Data properties |
2424

25+
!!! note "EasyForecastResult vs ForecastResult"
26+
The Easy API returns `EasyForecastResult` with `.lower` / `.upper`.
27+
The Vectrix class returns `ForecastResult` with `.lower95` / `.upper95`.
28+
2529
## ModelResult
2630

27-
Per-model result.
31+
Per-model result stored in `ForecastResult.allModelResults`.
2832

2933
| Field | Type | Description |
3034
|---|---|---|
3135
| `modelId` | `str` | Model identifier |
3236
| `modelName` | `str` | Display name |
3337
| `isValid` | `bool` | Whether model produced valid output |
3438
| `mape` | `float` | Validation MAPE |
39+
| `rmse` | `float` | Validation RMSE |
40+
| `mae` | `float` | Validation MAE |
41+
| `smape` | `float` | Validation sMAPE |
3542
| `predictions` | `np.ndarray` | Model predictions |
3643
| `lower95` | `np.ndarray` | Lower bound |
3744
| `upper95` | `np.ndarray` | Upper bound |
@@ -52,6 +59,34 @@ Per-model result.
5259
| `seasonalStrength` | `float` | 0–1 strength |
5360
| `predictabilityScore` | `float` | 0–100 score |
5461

62+
## DNAProfile
63+
64+
Returned by `analyze().dna` or `ForecastDNA().analyze()`.
65+
66+
| Field | Type | Description |
67+
|---|---|---|
68+
| `features` | `dict[str, float]` | 65+ statistical features |
69+
| `fingerprint` | `str` | 8-char hex hash |
70+
| `difficulty` | `str` | 'easy', 'medium', 'hard', 'very_hard' |
71+
| `difficultyScore` | `float` | 0–100 score |
72+
| `recommendedModels` | `list[str]` | Sorted by fitness |
73+
| `category` | `str` | 'trending', 'seasonal', 'stationary', etc. |
74+
| `summary` | `str` | Natural language summary |
75+
76+
!!! warning "Feature values are inside the `features` dict"
77+
```python
78+
# CORRECT
79+
dna.features['trendStrength']
80+
dna.features['seasonalStrength']
81+
dna.features['hurstExponent']
82+
83+
# WRONG — AttributeError
84+
dna.trendStrength
85+
dna.seasonalStrength
86+
```
87+
88+
**Key feature names:** `trendStrength`, `seasonalStrength`, `seasonalPeakPeriod`, `hurstExponent`, `volatility`, `cv`, `skewness`, `kurtosis`, `adfStatistic`, `spectralEntropy`, `approximateEntropy`, `garchEffect`, `volatilityClustering`, `demandDensity`, `nonlinearAutocorr`, `forecastability`, `trendSlope`, `trendDirection`, `trendLinearity`, `trendCurvature`
89+
5590
## ModelInfo
5691

5792
Available model catalog entry.

0 commit comments

Comments
 (0)