Referencia de API

La superficie recomendada es deliberadamente chica. La mayoría de los workflows empiezan con WalkForwardPolicy, TrainHistoryPolicy o DriftMonitoringPolicy, y recién bajan a simulación explícita, planning o splitter cuando necesitan control de nivel más bajo.

Los inputs públicos pueden venir de pandas, numpy o polars. Cuando la fuente no es pandas, Jano la normaliza en el borde y mantiene la misma superficie de split y reporting.

Workflow principal

class jano.workflows.WalkForwardPolicy(time_col, *, partition, step, strategy='rolling', allow_partial=False, start_at=None, end_at=None, max_folds=None)

Recommended high-level entry point for production-like walk-forward evaluation.

Parameters:

• time_col (str | int | TemporalSemanticsSpec)

• partition (TemporalPartitionSpec)

• strategy (str)

• allow_partial (bool)

• start_at (object | None)

• end_at (object | None)

• max_folds (int | None)

plan(X, title=None)

Return the precomputed walk-forward geometry.

Parameters:

title (str | None)

Return type:

SimulationPlan

run(X, output_path=None, title=None)

Materialize the walk-forward simulation.

Parameters:

• output_path (str | None)

• title (str | None)

Return type:

SimulationResult

as_splitter()

Expose the underlying splitter for manual control.

Return type:

TemporalBacktestSplitter

property simulation: TemporalSimulation

Expose the underlying simulation object.

class jano.workflows.TrainHistoryPolicy(time_col, *, cutoff, train_sizes, test_size, gap_before_test=None)

Recommended entry point for fixed-test, growing-train history studies.

Parameters:

• time_col (str | int | TemporalSemanticsSpec)

• train_sizes (Sequence[object])

evaluate(X, *, model, target_col, feature_cols=None, metrics=None)

Evaluate all configured train-history variants against one fixed test slice.

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

Return type:

TrainGrowthResult

find_optimal_train_size(X, **kwargs)

Return the smallest train window that stays within tolerance of the best score.

Return type:

dict[str, object]

class jano.workflows.DriftMonitoringPolicy(time_col, *, cutoff, train_size, test_size, step, gap_before_test=None, max_windows=None)

Recommended entry point for fixed-train, moving-test decay monitoring.

Parameters:

• time_col (str | int | TemporalSemanticsSpec)

• max_windows (int | None)

evaluate(X, *, model, target_col, feature_cols=None, metrics=None)

Evaluate how performance evolves as the test window moves forward.

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

Return type:

PerformanceDecayResult

find_drift_onset(X, **kwargs)

Return the first test window whose performance crosses the chosen threshold.

Return type:

dict[str, object] | None

class jano.workflows.RollingTrainHistoryPolicy(time_col, *, partition, step, train_sizes, strategy='rolling', allow_partial=False, start_at=None, end_at=None, max_folds=None)

Run train-history optimization inside each outer walk-forward iteration.

This policy answers questions such as: how much training history is required on average if the optimal train window is allowed to vary over time?

Parameters:

• time_col (str | int | TemporalSemanticsSpec)

• partition (TemporalPartitionSpec)

• train_sizes (Sequence[object])

• strategy (str)

• allow_partial (bool)

• start_at (object | None)

• end_at (object | None)

• max_folds (int | None)

plan(X, title=None)

Return the outer walk-forward plan used by the composed policy.

Parameters:

title (str | None)

Return type:

SimulationPlan

evaluate(X, *, model, target_col, feature_cols=None, metrics=None, metric='rmse', tolerance=0.0, relative=True, title=None)

Choose an optimal train-history size for each outer walk-forward iteration.

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

• metric (str)

• tolerance (float)

• relative (bool)

• title (str | None)

Return type:

RollingTrainHistoryResult

class jano.workflows.RollingTrainHistoryResult(records, metric)

Per-iteration optimal training-history choices over a walk-forward plan.

Parameters:

• records (DataFrame)

• metric (str)

records: DataFrame

metric: str

to_frame()

