Module `futureexpert.make_forecast_consistent`

Contains the models with the configuration for the hierarchical reconciliation and the result format.

Functions

def export_consistent_forecasts_to_pandas(results: ConsistentForecastResult) ‑> pandas.core.frame.DataFrame

Expand source code

def export_consistent_forecasts_to_pandas(results: ConsistentForecastResult) -> pd.DataFrame:
    """Export consistent forecasts.

    Parameters:
    -----------
    results: futureexpert.make_forecast_consistent.ConsistentForecastResult
        Result after hierarchical reconciliation of forecasts.

    Returns:
    --------
    A DataFrame where each row represents the reconciled forecast information of a single timeseries of a certain date.
    return: pandas.core.frame.DataFrame

    """
    records = [
        {
            "name": reconciled_fc.ts_name,
            "time_stamp_utc": forecast_value.time_stamp_utc,
            "point_forecast_value": forecast_value.point_forecast_value,
        }
        for reconciled_fc in results.reconciled_forecasts
        for forecast_value in reconciled_fc.forecasts
    ]

    return pd.DataFrame(records)

Export consistent forecasts.

Parameters:

results: futureexpert.make_forecast_consistent.ConsistentForecastResult Result after hierarchical reconciliation of forecasts.

Returns:

A DataFrame where each row represents the reconciled forecast information of a single timeseries of a certain date. return: pandas.core.frame.DataFrame

Classes

class ActualsMetadata (**data: Any)

Expand source code

class ActualsMetadata(BaseModel):
    """Metadata about the actuals time series used for forecasting.

    Parameters
    ----------
    name: builtins.str
        Name of the time series
    grouping: builtins.dict[builtins.str, builtins.str]
        Hierarchical grouping information (empty dict for top level)
    """
    name: str
    grouping: dict[str, str] = Field(default_factory=dict)

Metadata about the actuals time series used for forecasting.

Parameters

name : builtins.str: Name of the time series
grouping : builtins.dict[builtins.str, builtins.str]: Hierarchical grouping information (empty dict for top level)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var grouping : dict[str, str]
var model_config
var name : str

class ConsistencyCheckResult (**data: Any)

Expand source code

class ConsistencyCheckResult(BaseModel):
    """Result of hierarchical consistency check between actuals and summing matrix expectations.

    Parameters
    ----------
    total_aggregate_series: builtins.int
        Total number of aggregate series checked for consistency
    inconsistent_series_count: builtins.int
        Number of series with at least one inconsistent data point
    consistency_rate: builtins.float
        Percentage of series that are fully consistent (0-100)
    overall_mape: builtins.float
        Mean Absolute Percentage Error across all series and dates
    individual_series_inconsistencies: builtins.list[futureexpert.make_forecast_consistent.SeriesInconsistency]
        List of per-series inconsistency details
    summary_statistics: typing.Optional[futureexpert.make_forecast_consistent.ErrorSummaryStatistics]
        Statistical summary of percentage errors across all inconsistencies (optional if no errors)
    inconsistent_dates_ranked: builtins.dict[builtins.str, builtins.int]
        Dictionary mapping dates to count of inconsistent series, ordered by count descending
    """
    total_aggregate_series: int
    inconsistent_series_count: int
    consistency_rate: float
    overall_mape: float
    individual_series_inconsistencies: list[SeriesInconsistency]
    summary_statistics: Optional[ErrorSummaryStatistics] = None
    inconsistent_dates_ranked: dict[str, int]

Result of hierarchical consistency check between actuals and summing matrix expectations.

Parameters

