fix: resolve 8 bugs from pre-release testing (circular import, naive backtest, missing APIs) (#265)

Author: MathieuCayssol

functime/__init__.py

@@ -1,5 +1,5 @@
 "functime: Time-series machine learning at scale."
 
-__version__ = "1.0.0rc1"
+__version__ = "1.0.0"
 
 from functime.feature_extractors import FeatureExtractor  # noqa: F401

functime/backtesting.py

@@ -156,30 +156,94 @@ def backtest(
         # Append results
         y_preds.append(y_pred)
         if residualize:
-            # Residuals
-            y_resid = _residualize_autoreg(
-                y_train=y_train,
-                X_train=X_train,
-                strategy=forecaster.state.strategy,
-                lags=forecaster.lags,
-                max_horizons=forecaster.max_horizons,
-                artifacts=forecaster.state.artifacts,
+            # Residuals — only for autoregressive models that have a regressor
+            artifacts = forecaster.state.artifacts
+            has_regressor = (
+                "regressor" in artifacts
+                or "regressors" in artifacts
+                or (
+                    "recursive" in artifacts
+                    and "regressor" in artifacts.get("recursive", {})
+                )
             )
+            if has_regressor:
+                y_resid = _residualize_autoreg(
+                    y_train=y_train,
+                    X_train=X_train,
+                    strategy=forecaster.state.strategy,
+                    lags=forecaster.lags,
+                    max_horizons=forecaster.max_horizons,
+                    artifacts=artifacts,
+                )
+            else:
+                # For non-autoregressive models (e.g. naive, snaive),
+                # compute naive residuals: y[t] - y[t-1]
+                _y_train_df = y_train.lazy().collect(engine="streaming") if isinstance(y_train, pl.LazyFrame) else y_train
+                idx_cols = _y_train_df.columns[:2]
+                _target_col = _y_train_df.columns[-1]
+                y_resid = (
+                    _y_train_df.sort(idx_cols)
+                    .with_columns(
+                        (
+                            pl.col(_target_col)
+                            - pl.col(_target_col).shift(1).over(idx_cols[0])
+                        ).alias("y_resid")
+                    )
+                    .select(*idx_cols, "y_resid")
+                    .drop_nulls()
+                )
+            if isinstance(y_resid, pl.LazyFrame):
+                y_resid = y_resid.collect(engine="streaming")
             y_resid = y_resid.with_columns(pl.lit(i).alias("split"))
             y_resids.append(y_resid)
 
     y_preds = pl.concat(y_preds)
     full_forecaster = forecaster.fit(y=y, X=X)
     if residualize:
-        y_resids = _merge_autoreg_residuals(
-            y=y,
-            X=X,
-            y_resids=pl.concat(y_resids),
-            strategy=full_forecaster.state.strategy,
-            lags=forecaster.lags,
-            max_horizons=forecaster.max_horizons,
-            artifacts=full_forecaster.state.artifacts,
+        artifacts = full_forecaster.state.artifacts
+        has_regressor = (
+            "regressor" in artifacts
+            or "regressors" in artifacts
+            or (
+                "recursive" in artifacts
+                and "regressor" in artifacts.get("recursive", {})
+            )
         )
+        # Collect any lazy residuals
+        y_resids_collected = [
+            r.collect(engine="streaming") if isinstance(r, pl.LazyFrame) else r
+            for r in y_resids
+        ]
+        if has_regressor:
+            y_resids = _merge_autoreg_residuals(
+                y=y,
+                X=X,
+                y_resids=pl.concat(y_resids_collected),
+                strategy=full_forecaster.state.strategy,
+                lags=forecaster.lags,
+                max_horizons=forecaster.max_horizons,
+                artifacts=artifacts,
+            )
+        else:
+            # For non-autoregressive models, compute naive residuals for the full data
+            _y_df = y.lazy().collect(engine="streaming") if isinstance(y, pl.LazyFrame) else y
+            idx_cols = _y_df.columns[:2]
+            _target_col = _y_df.columns[-1]
+            y_resid = (
+                _y_df.sort(idx_cols)
+                .with_columns(
+                    (
+                        pl.col(_target_col)
+                        - pl.col(_target_col).shift(1).over(idx_cols[0])
+                    ).alias("y_resid")
+                )
+                .select(*idx_cols, "y_resid")
+                .drop_nulls()
+            )
+            combined = pl.concat(y_resids_collected)
+            last_split = combined.get_column("split").max() + 1
+            y_resid = y_resid.with_columns(pl.lit(last_split).alias("split"))
+            y_resids = pl.concat([combined, y_resid])
         pl.disable_string_cache()
         return y_preds, y_resids
     pl.disable_string_cache()

functime/base/forecaster.py

@@ -31,6 +31,7 @@
     "1d",
     "1w",
     "1mo",
+    "1q",
     "3mo",
     "1y",
 ]

functime/conversion.py

@@ -4,6 +4,95 @@
 import polars as pl
 
 
+def wide_to_long(
+    df: pl.DataFrame,
+    id_col: str = "entity_id",
+    time_col: str = "date",
+    value_col: str = "value",
+) -> pl.DataFrame:
+    """Convert a wide-format DataFrame to long (panel) format.
+
+    In wide format, each entity is a column and each row is a timestamp.
+    In long format, there are three columns: entity, time, and value.
+
+    Parameters
+    ----------
+    df : pl.DataFrame
+        Wide-format DataFrame where the first column is the time index
+        and remaining columns are entities.
+    id_col : str
+        Name for the entity column in the output. Defaults to "entity_id".
+    time_col : str
+        Name of the time column (must exist in the input). Defaults to "date".
+    value_col : str
+        Name for the value column in the output. Defaults to "value".
+
+    Returns
+    -------
+    pl.DataFrame
+        Long-format panel DataFrame with columns [id_col, time_col, value_col].
+    """
+    # Determine the time column — use time_col if present, otherwise first column
+    if time_col in df.columns:
+        time_column = time_col
+    else:
+        time_column = df.columns[0]
+
+    entity_columns = [c for c in df.columns if c != time_column]
+    result = df.unpivot(
+        on=entity_columns,
+        index=time_column,
+        variable_name=id_col,
+        value_name=value_col,
+    )
+    # Rename the time column if needed
+    if time_column != time_col:
+        result = result.rename({time_column: time_col})
+    # Reorder to [entity, time, value]
+    return result.select(id_col, time_col, value_col)
+
+
+def long_to_wide(
+    df: pl.DataFrame,
+    id_col: str | None = None,
+    time_col: str | None = None,
+    value_col: str | None = None,
+) -> pl.DataFrame:
+    """Convert a long (panel) format DataFrame to wide format.
+
+    In long format, there are entity, time, and value columns.
+    In wide format, each entity becomes its own column and each row is a timestamp.
+
+    Parameters
+    ----------
+    df : pl.DataFrame
+        Long-format panel DataFrame with at least 3 columns:
+        entity, time, value (in that order if col names not specified).
+    id_col : str, optional
+        Name of the entity column. Defaults to first column.
+    time_col : str, optional
+        Name of the time column. Defaults to second column.
+    value_col : str, optional
+        Name of the value column. Defaults to third column.
+
+    Returns
+    -------
+    pl.DataFrame
+        Wide-format DataFrame where each entity is a column.
+    """
+    cols = df.columns
+    id_col = id_col or cols[0]
+    time_col = time_col or cols[1]
+    value_col = value_col or cols[2]
+
+    result = df.pivot(
+        on=id_col,
+        index=time_col,
+        values=value_col,
+    ).sort(time_col)
+    return result
+
+
 def df_to_ndarray(df: pl.DataFrame) -> np.ndarray:
     """Zero-copy spill-to-disk Polars DataFrame to numpy ndarray."""
     return df.to_numpy()

functime/forecasting/automl.py

@@ -79,6 +79,18 @@ def __init__(
         if freq not in SUPPORTED_FREQ:
             raise ValueError(f"Offset {freq} not supported")
 
+        # Validate kwargs: reject common automl-param misplacements
+        _automl_params = {
+            "n_evals", "n_trials", "n_iter", "max_evals", "max_trials",
+        }
+        bad_kwargs = _automl_params & set(kwargs)
+        if bad_kwargs:
+            raise TypeError(
+                f"Unknown keyword argument(s) {bad_kwargs} for the underlying regressor. "
+                f"AutoML evaluation count is controlled by `num_samples`, not {bad_kwargs.pop()!r}. "
+                f"Only pass keyword arguments accepted by the sklearn-compatible regressor."
+            )
+
         self.freq = freq
         self.min_lags = min_lags
         self.max_lags = max_lags

functime/forecasting/elite.py

@@ -9,7 +9,6 @@
 from sklearn.linear_model import LassoLarsIC
 from tqdm import tqdm
 
-from functime.backtesting import backtest
 from functime.base.forecaster import Forecaster
 from functime.base.metric import METRIC_TYPE
 from functime.conversion import X_to_numpy, y_to_numpy
@@ -244,6 +243,7 @@ def _fit(self, y: pl.LazyFrame, X: pl.LazyFrame | None = None):
                 )
             else:
                 forecaster = forecaster_cls(freq=freq)
+            from functime.backtesting import backtest
             y_preds = backtest(forecaster=forecaster, y=y, cv=cv, residualize=False)
             cv_y_preds[model_name] = y_preds.pipe(coerce_dtypes(schema)).collect()
 

functime/metrics/__init__.py

@@ -10,6 +10,11 @@
     smape_original,
     underforecast,
 )
+from .probabilistic import (
+    crps,
+    interval_coverage,
+    winkler_score,
+)
 
 __all__ = [
     "mae",
@@ -22,4 +27,7 @@
     "smape_original",
     "overforecast",
     "underforecast",
+    "crps",
+    "interval_coverage",
+    "winkler_score",
 ]