Return one row per outer iteration with the chosen optimal train size.

Return type:

DataFrame

summary()

Return compact aggregate statistics for the chosen train windows.

Return type:

dict[str, object]

class jano.simulation.TemporalSimulation(time_col, partition, step, strategy='rolling', allow_partial=False, start_at=None, end_at=None, max_folds=None)

High-level interface for executing a complete temporal simulation.

Parameters:

• time_col (str | TemporalSemanticsSpec) – Either the name of the timeline column or a TemporalSemanticsSpec describing the timeline, ordering column and per-segment eligibility columns.

• partition (TemporalPartitionSpec) – High-level definition of the train/test or train/validation/test layout.

• step – Amount by which the simulation advances after each fold.

• strategy (str) – Simulation policy. Use "single", "rolling" or "expanding".

• allow_partial (bool) – Whether to keep the last fold when the final evaluation segment would otherwise run past the end of the dataset.

• start_at (object | None) – Optional lower bound for the simulation timeline. Rows strictly before this timestamp are excluded before folds are generated.

• end_at (object | None) – Optional upper bound for the simulation timeline. Rows strictly after this timestamp are excluded before folds are generated.

• max_folds (int | None) – Optional maximum number of folds to materialize.

property time_col

Return the timeline column configured for the simulation.

property partition

Return the validated partition configuration used by the simulation.

property temporal_semantics: TemporalSemanticsSpec

Return the temporal semantics used by the simulation.

as_splitter()

Return the underlying low-level splitter.

Return type:

TemporalBacktestSplitter

run(X, output_path=None, title=None)

Execute the configured simulation over X and materialize its folds.

Parameters:

• X (DataFrame) – Input dataset as pandas.DataFrame, numpy.ndarray or polars.DataFrame.

• output_path (str | Path | None) – Optional filesystem path where the rendered HTML report should be written.

• title (str | None) – Optional title used in the returned report outputs.

Returns:

A SimulationResult containing the materialized folds and their summary.

Return type:

SimulationResult

plan(X, title=None)

Precompute the simulation geometry before materializing any folds.

Parameters:

• X (DataFrame)

• title (str | None)

Return type:

SimulationPlan

class jano.simulation.SimulationResult(frame, splits, summary)

Materialized result of running a temporal simulation over a dataset.

Parameters:

• frame (DataFrame)

• splits (List[TimeSplit])

• summary (SimulationSummary)

frame

Source dataset used to build the simulation.

Type:

pandas.DataFrame

splits

Materialized fold objects.

Type:

List[jano.splits.TimeSplit]

summary

Structured report for the simulation.

Type:

jano.reporting.SimulationSummary

frame: DataFrame

splits: List[TimeSplit]

summary: SimulationSummary

property total_folds: int

Return the number of materialized folds.

property chart_data: SimulationChartData

Return plot-ready chart data for the simulation.

property html: str

Return the rendered HTML report.

to_frame()

Return fold-level simulation metadata as a pandas DataFrame.

Return type:

DataFrame

to_dict()

Return a serializable dictionary representation.

Return type:

dict[str, object]

write_html(path)

Write the rendered HTML report to disk.

Parameters:

path (str | Path)

Return type:

Path

iter_splits()

Iterate over materialized fold objects.

Return type:

Iterator[TimeSplit]

class jano.planning.SimulationPlan(partition_plan, title)

High-level simulation plan with helpers for reporting and materialization.

Parameters:

• partition_plan (PartitionPlan)

• title (str)

partition_plan: PartitionPlan

title: str

property total_folds: int

to_frame()

Return type:

DataFrame

select_iterations(iterations)

Parameters:

iterations (Sequence[int])

Return type:

SimulationPlan

select_from_iteration(iteration)

Parameters:

iteration (int)

Return type:

SimulationPlan

select_until_iteration(iteration)

Parameters:

iteration (int)

Return type:

SimulationPlan

exclude_windows(*, train=None, validation=None, test=None)

Parameters:

• train (Sequence[tuple[object, object]] | None)