total_aggregate_series : builtins.int: Total number of aggregate series checked for consistency
inconsistent_series_count : builtins.int: Number of series with at least one inconsistent data point
consistency_rate : builtins.float: Percentage of series that are fully consistent (0-100)
overall_mape : builtins.float: Mean Absolute Percentage Error across all series and dates
individual_series_inconsistencies : builtins.list[SeriesInconsistency]: List of per-series inconsistency details
summary_statistics : typing.Optional[ErrorSummaryStatistics]: Statistical summary of percentage errors across all inconsistencies (optional if no errors)
inconsistent_dates_ranked : builtins.dict[builtins.str, builtins.int]: Dictionary mapping dates to count of inconsistent series, ordered by count descending

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var consistency_rate : float
var inconsistent_dates_ranked : dict[str, int]
var inconsistent_series_count : int
var individual_series_inconsistencies : list[SeriesInconsistency]
var model_config
var overall_mape : float
var summary_statistics : ErrorSummaryStatistics | None
var total_aggregate_series : int

class ConsistentForecast (**data: Any)

Expand source code

class ConsistentForecast(BaseModel):
    """Reconciled consistent forecast for a single time series with nested original forecast.

    Parameters
    ----------
    ts_id: builtins.int
        Time series identifier
    ts_name: builtins.str
        Human-readable time series name
    original_forecast: futureexpert.make_forecast_consistent.OriginalForecast
        The original forecast before reconciliation
    forecasts: builtins.list[futureexpert.forecast.ForecastValue]
        List of reconciled forecast points with timestamps and values
    """
    ts_id: int
    ts_name: str
    original_forecast: OriginalForecast
    forecasts: list[ForecastValue]

Reconciled consistent forecast for a single time series with nested original forecast.

Parameters

ts_id : builtins.int: Time series identifier
ts_name : builtins.str: Human-readable time series name
original_forecast : OriginalForecast: The original forecast before reconciliation
forecasts : builtins.list[ForecastValue]: List of reconciled forecast points with timestamps and values

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var forecasts : list[ForecastValue]
var model_config
var original_forecast : OriginalForecast
var ts_id : int
var ts_name : str

class ConsistentForecastResult (**data: Any)

Expand source code

class ConsistentForecastResult(BaseModel):
    """Consistent forecasts with nested original forecasts.

    Each reconciled forecast contains its corresponding original forecast as a nested field,
    eliminating the need for separate parallel arrays.

    Parameters
    ----------
    reconciled_forecasts: builtins.list[futureexpert.make_forecast_consistent.ConsistentForecast]
        List of hierarchically consistent, reconciled forecasts
    reconciliation_method: futureexpert.make_forecast_consistent.ReconciliationMethod
        Method used (bottom_up, top_down, etc.)
    model_selection_strategy: typing.Literal['best_ranking_model']
        Strategy for selecting models from forecasts
    hierarchy_structure: futureexpert.make_forecast_consistent.HierarchyMetadata
        Information about the hierarchical structure
    filtering_summary: futureexpert.make_forecast_consistent.FilteringSummary
        Summary of any filtering applied to the input data
    period_summary: futureexpert.make_forecast_consistent.PeriodSummary
        Summary of period clipping applied to actuals and forecasts
    reconciliation_summary: futureexpert.make_forecast_consistent.ReconciliationSummary
        Summary of the reconciliation process
    validation_summary: futureexpert.make_forecast_consistent.ValidationResult
        Results of data validation checks
    consistency_check: futureexpert.make_forecast_consistent.ConsistencyCheckResult
        Results of hierarchical consistency analysis before reconciliation
    """

    reconciled_forecasts: list[ConsistentForecast]
    reconciliation_method: ReconciliationMethod
    model_selection_strategy: Literal['best_ranking_model']
    hierarchy_structure: HierarchyMetadata
    filtering_summary: FilteringSummary
    period_summary: PeriodSummary
    reconciliation_summary: ReconciliationSummary
    validation_summary: ValidationResult
    consistency_check: ConsistencyCheckResult

Consistent forecasts with nested original forecasts.

Each reconciled forecast contains its corresponding original forecast as a nested field, eliminating the need for separate parallel arrays.

Parameters

