Module futureexpert.forecast_consistency

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

Classes

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._forecast_consistency_metadata.SeriesInconsistency]
        List of per-series inconsistency details
    summary_statistics: typing.Optional[futureexpert._forecast_consistency_metadata.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[futureexpert._forecast_consistency_metadata.SeriesInconsistency]

List of per-series inconsistency details

summary_statistics : typing.Optional[futureexpert._forecast_consistency_metadata.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[futureexpert._forecast_consistency_metadata.SeriesInconsistency]

var model_config

var overall_mape : float

var summary_statistics : futureexpert._forecast_consistency_metadata.ErrorSummaryStatistics | None

var total_aggregate_series : int

class ConsistentForecastMetadata (**data: Any)

Expand source code

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

    Parameters
    ----------
    reconciliation_method: futureexpert._forecast_consistency_metadata.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._forecast_consistency_metadata.HierarchyMetadata
        Information about the hierarchical structure
    filtering_summary: futureexpert._forecast_consistency_metadata.FilteringSummary
        Summary of any filtering applied to the input data
    period_summary: futureexpert._forecast_consistency_metadata.PeriodSummary
        Summary of period clipping applied to actuals and forecasts
    reconciliation_summary: futureexpert._forecast_consistency_metadata.ReconciliationSummary
        Summary of the reconciliation process
    validation_summary: futureexpert._forecast_consistency_metadata.ValidationResult
        Results of data validation checks
    consistency_check: futureexpert._forecast_consistency_metadata.ConsistencyCheckResult
        Results of hierarchical consistency analysis before reconciliation
    """
    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

    model_config = ConfigDict(
        protected_namespaces=()  # ignore warnings about field names starting with 'model_'
    )

Consistent forecasts with nested original forecasts.

Parameters

reconciliation_method : futureexpert._forecast_consistency_metadata.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._forecast_consistency_metadata.HierarchyMetadata

Information about the hierarchical structure

filtering_summary : futureexpert._forecast_consistency_metadata.FilteringSummary

Summary of any filtering applied to the input data

period_summary : futureexpert._forecast_consistency_metadata.PeriodSummary

Summary of period clipping applied to actuals and forecasts

reconciliation_summary : futureexpert._forecast_consistency_metadata.ReconciliationSummary

Summary of the reconciliation process

validation_summary : futureexpert._forecast_consistency_metadata.ValidationResult

Results of data validation checks

consistency_check : futureexpert._forecast_consistency_metadata.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 : futureexpert._forecast_consistency_metadata.ConsistencyCheckResult

var filtering_summary : futureexpert._forecast_consistency_metadata.FilteringSummary

var hierarchy_structure : futureexpert._forecast_consistency_metadata.HierarchyMetadata

var model_config

var model_selection_strategy : Literal['best_ranking_model']

var period_summary : futureexpert._forecast_consistency_metadata.PeriodSummary

var reconciliation_method : futureexpert._forecast_consistency_metadata.ReconciliationMethod

var reconciliation_summary : futureexpert._forecast_consistency_metadata.ReconciliationSummary

var validation_summary : futureexpert._forecast_consistency_metadata.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 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.forecast_consistency.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.forecast_consistency.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.
    forecast_minimum_version: builtins.str
        Optional version ID of time series containing minimum forecast values.
        Forecast minimums must match time series via grouping columns, granularity.
        Dates must be within the forecasting horizon.
    forecast_minimum_version: typing.Optional[builtins.str]

    """
    version: str
    fc_report_id: int
    forecast_minimum_version: Optional[str] = None

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.

forecast_minimum_version : builtins.str

Optional version ID of time series containing minimum forecast values. Forecast minimums must match time series via grouping columns, granularity. Dates must be within the forecasting horizon.

forecast_minimum_version : typing.Optional[builtins.str]

 

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 forecast_minimum_version : str | None

var model_config

var version : str

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._forecast_consistency_metadata.ReconciliationMethod
        Primary reconciliation method to use
    fallback_methods: builtins.list[futureexpert._forecast_consistency_metadata.ReconciliationMethod]
        List of fallback methods to try if primary method fails
    excluded_levels: builtins.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)
    round_forecast_to_integer: builtins.bool
        If True, apply integer rounding constraint after reconciliation to ensure all
        forecast values are integers while preserving total sum and hierarchical consistency
    round_forecast_to_package_size: builtins.bool
        If True, apply package size rounding constraint after reconciliation to ensure all
        forecast values are multiples of time series specific package sizes.
        Cannot be combined with round_forecast_to_integer.
    enforce_forecast_minimum_constraint: builtins.bool
        If True, enforce forecast minimums from open orders or contractual obligations.
        Only available via client.start_making_forecast_consistent().
        Only available if round_forecast_to_package_size is active.
    """
    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
    round_forecast_to_integer: bool = False
    round_forecast_to_package_size: bool = False
    enforce_forecast_minimum_constraint: bool = False

    @model_validator(mode="after")
    def check_package_size_and_integer_rounding_exclusivity(self) -> ReconciliationConfig:
        """Validates that package size rounding and integer rounding cannot be used together.

    Parameters
    ----------
    return: futureexpert.forecast_consistency.ReconciliationConfig

    """
        if self.round_forecast_to_package_size and self.round_forecast_to_integer:
            raise ValueError(
                'round_forecast_to_package_size and round_forecast_to_integer cannot both be True. '
                'Package size rounding takes precedence and already enforces integer values.'
            )
        return self

    @model_validator(mode="after")
    def check_package_size_dependency(self) -> ReconciliationConfig:
        """Validates that package size rounding is active if minimum constraints are enforced.

    Parameters
    ----------
    return: futureexpert.forecast_consistency.ReconciliationConfig

    """
        if self.enforce_forecast_minimum_constraint and not self.round_forecast_to_package_size:
            raise ValueError(
                'enforce_forecast_minimum_constraint can only be True '
                'if round_forecast_to_package_size is also True.'
            )
        return self

Configuration for hierarchical reconciliation process.

Parameters

method : futureexpert._forecast_consistency_metadata.ReconciliationMethod

Primary reconciliation method to use

fallback_methods : builtins.list[futureexpert._forecast_consistency_metadata.ReconciliationMethod]

List of fallback methods to try if primary method fails

excluded_levels : builtins.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)

round_forecast_to_integer : builtins.bool

If True, apply integer rounding constraint after reconciliation to ensure all forecast values are integers while preserving total sum and hierarchical consistency

round_forecast_to_package_size : builtins.bool

If True, apply package size rounding constraint after reconciliation to ensure all forecast values are multiples of time series specific package sizes. Cannot be combined with round_forecast_to_integer.

enforce_forecast_minimum_constraint : builtins.bool

If True, enforce forecast minimums from open orders or contractual obligations. Only available via client.start_making_forecast_consistent(). Only available if round_forecast_to_package_size is active.

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 enforce_forecast_minimum_constraint : bool

var excluded_levels : list[str]

var fallback_methods : list[futureexpert._forecast_consistency_metadata.ReconciliationMethod]

var forecast_period_length : int | None

var method : futureexpert._forecast_consistency_metadata.ReconciliationMethod

var model_config

var round_forecast_to_integer : bool

var round_forecast_to_package_size : bool

Methods

def check_package_size_and_integer_rounding_exclusivity(self) ‑> ReconciliationConfig

Expand source code

@model_validator(mode="after")
def check_package_size_and_integer_rounding_exclusivity(self) -> ReconciliationConfig:
    """Validates that package size rounding and integer rounding cannot be used together.

Parameters
----------
return: futureexpert.forecast_consistency.ReconciliationConfig

"""
    if self.round_forecast_to_package_size and self.round_forecast_to_integer:
        raise ValueError(
            'round_forecast_to_package_size and round_forecast_to_integer cannot both be True. '
            'Package size rounding takes precedence and already enforces integer values.'
        )
    return self

Validates that package size rounding and integer rounding cannot be used together.

Parameters

return : ReconciliationConfig

 

def check_package_size_dependency(self) ‑> ReconciliationConfig

Expand source code

@model_validator(mode="after")
def check_package_size_dependency(self) -> ReconciliationConfig:
    """Validates that package size rounding is active if minimum constraints are enforced.

Parameters
----------
return: futureexpert.forecast_consistency.ReconciliationConfig

"""
    if self.enforce_forecast_minimum_constraint and not self.round_forecast_to_package_size:
        raise ValueError(
            'enforce_forecast_minimum_constraint can only be True '
            'if round_forecast_to_package_size is also True.'
        )
    return self

Validates that package size rounding is active if minimum constraints are enforced.

Parameters

return : ReconciliationConfig

 

class ReconciliationMethod (*args, **kwds)

Expand source code

class ReconciliationMethod(str, Enum):
    """Reconciliation methods for hierarchical forecasting."""

    BOTTOM_UP = 'bottom_up'
    """Sums forecasts from the base level of the hierarchy up to the top.

    Uses `hierarchicalforecast.methods.BottomUp`.
    """

    TOP_DOWN_PROPORTION_AVERAGES = 'top_down_proportion_averages'
    """Disaggregates the top-level forecast based on historical average proportions.

    Uses `hierarchicalforecast.methods.TopDown(method='proportion_averages')`.
    """

    TOP_DOWN_FORECAST_PROPORTION = 'top_down_forecast_proportion'
    """Disaggregates the top-level forecast based on the proportions of the base forecasts for each forecast step.

    Uses `hierarchicalforecast.methods.TopDown(method='forecast_proportions')`.
    """

    TOP_DOWN_AVERAGE_FORECAST_PROPORTION = 'top_down_average_forecast_proportion'
    """Disaggregates the top-level forecast based on the average proportions of the base forecasts over the horizon."""

    MIN_TRACE_WLS_STRUCT = 'min_trace_wls_struct'
    """Weights are based on the number of aggregated base series (Structural).

    Uses `hierarchicalforecast.methods.MinTrace(method='wls_struct')`.
    """

Reconciliation methods for hierarchical forecasting.

Ancestors

• builtins.str
• enum.Enum

Class variables

var BOTTOM_UP

Sums forecasts from the base level of the hierarchy up to the top.

Uses hierarchicalforecast.methods.BottomUp.

var MIN_TRACE_WLS_STRUCT

Weights are based on the number of aggregated base series (Structural).

Uses hierarchicalforecast.methods.MinTrace(method='wls_struct').

var TOP_DOWN_AVERAGE_FORECAST_PROPORTION

Disaggregates the top-level forecast based on the average proportions of the base forecasts over the horizon.

var TOP_DOWN_FORECAST_PROPORTION

Disaggregates the top-level forecast based on the proportions of the base forecasts for each forecast step.

Uses hierarchicalforecast.methods.TopDown(method='forecast_proportions').

var TOP_DOWN_PROPORTION_AVERAGES

Disaggregates the top-level forecast based on historical average proportions.

Uses hierarchicalforecast.methods.TopDown(method='proportion_averages').

class ReconciliationSummary (**data: Any)

Expand source code

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

    Parameters
    ----------
    method_used: futureexpert._forecast_consistency_metadata.ReconciliationMethod
        The reconciliation method that was actually used
    methods_attempted: builtins.list[futureexpert._forecast_consistency_metadata.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 : futureexpert._forecast_consistency_metadata.ReconciliationMethod

The reconciliation method that was actually used

methods_attempted : builtins.list[futureexpert._forecast_consistency_metadata.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 : futureexpert._forecast_consistency_metadata.ReconciliationMethod

var methods_attempted : list[futureexpert._forecast_consistency_metadata.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._forecast_consistency_metadata.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[futureexpert._forecast_consistency_metadata.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 : futureexpert._forecast_consistency_metadata.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]