• validation (Sequence[tuple[object, object]] | None)

• test (Sequence[tuple[object, object]] | None)

Return type:

SimulationPlan

materialize()

Return type:

SimulationResult

describe()

Return type:

SimulationSummary

write_html(path)

Parameters:

path (str | Path)

Return type:

Path

class jano.types.TemporalPartitionSpec(layout, train_size, test_size=None, validation_size=None, gap_before_train=None, gap_before_validation=None, gap_before_test=None, gap_after_test=None)

High-level description of a temporal partition layout.

Parameters:

• layout (str)

• train_size (str | int | float | Timedelta)

• test_size (str | int | float | Timedelta | None)

• validation_size (str | int | float | Timedelta | None)

• gap_before_train (str | int | float | Timedelta | None)

• gap_before_validation (str | int | float | Timedelta | None)

• gap_before_test (str | int | float | Timedelta | None)

• gap_after_test (str | int | float | Timedelta | None)

layout

Either train_test or train_val_test.

Type:

str

train_size

Size of the train segment.

Type:

str | int | float | pandas.Timedelta

test_size

Size of the test segment when present.

Type:

str | int | float | pandas.Timedelta | None

validation_size

Size of the validation segment when present.

Type:

str | int | float | pandas.Timedelta | None

gap_before_validation

Optional gap inserted before validation.

Type:

str | int | float | pandas.Timedelta | None

gap_before_test

Optional gap inserted before test.

Type:

str | int | float | pandas.Timedelta | None

layout: str

train_size: str | int | float | Timedelta

test_size: str | int | float | Timedelta | None = None

validation_size: str | int | float | Timedelta | None = None

gap_before_train: str | int | float | Timedelta | None = None

gap_before_validation: str | int | float | Timedelta | None = None

gap_before_test: str | int | float | Timedelta | None = None

gap_after_test: str | int | float | Timedelta | None = None

class jano.types.TemporalSemanticsSpec(timeline_col, order_col=None, segment_time_cols=<factory>)

Temporal semantics for ordering, reporting and segment eligibility.

Parameters:

• timeline_col (str | int)

• order_col (str | int | None)

• segment_time_cols (Mapping[str, str | int])

timeline_col

Column used to anchor the global simulation timeline and reports.

Type:

str | int

order_col

Optional column used to sort the dataset internally. Defaults to timeline_col.

Type:

str | int | None

segment_time_cols

Optional per-segment timestamp mapping. Use this when a segment should be sliced by a different temporal column than the global timeline. For example, train can be filtered by arrived_at while test stays anchored on departured_at.

Type:

Mapping[str, str | int]

timeline_col: str | int

order_col: str | int | None = None

segment_time_cols: Mapping[str, str | int]

property effective_order_col: str | int

Return the ordering column used by the engine.

column_for_segment(name)

Return the timestamp column used to assign rows to name.

Parameters:

name (str)

Return type:

str | int

class jano.types.FeatureLookbackSpec(default_lookback=None, group_lookbacks=<factory>, feature_groups=<factory>)

Lookback requirements for feature groups within the same fold.

Parameters:

• default_lookback (str | int | float | Timedelta | None)

• group_lookbacks (Mapping[str, str | int | float | Timedelta])

• feature_groups (Mapping[str, Sequence[str | int]])

default_lookback

Optional fallback lookback applied to features that do not belong to an explicit group.

Type:

str | int | float | pandas.Timedelta | None

group_lookbacks

Mapping from feature-group name to the temporal lookback needed to build that group.

Type:

Mapping[str, str | int | float | pandas.Timedelta]

feature_groups

Mapping from group name to the feature columns that belong to it.

Type:

Mapping[str, Sequence[str | int]]

All lookbacks must use duration-based sizes.

default_lookback: str | int | float | Timedelta | None = None

group_lookbacks: Mapping[str, str | int | float | Timedelta]

feature_groups: Mapping[str, Sequence[str | int]]

normalized_group_lookbacks()