reconciled_forecasts : builtins.list[ConsistentForecast]: List of hierarchically consistent, reconciled forecasts
reconciliation_method : ReconciliationMethod: Method used (bottom_up, top_down, etc.)
model_selection_strategy : typing.Literal['best_ranking_model']: Strategy for selecting models from forecasts
hierarchy_structure : HierarchyMetadata: Information about the hierarchical structure
filtering_summary : FilteringSummary: Summary of any filtering applied to the input data
period_summary : PeriodSummary: Summary of period clipping applied to actuals and forecasts
reconciliation_summary : ReconciliationSummary: Summary of the reconciliation process
validation_summary : ValidationResult: Results of data validation checks
consistency_check : ConsistencyCheckResult: Results of hierarchical consistency analysis before reconciliation

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var consistency_check : ConsistencyCheckResult
var filtering_summary : FilteringSummary
var hierarchy_structure : HierarchyMetadata
var model_config
var model_selection_strategy : Literal['best_ranking_model']
var period_summary : PeriodSummary
var reconciled_forecasts : list[ConsistentForecast]
var reconciliation_method : ReconciliationMethod
var reconciliation_summary : ReconciliationSummary
var validation_summary : ValidationResult

class ErrorSummaryStatistics (**data: Any)

Expand source code

class ErrorSummaryStatistics(BaseModel):
    """Statistical summary of percentage errors.

    Parameters
    ----------
    min: builtins.float
        Minimum percentage error value
    max: builtins.float
        Maximum percentage error value
    mean: builtins.float
        Mean percentage error value
    median: builtins.float
        Median percentage error value
    """
    min: float = Field(ge=0.0, description='Minimum percentage error')
    max: float = Field(ge=0.0, description='Maximum percentage error')
    mean: float = Field(ge=0.0, description='Mean percentage error')
    median: float = Field(ge=0.0, description='Median percentage error')

Statistical summary of percentage errors.

Parameters

min : builtins.float: Minimum percentage error value
max : builtins.float: Maximum percentage error value
mean : builtins.float: Mean percentage error value
median : builtins.float: Median percentage error value

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var max : float
var mean : float
var median : float
var min : float
var model_config

class FilteringSummary (**data: Any)

Expand source code

class FilteringSummary(BaseModel):
    """Metadata about the filtering process applied to time series.

    Parameters
    ----------
    excluded_levels_applied: builtins.set[builtins.str]
        Set of hierarchy levels that were excluded in this filtering
    original_series_count: builtins.int
        Number of time series before filtering was applied
    filtered_series_count: builtins.int
        Total number of time series that were filtered out
    remaining_series_count: builtins.int
        Number of time series remaining after filtering
    filtered_ts_ids: builtins.list[builtins.int]
        List of time series IDs that were filtered out
    filtered_by_level_count: builtins.int
        Number of series filtered due to level exclusions
    filtering_applied: builtins.bool
        Whether any filtering was actually applied (True if any series were filtered)
    """
    excluded_levels_applied: set[str]
    original_series_count: int
    filtered_series_count: int
    remaining_series_count: int
    filtered_ts_ids: list[int]
    filtered_by_level_count: int
    filtering_applied: bool

Metadata about the filtering process applied to time series.

Parameters

excluded_levels_applied : builtins.set[builtins.str]: Set of hierarchy levels that were excluded in this filtering
original_series_count : builtins.int: Number of time series before filtering was applied
filtered_series_count : builtins.int: Total number of time series that were filtered out
remaining_series_count : builtins.int: Number of time series remaining after filtering
filtered_ts_ids : builtins.list[builtins.int]: List of time series IDs that were filtered out
filtered_by_level_count : builtins.int: Number of series filtered due to level exclusions
filtering_applied : builtins.bool: Whether any filtering was actually applied (True if any series were filtered)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var excluded_levels_applied : set[str]
var filtered_by_level_count : int
var filtered_series_count : int
var filtered_ts_ids : list[int]
var filtering_applied : bool
var model_config
var original_series_count : int
var remaining_series_count : int

class ForecastModel (**data: Any)

Expand source code

