Skip to main content

​
SingleEvalSamplePayload

class SingleEvalSamplePayload(BaseModel):
    sample_id: Any
    history_timestamps: List[str]
    history_values: List[Optional[float]]
    target_timestamps: List[str]
    target_values: List[Optional[float]]
    forecast: bool = True
    metadata: bool = False
    leak_target: bool = False
    column_name: Optional[str] = None

​
Parameters

​
sample_id

Type: Any Unique identifier for the sample. Can be any hashable type. This will become a column in the output dataframe.

​
history_timestamps

Type: List[str] List of timestamp strings for historical data points. Must be in ISO format or compatible with pandas datetime parsing.

​
history_values

Type: List[Optional[float]] List of historical values corresponding to history_timestamps. None values represent missing data points.

​
target_timestamps

Type: List[str] List of timestamp strings for target (future) data points. Must be in ISO format or compatible with pandas datetime parsing.

​
target_values

Type: List[Optional[float]] List of target values corresponding to target_timestamps. None values represent missing data points.

​
forecast

Type: bool Default: True Whether this sample should be used for forecasting. If False, the sample is used for metadata only.

​
metadata

Type: bool Default: False Whether this sample contains metadata information. Metadata samples are not forecasted but provide context.

​
leak_target

Type: bool Default: False Whether this sample contains target leakage. Leakage samples should be excluded from training to prevent data leakage in model evaluation.

​
column_name

Type: str or None Default: None Name of the column this sample represents. Used for identification in multi-column datasets.

​
Raises

​
ValueError

  • If timestamps or values lists are empty
  • If history and target data have mismatched lengths
  • If values contain NaN that cannot be converted to None

​
Notes

  • All timestamp lists must be non-empty
  • NaN values in history_values and target_values are converted to None for JSON serialization compatibility
  • Each sample represents one time series column in a forecasting scenario
  • Samples with leak_target=True should be excluded from training data

​
Examples

​
Basic Forecast Sample

sample = SingleEvalSamplePayload(
    sample_id="sales",
    history_timestamps=["2023-01-01", "2023-01-02", "2023-01-03"],
    history_values=[100.0, 110.0, 120.0],
    target_timestamps=["2023-01-04", "2023-01-05"],
    target_values=[130.0, 140.0],
    forecast=True,
    metadata=False,
    leak_target=False,
    column_name="sales"
)

​
Metadata Sample with Missing Values

metadata_sample = SingleEvalSamplePayload(
    sample_id="temperature",
    history_timestamps=["2023-01-01", "2023-01-02", "2023-01-03"],
    history_values=[20.5, None, 22.1],  # Missing value on 2023-01-02
    target_timestamps=["2023-01-04", "2023-01-05"],
    target_values=[23.0, 24.5],
    forecast=False,
    metadata=True,
    leak_target=False,
    column_name="temperature"
)

​
Sample with Target Leakage

leak_sample = SingleEvalSamplePayload(
    sample_id="future_sales",
    history_timestamps=["2023-01-01", "2023-01-02"],
    history_values=[100.0, 110.0],
    target_timestamps=["2023-01-03", "2023-01-04"],
    target_values=[120.0, 130.0],
    forecast=True,
    metadata=False,
    leak_target=True,  # This sample has target leakage
    column_name="future_sales"
)

​
See Also