Return validated duration lookbacks for each explicit feature group.

Return type:

dict[str, SizeSpec]

normalized_default_lookback()

Return the validated duration lookback for ungrouped features.

Return type:

SizeSpec | None

class jano.splitters.TemporalBacktestSplitter(time_col, partition, step, strategy='rolling', allow_partial=False)

Flexible temporal splitter for single or repeated temporal backtests.

Parameters:

• time_col (str | TemporalSemanticsSpec) – Either the name of the timeline column or a TemporalSemanticsSpec describing the timeline, ordering column and per-segment eligibility columns.

• partition (TemporalPartitionSpec) – High-level definition of the train/test or train/validation/test layout.

• step – Amount by which the simulation advances after each fold. It must use the same unit family as the partition sizes.

• strategy (str) – Simulation policy. Use "single" for one split, "rolling" for fixed-size windows or "expanding" for growing training history.

• allow_partial (bool) – Whether to keep the last fold when the final evaluation segment would otherwise run past the end of the dataset.

split(X, y=None, groups=None)

Yield each fold as a plain tuple of positional index arrays.

Parameters:

• X – Input dataset as pandas.DataFrame, numpy.ndarray or polars.DataFrame.

• y – Unused placeholder for scikit-learn compatibility.

• groups – Unused placeholder for scikit-learn compatibility.

Yields:

Tuples of NumPy arrays ordered by the configured segment names.

Return type:

Iterator[Tuple[ndarray, …]]

iter_splits(X, y=None, groups=None)

Yield rich TimeSplit objects for each fold in the simulation.

Parameters:

• X – Input dataset as pandas.DataFrame, numpy.ndarray or polars.DataFrame.

• y – Unused placeholder for scikit-learn compatibility.

• groups – Unused placeholder for scikit-learn compatibility.

Yields:

TimeSplit instances containing segment indices, boundaries and metadata.

Return type:

Iterator[TimeSplit]

get_n_splits(X=None, y=None, groups=None)

Return the number of valid folds generated for X.

Parameters:

• X – Input dataset as pandas.DataFrame, numpy.ndarray or polars.DataFrame.

• y – Unused placeholder for scikit-learn compatibility.

• groups – Unused placeholder for scikit-learn compatibility.

Returns:

Total number of folds that would be produced by iter_splits.

Return type:

int

plan(X)

Precompute the temporal geometry of the simulation without materializing slices.

Return type:

PartitionPlan

describe_simulation(X, output_path=None, title=None, output='summary')

Describe a simulation over a concrete dataset.

Parameters:

• X (DataFrame) – Input dataset as pandas.DataFrame, numpy.ndarray or polars.DataFrame.

• output_path (str | Path | None) – Optional filesystem path where the rendered HTML report should be written.

• title (str | None) – Optional title used in the returned report outputs.

• output (str) – Output mode. Use "summary" for SimulationSummary, "html" for a rendered HTML string or "chart_data" for plot-ready Python data.

Returns:

A SimulationSummary, raw HTML string or SimulationChartData depending on output.

Return type:

SimulationSummary | SimulationChartData | str

class jano.planning.PartitionPlan(frame, temporal_semantics, strategy, size_kind, folds)

Precomputed temporal plan that can be inspected and materialized later.

Parameters:

• frame (DataFrame)

• temporal_semantics (TemporalSemanticsSpec)

• strategy (str)

• size_kind (str)

• folds (List[PlannedFold])

frame: DataFrame

temporal_semantics: TemporalSemanticsSpec

strategy: str

size_kind: str

folds: List[PlannedFold]

property total_folds: int

property time_col

to_frame()

Return type:

DataFrame

select_iterations(iterations)

Parameters:

iterations (Sequence[int])

Return type:

PartitionPlan

select_from_iteration(iteration)

Parameters:

iteration (int)

Return type:

PartitionPlan

select_until_iteration(iteration)

Parameters:

iteration (int)

Return type:

PartitionPlan

exclude_windows(*, train=None, validation=None, test=None)

