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'" },