class ForecastModel(BaseModel):
    """Single forecasting model results.

    Parameters
    ----------
    model_name: typing.Optional[builtins.str]
        Name of the forecasting model used (e.g., 'ARIMA', 'ETS', etc.)
    status: futureexpert.forecast.ModelStatus
        Status of the forecast (Successful, Failed, etc.)
    forecasts: builtins.list[futureexpert.forecast.ForecastValue]
        List of forecast points with timestamps and values
    """
    model_name: Optional[str] = None
    status: ModelStatus
    forecasts: list[ForecastValue]

Single forecasting model results.

Parameters

model_name : typing.Optional[builtins.str]: Name of the forecasting model used (e.g., 'ARIMA', 'ETS', etc.)
status : ModelStatus: Status of the forecast (Successful, Failed, etc.)
forecasts : builtins.list[ForecastValue]: List of forecast points with timestamps and values

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var forecasts : list[ForecastValue]
var model_config
var model_name : str | None
var status : ModelStatus

class HierarchyMetadata (**data: Any)

Expand source code

class HierarchyMetadata(BaseModel):
    """Metadata about hierarchical structure.

    Parameters
    ----------
    total_levels: builtins.int
        Total number of hierarchy levels detected
    base_level: builtins.int
        Index of the base (leaf) level in the hierarchy
    top_level: builtins.int
        Index of the top (root) level in the hierarchy
    base_series_count: builtins.int
        Number of time series at the base level
    top_series_count: builtins.int
        Number of time series at the top level
    series_by_level: builtins.dict[builtins.int, builtins.list[builtins.dict[builtins.str, typing.Any]]]
        Dictionary mapping level indices to list of series metadata
    summing_matrix: typing.Optional[typing.Any]
        Optional summing matrix for reconciliation (if computed)
    tags: typing.Optional[builtins.dict[builtins.str, typing.Any]]
        Optional hierarchicalforecast package tags for series grouping
    """
    total_levels: int
    base_level: int
    top_level: int
    base_series_count: int
    top_series_count: int
    series_by_level: dict[int, list[dict[str, Any]]]
    summing_matrix: Optional[Any] = None
    tags: Optional[dict[str, Any]] = None

Metadata about hierarchical structure.

Parameters

total_levels : builtins.int: Total number of hierarchy levels detected
base_level : builtins.int: Index of the base (leaf) level in the hierarchy
top_level : builtins.int: Index of the top (root) level in the hierarchy
base_series_count : builtins.int: Number of time series at the base level
top_series_count : builtins.int: Number of time series at the top level
series_by_level : builtins.dict[builtins.int, builtins.list[builtins.dict[builtins.str, typing.Any]]]: Dictionary mapping level indices to list of series metadata
summing_matrix : typing.Optional[typing.Any]: Optional summing matrix for reconciliation (if computed)
tags : typing.Optional[builtins.dict[builtins.str, typing.Any]]: Optional hierarchicalforecast package tags for series grouping

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var base_level : int
var base_series_count : int
var model_config
var series_by_level : dict[int, list[dict[str, typing.Any]]]
var summing_matrix : Any | None
var tags : dict[str, typing.Any] | None
var top_level : int
var top_series_count : int
var total_levels : int

class MakeForecastConsistentConfiguration (**data: Any)

Expand source code

class MakeForecastConsistentConfiguration(BaseConfig):
    """Service configuration.

    Parameters
    ----------
    data_selection: futureexpert.make_forecast_consistent.MakeForecastConsistentDataSelection
        Configuration on the selection of time series and forecasts used for carrying out the reconciliation.
    report_note: builtins.str
        Note of the report.
    db_name: typing.Optional[builtins.str]
        Only accessible for internal use. Name of the database to use for storing the results.
    reconciliation: typing.Optional[futureexpert.make_forecast_consistent.ReconciliationConfig]
        Optional reconciliation configuration. If not provided, defaults will be used.
    """
    data_selection: MakeForecastConsistentDataSelection
    report_note: str
    db_name: Optional[str] = None
    reconciliation: Optional[ReconciliationConfig] = None