Parameters:

• train (Sequence[tuple[object, object]] | None)

• validation (Sequence[tuple[object, object]] | None)

• test (Sequence[tuple[object, object]] | None)

Return type:

PartitionPlan

materialize()

Return type:

list[TimeSplit]

iter_splits()

Return type:

Iterator[TimeSplit]

class jano.planning.PlannedFold(iteration, boundaries, counts, metadata=<factory>)

Precomputed temporal geometry for one simulation iteration.

Parameters:

• iteration (int)

• boundaries (Dict[str, SegmentBoundaries])

• counts (Dict[str, int])

• metadata (Dict[str, object])

iteration: int

boundaries: Dict[str, SegmentBoundaries]

counts: Dict[str, int]

metadata: Dict[str, object]

property fold: int

property is_partial: bool

property simulation_start: Timestamp

property simulation_end: Timestamp

to_dict()

Return type:

dict[str, object]

Policies temporales

class jano.policies.TrainGrowthPolicy(time_col, *, cutoff, train_sizes, test_size, gap_before_test=None)

Evaluate whether adding more training history improves a fixed test slice.

This policy keeps the test window fixed and grows the train window backward in time. It is useful when you want to understand how much historical data is actually needed to match the best achievable test performance.

Parameters:

• time_col (str | int | TemporalSemanticsSpec)

• train_sizes (Sequence[object])

evaluate(X, *, model, target_col, feature_cols=None, metrics=None)

Run the fixed-test evaluation over all configured train sizes.

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

Return type:

TrainGrowthResult

find_optimal_train_size(X, *, model, target_col, feature_cols=None, metrics=None, metric='rmse', tolerance=0.0, relative=True)

Convenience wrapper around evaluate(...).find_optimal_train_size(...).

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

• metric (str)

• tolerance (float)

• relative (bool)

Return type:

dict[str, object]

class jano.policies.TrainGrowthResult(records, metric_directions)

Evaluated records for a fixed-test, growing-train temporal hypothesis.

Parameters:

• records (DataFrame)

• metric_directions (dict[str, str])

records: DataFrame

metric_directions: dict[str, str]

to_frame()

Return the evaluated train variants as a pandas DataFrame.

Return type:

DataFrame

find_optimal_train_size(metric='rmse', tolerance=0.0, relative=True)

Return the smallest train window whose score is within tolerance of the best.

Parameters:

• metric (str) – Metric column used to compare train variants.

• tolerance (float) – Allowed distance from the best score.

• relative (bool) – Whether tolerance is interpreted proportionally instead of absolutely.

Return type:

dict[str, object]

class jano.policies.PerformanceDecayPolicy(time_col, *, cutoff, train_size, test_size, step, gap_before_test=None, max_windows=None)

Evaluate how long a fixed train window stays useful as test moves forward.

This policy keeps train fixed and repeatedly shifts the test window into the future. It is useful when you want to estimate when performance decay or drift becomes operationally relevant without retraining the model at every step.

Parameters:

• time_col (str | int | TemporalSemanticsSpec)

• max_windows (int | None)

evaluate(X, *, model, target_col, feature_cols=None, metrics=None)

Run the fixed-train evaluation over moving test windows.

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

Return type:

PerformanceDecayResult

find_drift_onset(X, *, model, target_col, feature_cols=None, metrics=None, metric='rmse', threshold=0.1, baseline='first', relative=True)

Convenience wrapper around evaluate(...).find_drift_onset(...).

Parameters:

• target_col (str | int)

• feature_cols (Sequence[str | int] | None)

• metrics (str | Sequence[str] | Mapping[str, Callable[[ndarray, ndarray], float]] | None)

• metric (str)

• threshold (float)

• baseline (str | float)

• relative (bool)

Return type:

dict[str, object] | None

class jano.policies.PerformanceDecayResult(records, metric_directions)

Evaluated records for a fixed-train, moving-test temporal hypothesis.

Parameters:

• records (DataFrame)

• metric_directions (dict[str, str])

