Profiles

skforecast_ai.schemas.profiles

Classes:

Name	Description
SeriesLengthInfo	Per-series index range and observation count.
DataProfile	Profile of the input time series dataset.
SeriesPacf	PACF-significant lags for a single series.
ForecastingProfile	High-level profile of the forecasting problem.

Classes

SeriesLengthInfo

Bases: BaseModel

Per-series index range and observation count.

Attributes:

Name	Type	Description
start	str, default None	First timestamp of the series as a string (e.g. '2020-01-01'). None when the index is not datetime.
end	str, default None	Last timestamp of the series as a string. None when the index is not datetime.
length	int	Number of observations in the series.

Attributes

start class-attribute instance-attribute

start = None

end class-attribute instance-attribute

end = None

length instance-attribute

length

DataProfile

Bases: BaseModel

Profile of the input time series dataset.

Attributes:

Name	Type	Description
data_format	str, default 'single'	Layout of the dataset. One of 'single', 'wide', 'long'.
n_series	int	Number of individual time series.
series_lengths	dict	Mapping of series name to its SeriesLengthInfo (start, end, and length). Always populated, including single series (keyed by the target name). The task-aware effective number of observations is derived from this mapping (span for multi_series, common length for multivariate, single length otherwise).
span_index_length	int	Length of the union datetime index spanning every series, from the earliest start to the latest end at frequency. Falls back to the longest individual series when datetime bounds or frequency are unavailable. Computed automatically from series_lengths.
n_total_observations	int	Pooled total number of observations across all series (the sum of every series length). Computed automatically from series_lengths.
target	(str, list)	Name(s) of the target column(s). A single string for single series and long format. A list of strings for wide format where each element is a series column.
target_dtype	str, default 'numeric'	Data type category of the target column. One of 'numeric', 'categorical', 'other'.
target_stats	dict	Mapping of target column (or series name) to a dict with keys 'min', 'max', 'mean', 'std' computed on non-NaN values. Empty dict if no valid observations exist.
missing_target	dict	Mapping of target column (or series name) to count of NaN values. Only entries with at least one missing value are included.
date_column	str, default None	Name of the column containing timestamps.
series_id_column	str, default None	Name of the column identifying individual series.
index_type	str	Type of the DataFrame index. One of 'datetime', 'range', 'other'.
frequency	str, default None	Inferred pandas frequency string (e.g. 'h', 'D', 'ME').
frequency_is_set	bool, default False	Whether the index already has a frequency set (index.freq).
index_is_monotonic	bool, default True	Whether the index is sorted in ascending order.
has_gaps	bool, default False	Whether the datetime index has missing timestamps within its range.
has_duplicate_timestamps	bool, default False	Whether the index contains duplicate timestamps.
exog_columns	list	Names of exogenous predictor columns.
categorical_exog	list	Subset of exog_columns that are categorical.
missing_exog	dict	Mapping of exogenous column name to count of missing values. Only columns with at least one missing value are included.
data_path	str, default 'data.csv'	Path to the source CSV file. Derived automatically during profiling: if the input is a file path, this stores it; if the input is a DataFrame, defaults to 'data.csv'.
warnings	list	Human-readable warnings generated during profiling.

Attributes

data_format class-attribute instance-attribute

data_format = 'single'

n_series instance-attribute

n_series

series_lengths instance-attribute

series_lengths

span_index_length class-attribute instance-attribute

span_index_length = 0

n_total_observations class-attribute instance-attribute

n_total_observations = 0

target instance-attribute

target

target_dtype class-attribute instance-attribute

target_dtype = 'numeric'

target_stats class-attribute instance-attribute

target_stats = Field(default_factory=dict)

missing_target class-attribute instance-attribute

missing_target = Field(default_factory=dict)

date_column class-attribute instance-attribute

date_column = None

series_id_column class-attribute instance-attribute

series_id_column = None

index_type instance-attribute

index_type

frequency class-attribute instance-attribute

frequency = None

frequency_is_set class-attribute instance-attribute

frequency_is_set = False

index_is_monotonic class-attribute instance-attribute

index_is_monotonic = True

has_gaps class-attribute instance-attribute

has_gaps = False

has_duplicate_timestamps class-attribute instance-attribute

has_duplicate_timestamps = False

exog_columns class-attribute instance-attribute

exog_columns = Field(default_factory=list)

categorical_exog class-attribute instance-attribute

categorical_exog = Field(default_factory=list)

missing_exog class-attribute instance-attribute

missing_exog = Field(default_factory=dict)

data_path class-attribute instance-attribute

data_path = 'data.csv'

start_date class-attribute instance-attribute

start_date = None

warnings class-attribute instance-attribute

warnings = Field(default_factory=list)

Functions

_coerce_series_lengths classmethod

_coerce_series_lengths(value)

Coerce int values into SeriesLengthInfo(length=int).

Source code in skforecast_ai/schemas/profiles.py

@field_validator("series_lengths", mode="before")
@classmethod
def _coerce_series_lengths(cls, value: object) -> object:
    """Coerce `int` values into `SeriesLengthInfo(length=int)`."""
    if isinstance(value, dict):
        return {
            key: ({"length": v} if isinstance(v, int) else v)
            for key, v in value.items()
        }
    return value

_populate_observation_counts

_populate_observation_counts()

Derive span_index_length and n_total_observations.

Source code in skforecast_ai/schemas/profiles.py

@model_validator(mode="after")
def _populate_observation_counts(self) -> "DataProfile":
    """Derive `span_index_length` and `n_total_observations`."""
    if self.series_lengths:
        span, total = _resolve_observation_counts(
            self.series_lengths, self.frequency
        )
        self.span_index_length = span
        self.n_total_observations = total
    return self

SeriesPacf

Bases: BaseModel