Service configuration.

Parameters

data_selection : MakeForecastConsistentDataSelection: Configuration on the selection of time series and forecasts used for carrying out the reconciliation.
report_note : builtins.str: Note of the report.
db_name : typing.Optional[builtins.str]: Only accessible for internal use. Name of the database to use for storing the results.
reconciliation : typing.Optional[ReconciliationConfig]: Optional reconciliation configuration. If not provided, defaults will be used.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

BaseConfig
pydantic.main.BaseModel

Class variables

var data_selection : MakeForecastConsistentDataSelection
var db_name : str | None
var model_config
var reconciliation : ReconciliationConfig | None
var report_note : str

class MakeForecastConsistentDataSelection (**data: Any)

Expand source code

class MakeForecastConsistentDataSelection(BaseConfig):
    """Forecast and time series selection for making forecast consistent.

    Parameters
    ----------
    version: builtins.str
        Time series version to be used.
    fc_report_id: builtins.int
        The identifier of the forecasting report to be used.
    """
    version: str
    fc_report_id: int

Forecast and time series selection for making forecast consistent.

Parameters

version : builtins.str: Time series version to be used.
fc_report_id : builtins.int: The identifier of the forecasting report to be used.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

BaseConfig
pydantic.main.BaseModel

Class variables

var fc_report_id : int
var model_config
var version : str

class OriginalForecast (**data: Any)

Expand source code

class OriginalForecast(BaseModel):
    """Original forecast result structure.

    This represents only the essential fields from the forecasting pipeline
    that are actually used during hierarchical reconciliation.

    Parameters
    ----------
    input: futureexpert.make_forecast_consistent.OriginalForecastInput
        Input metadata including actuals information
    models: builtins.list[futureexpert.make_forecast_consistent.ForecastModel]
        Non-empty list of model results (typically only first model is used)
    """
    input: OriginalForecastInput
    models: list[ForecastModel] = Field(min_length=1, description='Non-empty list of forecast models')

Original forecast result structure.

This represents only the essential fields from the forecasting pipeline that are actually used during hierarchical reconciliation.

Parameters

input : OriginalForecastInput: Input metadata including actuals information
models : builtins.list[ForecastModel]: Non-empty list of model results (typically only first model is used)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var input : OriginalForecastInput
var model_config
var models : list[ForecastModel]

class OriginalForecastInput (**data: Any)

Expand source code

class OriginalForecastInput(BaseModel):
    """Input metadata for consistent forecast generation.

    Parameters
    ----------
    actuals: futureexpert.make_forecast_consistent.ActualsMetadata
        Metadata about the actuals time series
    """
    actuals: ActualsMetadata

Input metadata for consistent forecast generation.

Parameters

actuals : ActualsMetadata: Metadata about the actuals time series

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var actuals : ActualsMetadata
var model_config

class PeriodSummary (**data: Any)

Expand source code

class PeriodSummary(BaseModel):
    """Metadata about period clipping applied to actuals and forecasts.

    Parameters
    ----------
    final_actuals_length: builtins.int
        Number of datapoints in actuals after clipping and alignment
    final_forecasts_length: builtins.int
        Number of datapoints in forecasts after clipping and alignment
    actuals_period_config: typing.Optional[builtins.int]
        Configured period length for actuals (None = no limit)
    forecasts_period_config: typing.Optional[builtins.int]
        Configured period length for forecasts (None = no limit)
    """
    final_actuals_length: int
    final_forecasts_length: int
    actuals_period_config: Optional[int] = None
    forecasts_period_config: Optional[int] = None

Metadata about period clipping applied to actuals and forecasts.

Parameters

final_actuals_length : builtins.int: Number of datapoints in actuals after clipping and alignment
final_forecasts_length : builtins.int: Number of datapoints in forecasts after clipping and alignment
actuals_period_config : typing.Optional[builtins.int]: Configured period length for actuals (None = no limit)
forecasts_period_config : typing.Optional[builtins.int]: Configured period length for forecasts (None = no limit)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var actuals_period_config : int | None
var final_actuals_length : int
var final_forecasts_length : int
var forecasts_period_config : int | None
var model_config