records: DataFrame

metric_directions: dict[str, str]

to_frame()

Return the evaluated test windows as a pandas DataFrame.

Return type:

DataFrame

find_drift_onset(metric='rmse', threshold=0.1, baseline='first', relative=True)

Return the first evaluation window where performance becomes problematic.

Parameters:

• metric (str) – Metric column used to detect degradation.

• threshold (float) – Allowed degradation from the baseline before the window is flagged.

• baseline (str | float) – "first", "best" or an explicit numeric baseline.

• relative (bool) – Whether threshold is interpreted proportionally instead of absolutely.

Return type:

dict[str, object] | None

Objetos de fold

class jano.splits.TimeSplit(fold, segments, boundaries, metadata=<factory>)

A single temporal partition with named segments and metadata.

Parameters:

• fold (int)

• segments (Dict[str, ndarray])

• boundaries (Dict[str, SegmentBoundaries])

• metadata (Dict[str, object])

fold

Zero-based fold number.

Type:

int

segments

Mapping from segment name to positional NumPy indices.

Type:

Dict[str, numpy.ndarray]

boundaries

Mapping from segment name to temporal boundaries.

Type:

Dict[str, jano.types.SegmentBoundaries]

metadata

Additional metadata such as strategy or size kind.

Type:

Dict[str, object]

fold: int

segments: Dict[str, ndarray]

boundaries: Dict[str, SegmentBoundaries]

metadata: Dict[str, object]

slice(X)

Slice a DataFrame into segment-specific DataFrames.

Parameters:

X (DataFrame)

Return type:

Dict[str, DataFrame]

slice_xy(X, y)

Slice features and target into segment-specific objects.

Parameters:

• X (DataFrame)

• y (Series)

Return type:

Dict[str, DataFrame | Series]

summary()

Return a serializable summary of the fold and its segments.

Return type:

Dict[str, object]

feature_history_bounds(lookbacks, *, segment_name='train')

Return per-group historical windows needed to build feature groups.

The returned windows end at the start of segment_name and extend backward according to each configured feature-group lookback.

Parameters:

• lookbacks (FeatureLookbackSpec)

• segment_name (str)

Return type:

Dict[str, SegmentBoundaries]

slice_feature_history(X, lookbacks, *, time_col, segment_name='train')

Slice historical context windows needed by feature groups.

This helper is useful when the fold itself is fixed, but different feature groups need different amounts of past data to be engineered.

Parameters:

• X (DataFrame)

• lookbacks (FeatureLookbackSpec)

• time_col (str)

• segment_name (str)

Return type:

Dict[str, DataFrame]

Objetos de reporting

class jano.reporting.SimulationSummary(title, time_col, dataset_start, dataset_end, total_rows, total_folds, strategy, size_kind, folds, segment_order, chart_data, html)

Structured description of a temporal simulation over a dataset.

Parameters:

• title (str)

• time_col (str)

• dataset_start (Timestamp)

• dataset_end (Timestamp)

• total_rows (int)

• total_folds (int)

• strategy (str)

• size_kind (str)

• folds (List[Dict[str, object]])

• segment_order (List[str])

• chart_data (SimulationChartData)

• html (str)

title

Report title.

Type:

str

time_col

Name of the timestamp column used in the dataset.

Type:

str

dataset_start

Earliest timestamp present in the dataset.

Type:

pandas.Timestamp

dataset_end

Latest timestamp present in the dataset.

Type:

pandas.Timestamp

total_rows

Number of rows in the source dataset.

Type:

int

total_folds

Number of simulated folds.

Type:

int

strategy

Split strategy used to build the simulation.

Type:

str

size_kind

Unit family used by the partition sizes.

Type:

str

folds

Fold-by-fold segment metadata.

Type:

List[Dict[str, object]]

segment_order

Ordered list of segment names.

Type:

List[str]

chart_data

Plot-ready representation of the same simulation.

Type:

jano.reporting.SimulationChartData

html

Rendered HTML report.

Type:

str

title: str