PACF-significant lags for a single series.

Attributes:

Name	Type	Description
series_id	str	Name of the series (target column for single/wide, series id for long format).
n_observations	int	Number of non-NaN observations in the series (all NaNs, edge and interior, are excluded by the count). Used as the sample size for the PACF significance test. Not the raw column length.
lags	list of int	Significant lags retained by Benjamini-Hochberg FDR correction and the minimum effect-size floor, ordered by descending |PACF| (importance order, not ascending index).
pacf_abs	list of float	Absolute PACF magnitude aligned element-wise with lags (same order).

Attributes

series_id instance-attribute

series_id

n_observations instance-attribute

n_observations

lags class-attribute instance-attribute

lags = Field(default_factory=list)

pacf_abs class-attribute instance-attribute

pacf_abs = Field(default_factory=list)

ForecastingProfile

Bases: DisplayMixin, BaseModel

High-level profile of the forecasting problem.

Combines the dataset profile with the coarse modeling decisions: which forecaster family to use, which estimator to pair with it, and the alternative candidates the user could switch to. Detailed configuration (lags, metric, intervals, NaN handling, preprocessing) is left to ForecastPlan.

Attributes:

Name	Type	Description
data_profile	DataProfile	Profile of the input dataset (independent of the forecasting decisions).
task_type	str	Forecasting task category implied by the selected forecaster. One of 'single_series', 'multi_series', 'multivariate', 'statistical', 'foundation'.
forecaster	str	Selected skforecast forecaster class name.
forecaster_candidates	list	Ordered list of compatible forecaster class names. The first item is the preferred default.
estimator	str, default None	Selected scikit-learn compatible estimator name. None for forecaster families that do not use an external estimator (statistical, foundation).
estimator_candidates	list	Ordered list of compatible estimator names. Empty when the selected forecaster does not use an external estimator.
series_pacf	list of SeriesPacf	Per-series PACF-significant lags (the forecaster-invariant lag primitive). Empty for statistical and foundation tasks. The final lag set is derived in plan() by aggregating these primitives for the chosen forecaster.
window_features	list of dict, default None	Window feature configurations (dicts with keys 'stats' and 'window_size'). Computed eagerly at profile time as they are forecaster-invariant. None when the series is too short or the task is statistical/foundation.
calendar_features	list of str, default None	Recommended calendar feature names (a subset of those supported by skforecast.preprocessing.CalendarFeatures). Computed eagerly at profile time as they depend only on the index frequency and series length. None when the frequency is unknown, the series is too short, the frequency has no sub-period seasonality, or the task is statistical/foundation. The encoding is chosen later in plan() based on the resolved estimator.
explanation	str	Human-readable explanation of why this forecaster + estimator combination was chosen.

Attributes

data_profile instance-attribute

data_profile

task_type instance-attribute

task_type

forecaster instance-attribute

forecaster

forecaster_candidates class-attribute instance-attribute

forecaster_candidates = Field(default_factory=list)

estimator class-attribute instance-attribute

estimator = None

estimator_candidates class-attribute instance-attribute

estimator_candidates = Field(default_factory=list)

series_pacf class-attribute instance-attribute

series_pacf = Field(default_factory=list)

window_features class-attribute instance-attribute

window_features = None

calendar_features class-attribute instance-attribute

calendar_features = None

explanation instance-attribute

explanation

Functions

_rich_body

_rich_body(console, options)

Source code in skforecast_ai/schemas/profiles.py

def _rich_body(self, console, options):
    yield render_profile(self)

Functions

_resolve_observation_counts

_resolve_observation_counts(series_lengths, frequency)

Resolve the span index length and the total number of observations.

Merges the two quantities the assistant needs from the per-series ranges: the length of the union datetime index that spans every series (used for lag, window, and cross-validation sizing) and the pooled total number of observations (used for estimator sizing).

Parameters:

Name	Type	Description	Default
series_lengths	dict	Mapping of series name to its SeriesLengthInfo.	required
frequency	str	Inferred pandas frequency string. When None, or when datetime bounds are missing, the span falls back to the longest individual series.	None

Returns:

Name	Type	Description
span_index_length	int	Number of observations in the union index from the earliest start to the latest end at frequency.
n_total_observations	int	Sum of every series length.

Source code in skforecast_ai/schemas/profiles.py

def _resolve_observation_counts(
    series_lengths: dict[str, SeriesLengthInfo],
    frequency: str | None,
) -> tuple[int, int]:
    """
    Resolve the span index length and the total number of observations.

    Merges the two quantities the assistant needs from the per-series
    ranges: the length of the union datetime index that spans every
    series (used for lag, window, and cross-validation sizing) and the
    pooled total number of observations (used for estimator sizing).

    Parameters
    ----------
    series_lengths : dict
        Mapping of series name to its `SeriesLengthInfo`.
    frequency : str, default None
        Inferred pandas frequency string. When None, or when datetime
        bounds are missing, the span falls back to the longest individual
        series.

    Returns
    -------
    span_index_length : int
        Number of observations in the union index from the earliest start
        to the latest end at `frequency`.
    n_total_observations : int
        Sum of every series length.
    """
    infos = list(series_lengths.values())
    n_total_observations = sum(info.length for info in infos)

    starts = [info.start for info in infos if info.start is not None]
    ends = [info.end for info in infos if info.end is not None]
    if not starts or not ends or frequency is None:
        return max(info.length for info in infos), n_total_observations

    start = min(pd.Timestamp(s) for s in starts)
    end = max(pd.Timestamp(e) for e in ends)
    try:
        span_index_length = len(
            pd.date_range(start=start, end=end, freq=frequency)
        )
    except (ValueError, TypeError):
        span_index_length = max(info.length for info in infos)

    return span_index_length, n_total_observations