class ReconciliationConfig (**data: Any)

Expand source code

class ReconciliationConfig(BaseConfig):
    """Configuration for hierarchical reconciliation process.

    Parameters
    ----------
    method: futureexpert.make_forecast_consistent.ReconciliationMethod
        Primary reconciliation method to use
    fallback_methods: typing.list[futureexpert.make_forecast_consistent.ReconciliationMethod]
        List of fallback methods to try if primary method fails
    excluded_levels: typing.list[builtins.str]
        Set of hierarchy levels to exclude from reconciliation
    actuals_period_length: typing.Optional[builtins.int]
        Number of last datapoints from actuals to use for proportion calculation (None = all)
    forecast_period_length: typing.Optional[builtins.int]
        Number of datapoints from forecasts to use for proportion calculation (None = all)
    """
    method: ReconciliationMethod = ReconciliationMethod.BOTTOM_UP
    fallback_methods: List[ReconciliationMethod] = Field(default_factory=list)
    excluded_levels: List[str] = Field(default_factory=list)
    actuals_period_length: Optional[int] = None
    forecast_period_length: Optional[int] = None

Configuration for hierarchical reconciliation process.

Parameters

method : ReconciliationMethod: Primary reconciliation method to use
fallback_methods : typing.list[ReconciliationMethod]: List of fallback methods to try if primary method fails
excluded_levels : typing.list[builtins.str]: Set of hierarchy levels to exclude from reconciliation
actuals_period_length : typing.Optional[builtins.int]: Number of last datapoints from actuals to use for proportion calculation (None = all)
forecast_period_length : typing.Optional[builtins.int]: Number of datapoints from forecasts to use for proportion calculation (None = all)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

BaseConfig
pydantic.main.BaseModel

Class variables

var actuals_period_length : int | None
var excluded_levels : List[str]
var fallback_methods : List[ReconciliationMethod]
var forecast_period_length : int | None
var method : ReconciliationMethod
var model_config

class ReconciliationMethod (*args, **kwds)

Expand source code

class ReconciliationMethod(str, Enum):
    """Reconciliation methods for hierarchical forecasting."""
    BOTTOM_UP = "bottom_up"
    TOP_DOWN_PROPORTION_AVERAGES = "top_down_proportion_averages"
    TOP_DOWN_FORECAST_PROPORTION = "top_down_forecast_proportion"
    MIN_TRACE_WLS_STRUCT = "min_trace_wls_struct"

Reconciliation methods for hierarchical forecasting.

Ancestors

builtins.str
enum.Enum

Class variables

var BOTTOM_UP
var MIN_TRACE_WLS_STRUCT
var TOP_DOWN_FORECAST_PROPORTION
var TOP_DOWN_PROPORTION_AVERAGES

class ReconciliationSummary (**data: Any)

Expand source code

class ReconciliationSummary(BaseModel):
    """Comprehensive metadata about the reconciliation process.

    Parameters
    ----------
    method_used: futureexpert.make_forecast_consistent.ReconciliationMethod
        The reconciliation method that was actually used
    methods_attempted: builtins.list[futureexpert.make_forecast_consistent.ReconciliationMethod]
        List of all methods attempted (including failures)
    is_successful: builtins.bool
        Whether the reconciliation completed successfully
    total_series_reconciled: builtins.int
        Number of time series that were reconciled
    processing_time_seconds: builtins.float
        Total time taken for reconciliation in seconds
    error_message: typing.Optional[builtins.str]
        Error message if reconciliation failed
    quality_metrics: typing.Optional[builtins.dict[builtins.str, builtins.float]]
        Optional dictionary of reconciliation quality metrics
    """
    method_used: ReconciliationMethod
    methods_attempted: list[ReconciliationMethod]
    is_successful: bool
    total_series_reconciled: int
    processing_time_seconds: float
    error_message: Optional[str] = None
    quality_metrics: Optional[dict[str, float]] = None