time_col: str

dataset_start: Timestamp

dataset_end: Timestamp

total_rows: int

total_folds: int

strategy: str

size_kind: str

folds: List[Dict[str, object]]

segment_order: List[str]

chart_data: SimulationChartData

html: str

to_dict()

Return a serializable dictionary representation.

Return type:

Dict[str, object]

to_frame()

Convert fold summaries into a tabular pandas DataFrame.

Return type:

DataFrame

write_html(path)

Write the rendered HTML report to path.

Parameters:

path (str | Path)

Return type:

Path

class jano.reporting.SimulationChartData(title, time_col, dataset_start, dataset_end, total_rows, total_folds, strategy, size_kind, segment_order, segment_colors, segment_stats, folds)

Plot-ready description of a temporal simulation timeline.

Parameters:

• title (str)

• time_col (str)

• dataset_start (Timestamp)

• dataset_end (Timestamp)

• total_rows (int)

• total_folds (int)

• strategy (str)

• size_kind (str)

• segment_order (List[str])

• segment_colors (Dict[str, str])

• segment_stats (Dict[str, Dict[str, object]])

• folds (List[Dict[str, object]])

title

Report title.

Type:

str

time_col

Name of the timestamp column used in the dataset.

Type:

str

dataset_start

Earliest timestamp present in the dataset.

Type:

pandas.Timestamp

dataset_end

Latest timestamp present in the dataset.

Type:

pandas.Timestamp

total_rows

Number of rows in the source dataset.

Type:

int

total_folds

Number of simulated folds.

Type:

int

strategy

Split strategy used to build the simulation.

Type:

str

size_kind

Unit family used by the partition sizes.

Type:

str

segment_order

Ordered list of segment names.

Type:

List[str]

segment_colors

Color associated with each segment.

Type:

Dict[str, str]

segment_stats

Aggregate per-segment row statistics across folds.

Type:

Dict[str, Dict[str, object]]

folds

Fold-level timeline payload ready for plotting.

Type:

List[Dict[str, object]]

title: str

time_col: str

dataset_start: Timestamp

dataset_end: Timestamp

total_rows: int

total_folds: int

strategy: str

size_kind: str

segment_order: List[str]

segment_colors: Dict[str, str]

segment_stats: Dict[str, Dict[str, object]]

folds: List[Dict[str, object]]

to_dict()

Return a serializable dictionary representation.

Return type:

Dict[str, object]

Helpers de tipos y validación

class jano.types.SizeSpec(value, kind)

Normalized specification for segment sizes.

Parameters:

• value (Timedelta | int | float)

• kind (str)

value

Parsed size value as Timedelta, integer row count or fraction.

Type:

pandas.Timedelta | int | float

kind

Unit family for the value: duration, rows or fraction.

Type:

str

value: Timedelta | int | float

kind: str

classmethod from_value(value)

Normalize a raw size value into a typed SizeSpec.

Parameters:

value (str | int | float | Timedelta)

Return type:

SizeSpec

class jano.types.SegmentBoundaries(start, end)

Closed-open boundaries for a named temporal segment.

Parameters:

• start (Timestamp)

• end (Timestamp)

start: Timestamp

end: Timestamp

class jano.validation.ValidatedPartitionSpec(layout, segments, gaps, tail_gap, size_kind)

Partition specification after normalization.

Parameters:

• layout (str)

• segments (Dict[str, SizeSpec])

• gaps (Dict[str, SizeSpec])

• tail_gap (SizeSpec | None)

• size_kind (str)

layout: str

segments: Dict[str, SizeSpec]

gaps: Dict[str, SizeSpec]

tail_gap: SizeSpec | None

size_kind: str

jano.validation.validate_strategy(strategy)

Validate and normalize a split strategy name.

Parameters:

strategy (str)

Return type:

str

jano.validation.validate_partition_spec(partition)

Validate a high-level partition spec and normalize its sizes.

Parameters:

partition (TemporalPartitionSpec)

Return type:

ValidatedPartitionSpec