exceptions

TemporalScope/src/temporalscope/core/exceptions.py

This module defines custom exceptions and warnings used throughout the TemporalScope package. These exceptions provide clear, actionable feedback for users during time-series forecasting workflows, particularly for DataFrame validation and time column handling through Narwhals.

CLASS	DESCRIPTION
DataFrameValidationError	Exception raised for DataFrame validation issues.
ModeValidationError	Exception raised when an invalid mode is specified.
TargetColumnWarning	Warning raised for potential issues with the target column.
TimeColumnError	Exception raised for validation issues with time_col.
TimeFrameError	Base class for exceptions in the TimeFrame module.

DataFrameValidationError

Exception raised for DataFrame validation issues.

This error is raised when DataFrame operations fail due to invalid data, schema mismatches, or other validation issues.

Examples:

try:
    # Validate numeric columns using Narwhals
    for col in feature_cols:
        df = df.select([nw.col(col).cast(nw.Float64()).alias(col)])
except Exception as e:
    raise DataFrameValidationError(f"Failed to validate numeric columns: {str(e)}")

ModeValidationError

ModeValidationError(mode, message='Invalid mode specified')

Exception raised when an invalid mode is specified.

PARAMETER	DESCRIPTION
mode	The invalid mode that caused the error. TYPE: str
message	TYPE: str DEFAULT: 'Invalid mode specified'

Examples:

if mode not in VALID_MODES:
    raise ModeValidationError(mode, f"Invalid mode: {mode}. Must be one of {VALID_MODES}.")

PARAMETER	DESCRIPTION
mode	The invalid mode that caused the error. TYPE: str
message	The error message to display. TYPE: str DEFAULT: 'Invalid mode specified'

ATTRIBUTE	DESCRIPTION
message
mode

Source code in src/temporalscope/core/exceptions.py

def __init__(self, mode, message="Invalid mode specified"):
    """Initialize ModeValidationError.

    Parameters
    ----------
    mode : str
        The invalid mode that caused the error.
    message : str
        The error message to display.
    """
    self.mode = mode
    self.message = f"{message}: {mode}"
    super().__init__(self.message)

message

message = f'{message}: {mode}'

mode

mode = mode

TargetColumnWarning

Warning raised for potential issues with the target column.

This warning is issued when the target column appears to contain sequential or vectorized data, which may require transformation depending on the selected mode (MODE_SINGLE_TARGET vs MODE_MULTI_TARGET).

Examples:

# Check if target column contains sequence data
if mode == MODE_MULTI_TARGET and df.select([nw.col(target_col).is_list()]).item():
    warnings.warn(
        "`target_col` appears to contain sequential data. Ensure it is transformed appropriately for MODE_MULTI_TARGET.",
        TargetColumnWarning,
    )

TimeColumnError

Exception raised for validation issues with time_col.

Examples:

# Validate time column type using Narwhals
if not (nw.col(time_col).cast(nw.Float64()).is_valid() or nw.col(time_col).cast(nw.Datetime()).is_valid()):
    raise TimeColumnError("`time_col` must be numeric or timestamp-like.")

TimeFrameError

Base class for exceptions in the TimeFrame module.

This serves as the foundation for all TimeFrame-related errors.