Comprehensive metadata about the reconciliation process.

Parameters

method_used : ReconciliationMethod: The reconciliation method that was actually used
methods_attempted : builtins.list[ReconciliationMethod]: List of all methods attempted (including failures)
is_successful : builtins.bool: Whether the reconciliation completed successfully
total_series_reconciled : builtins.int: Number of time series that were reconciled
processing_time_seconds : builtins.float: Total time taken for reconciliation in seconds
error_message : typing.Optional[builtins.str]: Error message if reconciliation failed
quality_metrics : typing.Optional[builtins.dict[builtins.str, builtins.float]]: Optional dictionary of reconciliation quality metrics

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var error_message : str | None
var is_successful : bool
var method_used : ReconciliationMethod
var methods_attempted : list[ReconciliationMethod]
var model_config
var processing_time_seconds : float
var quality_metrics : dict[str, float] | None
var total_series_reconciled : int

class SeriesInconsistency (**data: Any)

Expand source code

class SeriesInconsistency(BaseModel):
    """Individual time series inconsistency details for hierarchical consistency checking.

    Parameters
    ----------
    ts_id: builtins.str
        Time series identifier
    ts_name: builtins.str
        Human-readable time series name
    total_datapoints: builtins.int
        Total number of data points in the time series
    inconsistent_datapoints: builtins.int
        Number of data points with inconsistencies
    consistency_rate: builtins.float
        Percentage of consistent data points (0-100)
    series_mape: builtins.float
        Mean Absolute Percentage Error for this specific series
    summary_statistics: typing.Optional[futureexpert.make_forecast_consistent.ErrorSummaryStatistics]
        Statistical summary of percentage errors (optional if no errors)
    contributing_base_series: builtins.list[builtins.str]
        List of base series IDs that should sum to this aggregate series
    """
    ts_id: str
    ts_name: str
    total_datapoints: int
    inconsistent_datapoints: int
    consistency_rate: float
    series_mape: float
    summary_statistics: Optional[ErrorSummaryStatistics] = None
    contributing_base_series: list[str]

Individual time series inconsistency details for hierarchical consistency checking.

Parameters

ts_id : builtins.str: Time series identifier
ts_name : builtins.str: Human-readable time series name
total_datapoints : builtins.int: Total number of data points in the time series
inconsistent_datapoints : builtins.int: Number of data points with inconsistencies
consistency_rate : builtins.float: Percentage of consistent data points (0-100)
series_mape : builtins.float: Mean Absolute Percentage Error for this specific series
summary_statistics : typing.Optional[ErrorSummaryStatistics]: Statistical summary of percentage errors (optional if no errors)
contributing_base_series : builtins.list[builtins.str]: List of base series IDs that should sum to this aggregate series

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var consistency_rate : float
var contributing_base_series : list[str]
var inconsistent_datapoints : int
var model_config
var series_mape : float
var summary_statistics : ErrorSummaryStatistics | None
var total_datapoints : int
var ts_id : str
var ts_name : str

class ValidationResult (**data: Any)

Expand source code

class ValidationResult(BaseModel):
    """Result of data validation for hierarchical forecasting.

    Parameters
    ----------
    is_valid: builtins.bool
        Whether the data passes all validation checks
    errors: builtins.list[builtins.str]
        List of validation errors that prevent processing
    warnings: builtins.list[builtins.str]
        List of validation warnings that may affect quality
    """
    is_valid: bool
    errors: list[str]
    warnings: list[str]

Result of data validation for hierarchical forecasting.

Parameters

is_valid : builtins.bool: Whether the data passes all validation checks
errors : builtins.list[builtins.str]: List of validation errors that prevent processing
warnings : builtins.list[builtins.str]: List of validation warnings that may affect quality

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Ancestors

pydantic.main.BaseModel

Class variables

var errors : list[str]
var is_valid : bool
var model_config
var warnings : list[str]