From 3b5154f31074f31d62b706fba29127c6cdb8a702 Mon Sep 17 00:00:00 2001 From: Benjamin Walker Date: Sun, 15 Nov 2026 13:48:28 +0000 Subject: [PATCH] Add NumPy, pandas, and CSV forecasting support for 0.2.0 Preserve input tensor devices and return DataFrames for pandas and CSV inputs. Infer calendar metadata and future date indexes from dated histories. Bump the package to 0.2.0, add format and date regression tests and an example CSV, and update the usage documentation. --- MANIFEST.in | 1 + README.md | 243 ++++++++++++++---- examples/history.csv | 25 ++ pyproject.toml | 2 +- .../ci_proto/_forecast.py | 49 +++- .../ci_proto/_formats.py | 107 ++++++++ tests/test_dates.py | 170 ++++++++++++ tests/test_formats.py | 187 ++++++++++++++ uv.lock | 2 +- 9 files changed, 716 insertions(+), 70 deletions(-) create mode 100644 examples/history.csv create mode 100644 src/continuousintelligence/ci_proto/_formats.py create mode 100644 tests/test_dates.py create mode 100644 tests/test_formats.py diff --git a/MANIFEST.in b/MANIFEST.in index 5457f1c..8ff5dff 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,3 @@ include examples/forecast.py tests/conftest.py tests/distribution.py +include examples/history.csv include uv.lock .python-version diff --git a/README.md b/README.md index 7a96137..fef216f 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,9 @@ pip install continuousintelligence ``` -Forecast the next day of bicycle rentals from five observed days of hourly demand -in Washington, D.C. The example history is included with the package: +Pass a PyTorch tensor, NumPy array, pandas DataFrame, or CSV file to `model.forecast`. +The example below uses the bundled bicycle-rental data from Washington, D.C., +to forecast the next 24 hours from five days of hourly demand: ```python import continuousintelligence as ci @@ -98,69 +99,198 @@ you can try it. ## Usage details
-Forecast inputs and outputs +Usage details -Call `model.forecast(history, horizon=320)` with a two-dimensional PyTorch tensor. Rows -are target variables and columns are consecutive time steps. Rows are forecast jointly by -default. Supply `series_ids` to treat them as a cohort of independent univariate series. +### Prepare your history -In the table below, `V` is the number of target variables, `T` is the history length, -`H` is the requested horizon, and `Q` is the number of quantile levels. +History is the observed data you want to forecast from. ci-proto works with regularly +sampled data, can forecast multiple variables together, and can handle missing data. +Use `NaN` for missing values. The following formats are supported for the history: -| Value | Shape or type | Description | -| --- | --- | --- | -| `history` | `[V, T]` | Observed target values. Use `NaN` for missing observations. | -| `horizon` | `int` | Number of future steps to predict. Any positive integer; defaults to 320. | -| Returned forecast | `[V, Q, H]` | CPU `float32` tensor in the original target units, ordered by quantile level. | -| `model.quantiles` | `[Q]` | CPU tensor containing the probability level for each output quantile. | +**PyTorch tensors and NumPy arrays** with shape `[variables, time]`: one row per variable, +with observations running from left to right. This example has two variables and four +time steps: + +```python +import numpy as np +import torch + +values = [[12, 9, 7, 6], [8, 6, 5, 4]] +history = np.array(values) +# Or use a tensor with the same layout. +history = torch.tensor(values, dtype=torch.float32) +``` + +**pandas DataFrames** with one column per variable and one row per time step. The same +data looks like this: + +```python +import pandas as pd + +history = pd.DataFrame( + { + "store_a": [12, 9, 7, 6], + "store_b": [8, 6, 5, 4], + } +) +``` + +A pandas Series, such as `history["store_a"]`, can be used to forecast a single variable. + +**CSV files** with the same layout as a DataFrame. Include a header naming the variables: + +```csv +store_a,store_b +12,8 +9,6 +7,5 +6,4 +``` + +Pass the file path as history. + +```python +history = "examples/history.csv" +``` + +### Make a forecast -Input tensors can be real values or `NaN`. ci-proto returns nine quantiles -between 0.1 and 0.9 in increments of 0.1. Histories up to 16,384 observations use the -standard checkpoint. Longer histories automatically use the long checkpoint with the full -supplied history. The median is the central quantile. +Once you have your history, load the model and choose how many future steps to predict: + +```python +import continuousintelligence as ci + +model = ci.load_model("ContinuousIntelligence/ci-proto") +prediction = model.forecast(history, horizon=24) +``` + +`horizon` can be any positive integer and defaults to 320. For example, when forecasting hourly data, a horizon of +24 predicts the next day. By default, all of the variables are forecast together. If you want independent forecasts, pass each variable in a separate call. + +### Read the forecast + +ci-proto returns nine quantiles from 0.1 to 0.9. The 0.5 quantile is the median forecast with the other quantiles describing the predicted range of value. All forecast values are `float32` in the original units. + +The output depends on the history format. Here, `V` is the number of variables, `T` is +the history length, `H` is the horizon, and `Q` is the number of quantiles. + +| History | Returned forecast | +| --- | --- | +| PyTorch tensor | Tensor `[V, Q, H]` on the input tensor's device. | +| NumPy array | Array `[V, Q, H]`. | +| pandas DataFrame, Series, or CSV path | DataFrame with `H` rows and `(variable, quantile)` columns. A Series supplies its name as the variable label. | + +To extract the median from a DataFrame forecast or save all quantiles to CSV: + +```python +median = prediction.xs(0.5, level="quantile", axis=1) +prediction.to_csv("forecast.csv") +```
-Covariates and categorical inputs +Dates and frequency -Pass covariates as keyword arguments to -`model.forecast(..., past_covariates=..., future_covariates=...)`. Only the variables in -`history` receive forecasts. Align all tensors to the same time axis before calling the -model. +Dates are used automatically to provide calendar information, such as the hour and day +of the week. -| Argument | Shape | Requirements | +**PyTorch tensors and NumPy arrays** + +Using the tensor or NumPy history from above, supply dates for both the history and +the forecast horizon with `timestamps` and `freq`: + +```python +import pandas as pd +import torch + +dates = pd.date_range("2026-11-01", periods=history.shape[1] + 24, freq="h") +prediction = model.forecast( + history, + horizon=24, + timestamps=torch.tensor(dates.as_unit("ns").asi8), + freq="h", +) +``` + +**pandas DataFrames** + +For a DataFrame, you can attach them with a `DatetimeIndex`: + +```python +history.index = pd.date_range("2026-11-01", periods=len(history), freq="h") +``` + +**CSV files** + +For a CSV file, dates go in a `timestamp` column: + +```csv +timestamp,store_a,store_b +2026-11-01T00:00:00,12,8 +2026-11-01T01:00:00,9,6 +2026-11-01T02:00:00,7,5 +2026-11-01T03:00:00,6,4 +``` + +The [example CSV](examples/history.csv) contains two series with hourly timestamps: + +```python +prediction = model.forecast("examples/history.csv", horizon=24) +``` + +The timestamp arguments use the following shapes, with `T`, `H`, and `V` as defined above: + +| Argument | Shape or type | Description | | --- | --- | --- | -| `past_covariates` | `[past_variables, T]` | Must have exactly the same history length as `history`. | -| `future_covariates` | `[known_variables, T + H]` | Must cover both the observed history and the requested forecast horizon. | -| `categorical_past` | Tuple of row indices | Selects categorical rows in `past_covariates`; defaults to `()`. | -| `categorical_future` | Tuple of row indices | Selects categorical rows in `future_covariates`; defaults to `()`. | +| `timestamps` | `int64` tensor `[T + H]` or `[V, T + H]` | Epoch nanoseconds covering history and horizon, in increasing order. | +| `freq` | String | Sampling frequency, such as `"h"`, `"D"`, or `"W"`. Inferred from dated pandas and CSV inputs when possible. | -Represent categorical values with numeric category codes. For example, -`categorical_future=(0, 2)` marks its first and third rows as categorical. -Boolean covariates can be supplied as numeric -inputs without marking them categorical. Use `NaN` for missing covariate observations. +For gaps in a regular history, insert the missing time steps and use `NaN` for their values. For uneven histories, left-pad values with `NaN` and timestamps with `torch.iinfo(torch.int64).min`.
-Timestamps and related series +Covariates and categorical inputs -Pass optional metadata to add calendar features or context from related series. +Covariates are extra inputs that can help explain the variables in your history. Past +covariates contain observations available up to the forecast origin. Future covariates +contain values known for both the history and forecast horizon, such as a planned promotion. -| Argument | Shape or type | Description | +Pass them to `model.forecast` as `past_covariates` and `future_covariates`. They accept +the same formats and layouts as history. Align all inputs to the same time axis. Only +the variables in `history` receive forecasts. History also determines the output format +and device. + +| Argument | Shape | Requirements | | --- | --- | --- | -| `timestamps` | `int64` tensor `[T + H]` or `[V, T + H]` | Epoch nanoseconds covering history and horizon. Must increase strictly. | -| `freq` | String | Pandas frequency, such as `"h"`, `"D"` or `"W"`. Required for calendar features. | -| `series_ids` | `V` unique strings | Identifies independent series in input row order. | -| `static_features` | Mapping of column names to `V` values | Optional grouping metadata, such as `{"region": ["north", "south"]}`. Requires `series_ids`. | +| `past_covariates` | `[past_variables, T]` | Must have exactly the same history length as `history`. | +| `future_covariates` | `[known_variables, T + H]` | Must cover both the observed history and the requested forecast horizon. | +| `categorical_past` | Tuple of variable indices | Selects categorical variables in `past_covariates`; defaults to `()`. | +| `categorical_future` | Tuple of variable indices | Selects categorical variables in `future_covariates`; defaults to `()`. | + +A categorical covariate describes a category, such as the type of promotion running in +a store. For example, `0` could mean no promotion, `1` an email campaign, and `2` a discount. +These numbers identify categories rather than quantities. + +```python +history = pd.DataFrame({"sales": [12, 9, 7, 6]}) +future_covariates = pd.DataFrame({"promotion_type": [0, 0, 1, 2, 1, 0]}) +prediction = model.forecast( + history, + horizon=2, + future_covariates=future_covariates, + categorical_future=(0,), +) +``` -Pass all related series together. Context is shared only between series with the same -forecast origin. Covariates can be shared across series or supplied per series as -`[V, covariates, time]`. +The first four rows of `future_covariates` cover the history and the last two cover the +forecast horizon. `categorical_future=(0,)` marks the first covariate as categorical. +Indices refer to tensor/array rows or pandas/CSV columns, starting from zero. +Use `categorical_past` in the same way for past covariates. -For uneven histories, left-pad values with `NaN` and timestamps with -`torch.iinfo(torch.int64).min`. +Boolean covariates can be supplied as numeric inputs without marking them categorical. +Use `NaN` for missing covariate observations.
@@ -196,6 +326,9 @@ returns it. Hugging Face models always include it; local bundles may omit it. For reproducibility, pin Hugging Face models with a full commit SHA. `revision` applies only to Hub loading. Use `./` or a `Path` object to identify local paths explicitly. +Histories up to 16,384 observations use the standard checkpoint. Longer histories +automatically use the long checkpoint with the full supplied history. +
@@ -218,8 +351,10 @@ Fused inference requires CUDA-enabled PyTorch, an Ampere-or-newer NVIDIA GPU, a 580-series-or-newer driver, and a host C++ compiler. Replace CPU-only PyTorch to enable GPU inference. -Inspect `model.device` and `model.backend`: `"mamba3"` means fused CUDA inference; -`"torch"` means the portable backend. Forecast outputs are always CPU tensors. +Inference runs on `model.device`. Tensor forecasts return on the input tensor's device, +including its CUDA device index. NumPy and pandas outputs are on the CPU. + +`model.backend` is `"mamba3"` for fused CUDA inference or `"torch"` for the portable backend. Reference results use H100 with PyTorch `2.13.0+cu130`. Reduced-precision results can vary across runtimes. @@ -227,11 +362,11 @@ across runtimes.
-Other data and plotting options +Plotting forecasts -`ci.plot_forecast(history, prediction, quantiles)` works with your own data: -history has shape `[variables, time]`, predictions `[variables, quantiles, horizon]`, -and the quantile levels form a sorted vector including `0.5` for the median. +`ci.plot_forecast(history, prediction, quantiles)` accepts tensors: history has shape +`[variables, time]`, predictions `[variables, quantiles, horizon]`, and quantile levels +form a sorted vector including `0.5` for the median. Each variable gets its own panel with the median and available nested quantile bands. The function returns a Matplotlib figure; `output` saves it to a file. Pass `timestamps` covering history plus horizon for a date axis, and `ylabel` to label the values. @@ -248,9 +383,9 @@ python examples/forecast.py --model ContinuousIntelligence/ci-proto The plot is saved to `outputs/forecast.png`. -To forecast another source, pass `--data` with a CSV file and name its columns with -`--time-column` and `--value-column`. If the file has a `split` column, rows marked -`history` are observed and the following rows marked `forecast` set the horizon. +The plotting script reads CSV files using its own column options. Pass `--data` and name +the columns with `--time-column` and `--value-column`. If the file has a `split` column, +rows marked `history` are observed and the following rows marked `forecast` set the horizon. Otherwise every row is history; pass `--horizon`, and future timestamps continue the inferred frequency. `--ylabel` sets the axis label. @@ -278,7 +413,7 @@ calibration run automatically without changing model weights. | `target_encode_categoricals` | Encodes categories using observed target statistics. | | `clip_nonnegative` | Keeps forecasts nonnegative when the observed history is nonnegative. | | `integer_round` | Rounds forecasts when the observed history contains only integers. | -| `calendar_covariates` | Adds calendar features when timestamps and frequency are supplied. | +| `calendar_covariates` | Adds calendar features from dates and frequency. | | `bfloat16` | Enables reduced-precision inference; `false` uses float32. | Edit a local `tta.json` to change these flags. Encoding, clipping, rounding, calendar diff --git a/examples/history.csv b/examples/history.csv new file mode 100644 index 0000000..c8c5d17 --- /dev/null +++ b/examples/history.csv @@ -0,0 +1,25 @@ +timestamp,store_a,store_b +2026-11-01T00:00:00,12,8 +2026-11-01T01:00:00,9,6 +2026-11-01T02:00:00,7,5 +2026-11-01T03:00:00,6,4 +2026-11-01T04:00:00,8,5 +2026-11-01T05:00:00,14,9 +2026-11-01T06:00:00,25,18 +2026-11-01T07:00:00,42,31 +2026-11-01T08:00:00,58,45 +2026-11-01T09:00:00,65,52 +2026-11-01T10:00:00,72,58 +2026-11-01T11:00:00,80,64 +2026-11-01T12:00:00,86,70 +2026-11-01T13:00:00,83,68 +2026-11-01T14:00:00,78,63 +2026-11-01T15:00:00,82,67 +2026-11-01T16:00:00,91,74 +2026-11-01T17:00:00,96,80 +2026-11-01T18:00:00,84,69 +2026-11-01T19:00:00,67,54 +2026-11-01T20:00:00,49,38 +2026-11-01T21:00:00,35,26 +2026-11-01T22:00:00,24,17 +2026-11-01T23:00:00,17,12 diff --git a/pyproject.toml b/pyproject.toml index 41b0968..79a1ffb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "continuousintelligence" -version = "0.1.1" +version = "0.2.0" description = "Continuous Intelligence models" readme = "README.md" license = "LicenseRef-ci-proto AND Apache-2.0 AND CC-BY-4.0" diff --git a/src/continuousintelligence/ci_proto/_forecast.py b/src/continuousintelligence/ci_proto/_forecast.py index 215d91a..107abfc 100644 --- a/src/continuousintelligence/ci_proto/_forecast.py +++ b/src/continuousintelligence/ci_proto/_forecast.py @@ -18,6 +18,7 @@ from torch import Tensor, nn from torch.nn.functional import pad +from ._formats import ForecastInput, ForecastOutput, as_tensor, prepare_history from ._model import Model, forecast_layout @@ -56,21 +57,26 @@ def backend(self) -> str: def forecast( self, - history: Tensor, + history: ForecastInput, horizon: int = 320, *, - past_covariates: Tensor | None = None, - future_covariates: Tensor | None = None, + past_covariates: ForecastInput | None = None, + future_covariates: ForecastInput | None = None, categorical_past: tuple[int, ...] = (), categorical_future: tuple[int, ...] = (), timestamps: Tensor | None = None, freq: str | None = None, series_ids: Sequence[str] | None = None, static_features: Mapping[str, Sequence[object]] | None = None, - ) -> Tensor: + ) -> ForecastOutput: """Forecast joint variables, or independent series identified by ``series_ids``. - ``history``: float tensor ``[variables, time]``; NaN denotes missing data. + ``history``: tensor or NumPy array ``[variables, time]``, pandas DataFrame + (time rows, variable columns), Series, or CSV path with numeric columns. + NaN denotes missing data. Covariates accept the same input formats. + CSV files may include a ``timestamp`` column. A pandas DatetimeIndex or + CSV timestamps supply calendar dates; frequency is inferred or set by + ``freq``. Dated histories must be regularly spaced. ``past_covariates``: ``[past_variables, time]``. ``future_covariates``: ``[known_variables, time + horizon]``; extra future steps are ignored. Only supply values known at forecast time. Categorical @@ -86,17 +92,26 @@ def forecast( names to values in input row order. Cohort covariates can also be shaped ``[variables, covariates, time]``, including the horizon for known values. - Returns CPU float32 quantiles ``[variables, quantiles, horizon]``, in - original units, with levels given by ``self.quantiles``. ci-proto returns - nine quantiles between 0.1 and 0.9 in increments of 0.1. Horizon is any - positive integer and defaults to 320. + Returns float32 quantiles in the original units. Tensors retain the input + device; NumPy inputs return arrays, both ``[variables, quantiles, horizon]``. + Pandas and CSV inputs return a DataFrame with horizon rows and + ``(variable, quantile)`` columns, indexed by future dates for dated inputs + or by steps starting at zero otherwise. + Levels are given by ``self.quantiles``. Horizon is any positive integer + and defaults to 320. """ model, tta = self._model, self._tta if type(horizon) is not int or horizon < 1: raise ValueError("horizon must be a positive integer") + history, restore, timestamps, freq = prepare_history( + history, model.get_buffer("quantiles"), horizon, timestamps, freq + ) + if past_covariates is not None: + past_covariates = as_tensor(past_covariates, "past_covariates") + if future_covariates is not None: + future_covariates = as_tensor(future_covariates, "future_covariates") if ( self._long_model is not None - and isinstance(history, Tensor) and history.ndim == 2 and history.shape[-1] > model.config.context_len ): @@ -134,7 +149,7 @@ def forecast( series_ids, static_features, ) - return _run_cases(model, cases, count, horizon, tta) + return restore(_run_cases(model, cases, count, horizon, tta)) if static_features is not None: raise ValueError("static_features requires series_ids") if stamps is not None: @@ -159,7 +174,7 @@ def forecast( context, future = _with_calendar( context, future, count, stamps, freq, bool(tta["calendar_covariates"]) ) - return _predict(model, context[None], future[None], count, horizon, tta)[0] + return restore(_predict(model, context[None], future[None], count, horizon, tta)[0]) def _rows( @@ -448,7 +463,7 @@ def _predict( expected = (samples * n_targets, model.get_buffer("quantiles").numel(), horizon) if pred.shape != expected or not bool(torch.isfinite(pred).all()): raise ValueError("model returned invalid forecast values or shape") - return pred.reshape(samples, n_targets, -1, horizon).detach().cpu() + return pred.reshape(samples, n_targets, -1, horizon).detach() def _timestamps( @@ -682,7 +697,13 @@ def _run_cases( horizon: int, tta: Mapping[str, float], ) -> Tensor: - out = torch.empty(count, model.get_buffer("quantiles").numel(), horizon) + out = torch.empty( + count, + model.get_buffer("quantiles").numel(), + horizon, + device=next(model.parameters()).device, + dtype=torch.float32, + ) pending: dict[tuple[int, int, int], list[_Case]] = {} rows = 0 views = 2 if tta["postprocess"] and tta["tta_sign_flip"] else 1 diff --git a/src/continuousintelligence/ci_proto/_formats.py b/src/continuousintelligence/ci_proto/_formats.py new file mode 100644 index 0000000..ddb62f7 --- /dev/null +++ b/src/continuousintelligence/ci_proto/_formats.py @@ -0,0 +1,107 @@ +"""Convert forecast inputs and restore their containers at the API boundary.""" + +from collections.abc import Callable +from pathlib import Path + +import numpy as np +import pandas as pd +import torch +from torch import Tensor + +ForecastInput = Tensor | np.ndarray | pd.DataFrame | pd.Series | str | Path +ForecastOutput = Tensor | np.ndarray | pd.DataFrame + + +def _read_csv(path: str | Path) -> pd.DataFrame: + frame = pd.read_csv(Path(path).expanduser()) + if "timestamp" in frame.columns: + frame = frame.set_index("timestamp") + frame.index = pd.DatetimeIndex(pd.to_datetime(frame.index)) + return frame + + +def _dates( + index: pd.DatetimeIndex, horizon: int, freq: str | None +) -> tuple[pd.DatetimeIndex, Tensor, str]: + if index.empty or index.hasnans or not index.is_unique or not index.is_monotonic_increasing: + raise ValueError("history dates must be nonempty, unique, and increasing") + freq = freq or index.freqstr + if freq is None and len(index) >= 3: + freq = pd.DatetimeIndex(index, freq="infer").freqstr + if freq is None: + raise ValueError("cannot infer history frequency; pass freq, for example freq='h'") + dates = pd.date_range(index[0], periods=len(index) + horizon, freq=freq, name=index.name) + if not (dates[: len(index)] == index).all(): + raise ValueError("history dates must be regularly spaced at freq; reindex missing steps") + stamps = torch.from_numpy(dates.as_unit("ns").asi8.copy()) + return dates, stamps, freq + + +def as_tensor(value: ForecastInput, name: str) -> Tensor: + """Arrays use [variables, time]; tables use time rows and variable columns.""" + if isinstance(value, Tensor): + return value + if isinstance(value, (str, Path)): + value = _read_csv(value) + if isinstance(value, pd.Series): + value = value.to_frame() + if isinstance(value, pd.DataFrame): + array = value.to_numpy() + if array.dtype == object and all(dtype.kind in "biuf" for dtype in value.dtypes): + array = value.to_numpy(dtype=np.float64, na_value=np.nan) + value = array.T + if not isinstance(value, np.ndarray): + raise ValueError(f"{name} must be a tensor, NumPy array, pandas object, or CSV path") + try: + # Copy to support negative strides and read-only pandas/NumPy buffers. + return torch.from_numpy(value.copy()) + except (TypeError, ValueError) as error: + raise ValueError(f"{name} must contain numeric values or NaN") from error + + +def prepare_history( + history: ForecastInput, + quantiles: Tensor, + horizon: int, + timestamps: Tensor | None, + freq: str | None, +) -> tuple[Tensor, Callable[[Tensor], ForecastOutput], Tensor | None, str | None]: + """Remember output labels and the caller's device before converting history.""" + if isinstance(history, (str, Path)): + history = _read_csv(history) + if isinstance(history, pd.Series): + history = history.to_frame() + tensor = as_tensor(history, "history") + if isinstance(history, Tensor): + device = history.device + return tensor, lambda prediction: prediction.to(device), timestamps, freq + if isinstance(history, np.ndarray): + return tensor, lambda prediction: prediction.cpu().numpy(), timestamps, freq + + future_index = pd.RangeIndex(horizon, name="step") + if isinstance(history.index, pd.DatetimeIndex): + dates, stamps, freq = _dates(history.index, horizon, freq) + if timestamps is not None: + if ( + not isinstance(timestamps, Tensor) + or timestamps.dtype != torch.int64 + or timestamps.ndim not in (1, 2) + or timestamps.shape[-1] < len(dates) + or not torch.equal( + timestamps[..., : len(dates)].detach().cpu(), + stamps.expand_as(timestamps[..., : len(dates)]), + ) + ): + raise ValueError("timestamps must match the history dates and forecast frequency") + else: + timestamps = stamps + future_index = dates[len(history) :] + + levels = quantiles.tolist() + columns = pd.MultiIndex.from_product([history.columns, levels], names=["variable", "quantile"]) + + def restore_frame(prediction: Tensor) -> pd.DataFrame: + values = prediction.permute(2, 0, 1).cpu().numpy().reshape(horizon, -1) + return pd.DataFrame(values, index=future_index, columns=columns) + + return tensor, restore_frame, timestamps, freq diff --git a/tests/test_dates.py b/tests/test_dates.py new file mode 100644 index 0000000..7da3723 --- /dev/null +++ b/tests/test_dates.py @@ -0,0 +1,170 @@ +"""Date-aware pandas and CSV forecasts use the existing calendar API.""" + +from pathlib import Path + +import numpy as np +import pandas as pd +import pytest +import torch +from test_forecast import TTA, Probe + +from continuousintelligence import load_model +from continuousintelligence.ci_proto import Forecaster + + +@pytest.mark.parametrize("cohort", [False, True]) +@pytest.mark.parametrize("kind", ["dataframe", "series", "csv_path", "csv_string"]) +def test_dated_forecast_matches_explicit_calendar_inputs(release_files, tmp_path, kind, cohort): + model = load_model(*release_files, device="cpu") + dates = pd.date_range("2026-11-01 09:00", periods=7, freq="h", name="timestamp") + frame = pd.DataFrame( + {"load": [0.25, -0.5, np.nan, 0.75], "temperature": [1.5, -2.5, 3.5, -4.5]}, + # Drop frequency metadata so the frequency must be inferred from the dates. + index=pd.DatetimeIndex(list(dates[:4]), name="timestamp"), + ) + if kind == "series": + frame = frame[["load"]] + source = frame["load"] + elif kind == "dataframe": + source = frame.copy() + else: + path = tmp_path / "history.csv" + frame.to_csv(path) + source = path if kind == "csv_path" else str(path) + before = frame.copy(deep=True) + arguments = {"series_ids": list(reversed(frame.columns))} if cohort else {} + expected = model.forecast( + torch.from_numpy(frame.to_numpy().T.copy()), + 3, + timestamps=torch.tensor(dates.as_unit("ns").asi8), + freq="h", + **arguments, + ) + actual = model.forecast(source, 3, **arguments) + expected = pd.DataFrame( + expected.permute(2, 0, 1).numpy().reshape(3, -1), + index=dates[4:], + columns=pd.MultiIndex.from_product( + [frame.columns, model.quantiles.tolist()], names=["variable", "quantile"] + ), + ) + pd.testing.assert_frame_equal(actual, expected) + pd.testing.assert_frame_equal(frame, before) + if kind == "dataframe": + pd.testing.assert_frame_equal(source, before) + elif kind == "series": + pd.testing.assert_series_equal(source, before["load"]) + + +@pytest.mark.parametrize("freq", ["MS", "ME", "W-MON", "D"]) +def test_calendar_frequency_preserves_future_dates(freq): + dates = pd.date_range("2024-01-01", periods=7, freq=freq, name="date") + frame = pd.DataFrame({"load": [1.5, -2.5, 3.5, -4.5]}, index=dates[:4]) + model = Forecaster(Probe(), TTA) + prediction = model.forecast(frame, 3) + pd.testing.assert_index_equal(prediction.index, dates[4:]) + assert np.isfinite(prediction.to_numpy()).all() + + +def test_timezone_and_daylight_saving_time_are_preserved(): + dates = pd.date_range( + "2026-03-08 00:00", periods=6, freq="h", tz="America/New_York", name="time" + ) + frame = pd.DataFrame({"load": [0.25, -0.5, 0.75]}, index=dates[:3]) + prediction = Forecaster(Probe(), TTA).forecast(frame, 3) + pd.testing.assert_index_equal(prediction.index, dates[3:]) + + +def test_utc_csv_preserves_dates(tmp_path): + dates = pd.date_range("2026-11-01", periods=6, freq="h", tz="UTC", name="timestamp") + frame = pd.DataFrame({"load": [0.25, -0.5, 0.75, -0.25]}, index=dates[:4]) + path = tmp_path / "history.csv" + frame.to_csv(path) + prediction = Forecaster(Probe(), TTA).forecast(path, 2) + pd.testing.assert_index_equal(prediction.index, dates[4:]) + + +@pytest.mark.parametrize("length", [1, 2]) +def test_short_history_accepts_explicit_frequency(length): + dates = pd.date_range("2026-11-01", periods=length + 2, freq="h") + frame = pd.DataFrame( + {"load": [0.25, -0.5][:length]}, index=pd.DatetimeIndex(list(dates[:length])) + ) + model = Forecaster(Probe(), TTA) + with pytest.raises(ValueError, match="infer.*frequency"): + model.forecast(frame, 2) + prediction = model.forecast(frame, 2, freq="h") + pd.testing.assert_index_equal(prediction.index, dates[length:]) + + +@pytest.mark.parametrize( + "dates,freq,message", + [ + (["2026-11-01", "2026-11-01"], "D", "unique"), + (["2026-11-02", "2026-11-01"], "D", "increasing"), + (["2026-11-01", None], "D", "increasing"), + (["2026-11-01", "2026-11-02", "2026-11-04"], None, "infer.*frequency"), + (["2026-11-01", "2026-11-02", "2026-11-04"], "D", "regularly spaced"), + ], +) +def test_invalid_dates_fail_before_inference(dates, freq, message): + neural = Probe() + frame = pd.DataFrame({"load": np.ones(len(dates))}, index=pd.to_datetime(dates)) + with pytest.raises(ValueError, match=message): + Forecaster(neural, TTA).forecast(frame, 2, freq=freq) + assert not neural.batches + + +@pytest.mark.parametrize("per_series", [False, True]) +def test_explicit_timestamps_must_agree_with_dated_history(per_series): + dates = pd.date_range("2026-11-01", periods=6, freq="h") + frame = pd.DataFrame({"load": [0.25, -0.5, 0.75, -0.25]}, index=dates[:4]) + stamps = torch.tensor(dates.as_unit("ns").asi8) + if per_series: + stamps = stamps[None] + model = Forecaster(Probe(), TTA) + actual = model.forecast(frame, 2, timestamps=stamps) + expected = model.forecast(frame, 2) + pd.testing.assert_frame_equal(actual, expected) + for index in (0, -1): + damaged = stamps.clone() + damaged[..., index] += 1 + with pytest.raises(ValueError, match="timestamps must match"): + model.forecast(frame, 2, timestamps=damaged) + + +def test_dated_csv_covariates(tmp_path): + dates = pd.date_range("2026-11-01", periods=6, freq="h", name="timestamp") + history = pd.DataFrame({"load": [0.25, -0.5, 0.75, -0.25]}, index=dates[:4]) + past = pd.DataFrame({"past": [1.0, 2.0, 3.0, 4.0]}, index=dates[:4]) + future = pd.DataFrame({"known": [0, 0, 1, 1, 0, 1]}, index=dates) + past_path, future_path = tmp_path / "past.csv", tmp_path / "future.csv" + past.to_csv(past_path) + future.to_csv(future_path) + model = Forecaster(Probe(), TTA) + actual = model.forecast( + history, + 2, + past_covariates=past_path, + future_covariates=future_path, + categorical_future=(0,), + ) + expected = model.forecast( + history, + 2, + past_covariates=past, + future_covariates=future, + categorical_future=(0,), + ) + pd.testing.assert_frame_equal(actual, expected) + + +def test_example_csv(): + path = Path(__file__).resolve().parents[1] / "examples" / "history.csv" + prediction = Forecaster(Probe(), TTA).forecast(path, 3) + expected = pd.date_range("2026-11-02", periods=3, freq="h", name="timestamp") + pd.testing.assert_index_equal(prediction.index, expected) + assert prediction.columns.get_level_values("variable").unique().tolist() == [ + "store_a", + "store_b", + ] diff --git a/tests/test_formats.py b/tests/test_formats.py new file mode 100644 index 0000000..bedb6b2 --- /dev/null +++ b/tests/test_formats.py @@ -0,0 +1,187 @@ +"""Public forecast containers, tabular labels, and input-device placement.""" + +import numpy as np +import pandas as pd +import pytest +import torch +from test_forecast import TTA, Probe + +from continuousintelligence import load_model +from continuousintelligence.ci_proto import Forecaster + + +@pytest.mark.parametrize("cohort", [False, True]) +@pytest.mark.parametrize("kind", ["numpy", "dataframe", "series", "csv_path", "csv_string"]) +def test_forecast_returns_expected_container(release_files, tmp_path, kind, cohort): + model = load_model(*release_files, device="cpu") + history = torch.tensor([[0.25, -0.5, torch.nan, 0.75], [1.5, -2.5, 3.5, -4.5]]) + if kind == "series": + history = history[:1] + labels = ["load", "temperature"][: len(history)] + frame = pd.DataFrame(history.numpy().T, columns=labels) + if kind == "numpy": + source = history.numpy().copy() + # Reversed arrays can have negative strides; read-only inputs are valid. + source = source[:, ::-1].copy()[:, ::-1] + source.setflags(write=False) + elif kind == "series": + source = frame["load"] + elif kind == "dataframe": + source = frame.copy() + else: + path = tmp_path / "history.csv" + frame.to_csv(path, index=False) + source = path if kind == "csv_path" else str(path) + arguments = {"series_ids": list(reversed(labels))} if cohort else {} + expected = model.forecast(history, 3, **arguments).numpy() + actual = model.forecast(source, 3, **arguments) + if kind == "numpy": + assert isinstance(actual, np.ndarray) and actual.dtype == np.float32 + np.testing.assert_array_equal(actual, expected) + np.testing.assert_array_equal(source, history.numpy()) + else: + assert isinstance(actual, pd.DataFrame) + pd.testing.assert_index_equal(actual.index, pd.RangeIndex(3, name="step")) + assert actual.columns.names == ["variable", "quantile"] + assert actual.columns.tolist() == [ + (label, q) for label in labels for q in model.quantiles.tolist() + ] + np.testing.assert_array_equal(actual.to_numpy(), expected.transpose(2, 0, 1).reshape(3, -1)) + assert all(dtype == np.float32 for dtype in actual.dtypes) + if kind == "series": + pd.testing.assert_series_equal(source, frame["load"]) + elif kind == "dataframe": + pd.testing.assert_frame_equal(source, frame) + else: + pd.testing.assert_frame_equal(pd.read_csv(path), frame, check_dtype=False) + + +@pytest.mark.parametrize("cohort", [False, True]) +def test_covariates_accept_mixed_formats(tmp_path, cohort): + model = Forecaster(Probe(), TTA) + history = torch.tensor([[0.25, -0.5, 0.75, -0.25]]) + past = torch.tensor([[1.0, 2.0, 3.0, 4.0]]) + future = torch.tensor([[0, 0, 1, 1, 0, 1]]) + arguments = {"series_ids": ["load"]} if cohort else {} + expected = model.forecast( + history, + 2, + past_covariates=past, + future_covariates=future, + categorical_future=(0,), + **arguments, + ) + future_path = tmp_path / "future.csv" + pd.DataFrame(future.numpy().T).to_csv(future_path, index=False) + actual = model.forecast( + history.numpy(), + 2, + past_covariates=pd.Series(past[0].numpy()), + future_covariates=future_path, + categorical_future=(0,), + **arguments, + ) + np.testing.assert_array_equal(actual, expected.numpy()) + + +def test_nullable_numeric_pandas_columns(): + frame = pd.DataFrame( + { + "load": pd.Series([0.25, pd.NA, -0.5, 0.75], dtype="Float64"), + "count": pd.Series([1, 2, pd.NA, 4], dtype="Int64"), + "flag": pd.Series([True, False, pd.NA, True], dtype="boolean"), + } + ) + before = frame.copy(deep=True) + model = Forecaster(Probe(), TTA) + expected = model.forecast( + torch.tensor([[0.25, torch.nan, -0.5, 0.75], [1, 2, torch.nan, 4], [1, 0, torch.nan, 1]]), + 2, + ).numpy() + actual = model.forecast(frame, 2) + np.testing.assert_array_equal(actual.to_numpy(), expected.transpose(2, 0, 1).reshape(2, -1)) + pd.testing.assert_frame_equal(frame, before) + + +@pytest.mark.parametrize("kind", ["numpy", "dataframe", "csv"]) +def test_non_tensor_history_selects_long_model(tmp_path, kind): + standard = Probe() + long = Probe([[11.0, 12.0, 13.0]]) + long.config.context_len = 32 + model = Forecaster(standard, {**TTA, "postprocess": False}) + model._long_model = lambda: Forecaster(long, {**TTA, "postprocess": False}) + history = np.sin(np.arange(17, dtype=np.float32))[None] + if kind != "numpy": + history = pd.DataFrame(history.T, columns=["load"]) + if kind == "csv": + path = tmp_path / "history.csv" + history.to_csv(path, index=False) + history = path + model.forecast(history, 2) + assert not standard.batches + assert long.batches[0]["x"].shape[-1] == 32 + long.config.future_len + + +@pytest.mark.parametrize( + "history", + [ + np.ones(4), + np.empty((0, 4)), + [[1, 2, 3]], + pd.DataFrame({"load": [1.0], "label": ["bad"]}), + np.array([[complex(1, 2)]]), + ], +) +def test_invalid_formats_fail_before_inference(history): + neural = Probe() + with pytest.raises(ValueError, match="history"): + Forecaster(neural, TTA).forecast(history, 2) + assert not neural.batches + + +@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA hardware is unavailable") +@pytest.mark.parametrize("cohort", [False, True]) +@pytest.mark.parametrize( + "model_device,input_device", + [ + ("cuda:0", "cpu"), + ("cuda:0", "cuda:0"), + ("cpu", "cuda:0"), + pytest.param( + "cuda:0", + "cuda:1", + marks=pytest.mark.skipif( + torch.cuda.device_count() < 2, reason="Two CUDA devices are required" + ), + ), + ], +) +def test_tensor_output_keeps_input_device(release_files, model_device, input_device, cohort): + model = load_model(*release_files, device="cpu") + model._model.to(model_device) + history = torch.tensor( + [[0.25, -0.5, 0.75, -0.25]], device=input_device, dtype=torch.float64, requires_grad=True + ) + arguments = {"series_ids": ["load"]} if cohort else {} + current = torch.cuda.current_device() + expected = model.forecast(history.detach().cpu(), 3, **arguments) + actual = model.forecast(history, 3, **arguments) + assert actual.device == history.device + assert actual.dtype == torch.float32 and not actual.requires_grad + assert model.device == torch.device(model_device) + assert torch.cuda.current_device() == current + torch.testing.assert_close(actual.cpu(), expected) + + +@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA hardware is unavailable") +@pytest.mark.parametrize("cohort", [False, True]) +def test_gpu_model_returns_host_numpy_and_pandas(release_files, cohort): + model = load_model(*release_files, device="cpu") + model._model.cuda() + history = np.array([[0.25, -0.5, 0.75, -0.25]], dtype=np.float32) + arguments = {"series_ids": ["load"]} if cohort else {} + expected = model.forecast(torch.from_numpy(history), 3, **arguments) + actual = model.forecast(history, 3, **arguments) + np.testing.assert_array_equal(actual, expected.numpy()) + frame = model.forecast(pd.DataFrame(history.T, columns=["load"]), 3, **arguments) + np.testing.assert_array_equal(frame["load"].to_numpy().T, actual[0]) diff --git a/uv.lock b/uv.lock index 66a70da..1da8627 100644 --- a/uv.lock +++ b/uv.lock @@ -320,7 +320,7 @@ wheels = [ [[package]] name = "continuousintelligence" -version = "0.1.1" +version = "0.2.0" source = { editable = "." } dependencies = [ { name = "apache-tvm-ffi", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },