Scenarios¶

coleman.scenarios ¶

coleman.scenarios - Scenario Management for the Coleman Framework.

This module provides utilities for managing and processing different scenarios in the context of the Coleman framework. This includes virtual scenarios for commits, scenarios specific to HCS context, and scenarios that consider context information for each commit. The module also provides utilities to load dataset files for experimental evaluations.

Classes:

Name	Description
`VirtualScenario`	Basic virtual scenario to manipulate data for each commit.
`VirtualHCSScenario`	Extends VirtualScenario to handle HCS context.
`VirtualContextScenario`	Extends VirtualScenario to handle context information.
`ScenarioLoader`	Loader that reads a build dataset and yields scenarios.
`HCSScenarioLoader`	Extends ScenarioLoader to handle HCS scenarios.
`ContextScenarioLoader`	Extends ScenarioLoader to handle context scenarios.

Short Aliases

Scenario Alias for VirtualScenario. HCSScenario Alias for VirtualHCSScenario. ContextScenario Alias for VirtualContextScenario.

Backward-Compatible Names

IndustrialDatasetScenarioProvider Alias for ScenarioLoader. IndustrialDatasetHCSScenarioProvider Alias for HCSScenarioLoader. IndustrialDatasetContextScenarioProvider Alias for ContextScenarioLoader.

ContextScenarioLoader ¶

Bases: ScenarioLoader

Scenario loader for context-aware data.

Parameters:

Name	Type	Description	Default
`tcfile`	`str`	Path to the test case file.	required
`feature_group_name`	`str`	Name of the feature group.	required
`feature_group_values`	`list of str`	List of features.	required
`previous_build`	`list of str`	List of features from the previous build.	required
`sched_time_ratio`	`float`	Ratio of the total build time to be used for scheduling. Default is 0.5.	`0.5`

Attributes:

Name	Type	Description
`feature_group`	`str`	The feature group name.
`features`	`list of str`	List of feature column names.
`previous_build`	`list of str`	List of features from the previous build.

init ¶

__init__(
    tcfile,
    feature_group_name,
    feature_group_values,
    previous_build,
    sched_time_ratio=0.5,
    budget_mode=BudgetMode.RATIO,
    budget_value=None,
)

Initialize the context-aware scenario loader.

Parameters:

Name	Type	Description	Default
`tcfile`	`str`	Path to the test case file.	required
`feature_group_name`	`str`	Name of the feature group.	required
`feature_group_values`	`list of str`	List of features.	required
`previous_build`	`list of str`	List of features from the previous build.	required
`sched_time_ratio`	`float`	Ratio of the total build time to be used for scheduling. Default is 0.5.	`0.5`

next ¶

__next__()

Return the next contextual scenario.

str ¶

__str__()

Return the name of the scenario loader.

Returns:

Type	Description
`str`	The scenario loader name.

get ¶

get()

Get the next virtual context scenario.

Called by __next__. Separates data by builds and returns each successive build as a context scenario with feature data.

Returns:

Type	Description
`VirtualContextScenario or None`	The next context scenario, or None if no more builds remain.

HCSScenarioLoader ¶

Bases: ScenarioLoader

Scenario loader for HCS-specific data.

Extends the base scenario loader to support variant-specific data.

Parameters:

Name	Type	Description	Default
`tcfile`	`str`	Path to the test case dataset file.	required
`variantsfile`	`str`	Path to the variants dataset file.	required
`sched_time_ratio`	`float`	Ratio of scheduled time to total build time. Default is 0.5.	`0.5`

Attributes:

Name	Type	Description
`variants`	`DataFrame`	DataFrame containing variant data.

variants `property` ¶

variants

Legacy eager view of variants data.

init ¶

__init__(
    tcfile,
    variantsfile,
    sched_time_ratio=0.5,
    budget_mode=BudgetMode.RATIO,
    budget_value=None,
)

Initialize the HCSScenarioLoader.

Parameters:

Name	Type	Description	Default
`tcfile`	`str`	Path to the test case dataset file.	required
`variantsfile`	`str`	Path to the variants dataset file.	required
`sched_time_ratio`	`float`	Ratio of scheduled time to total build time. Default is 0.5.	`0.5`

next ¶

__next__()

Return the next HCS scenario.

get ¶

get()

Get the next virtual HCS scenario.

Called by __next__. Separates data by builds and returns each successive build as an HCS scenario with variant data.

Returns:

Type	Description
`VirtualHCSScenario or None`	The next HCS scenario, or None if no more builds remain.

get_all_variants ¶

get_all_variants()

Return all unique variant names as a list.

Returns:

Type	Description
`list of str`	List of unique variant names.

get_total_variants ¶

get_total_variants()

Return the number of unique variants.

Returns:

Type	Description
`int`	The number of unique variants.

ScenarioLoader ¶

Base class for scenario loaders that process test case data from dataset files.

Parameters:

Name	Type	Description	Default
`tcfile`	`str`	Path to the test case dataset file (Parquet preferred, CSV supported).	required
`sched_time_ratio`	`float`	Ratio of scheduled time to total build time. Default is 0.5.	`0.5`

Attributes:

Name	Type	Description
`name`	`str`	Name derived from the dataset directory.
`current_build`	`int`	The current build number being processed.
`total_build_duration`	`float`	The total duration of the current build.
`scenario`	`VirtualScenario or None`	The current virtual scenario.
`tcdf`	`DataFrame`	DataFrame containing test case data.
`max_builds`	`int`	The maximum number of builds in the dataset.

tcdf `property` ¶

tcdf

Legacy eager view of scenario data.

Returns:

Type	Description
`DataFrame`	Materialized DataFrame. Prefer lazy internal access for scalability.

init ¶

__init__(
    tcfile,
    sched_time_ratio=0.5,
    budget_mode=BudgetMode.RATIO,
    budget_value=None,
)

Initialize the ScenarioLoader.

Parameters:

Name	Type	Description	Default
`tcfile`	`str`	Path to the test case dataset file.	required
`sched_time_ratio`	`float`	Ratio of scheduled time to total build time. Default is 0.5.	`0.5`

iter ¶

__iter__()

Return the iterator for the scenario loader.

Returns:

Type	Description
`ScenarioLoader`	The iterator instance.

next ¶

__next__()

Return the next scenario.

Returns:

Type	Description
`VirtualScenario`	The next virtual scenario.

Raises:

Type	Description
`StopIteration`	If no more scenarios are available.

str ¶

__str__()

Return the name of the scenario loader.

Returns:

Type	Description
`str`	The scenario loader name.

compute_available_time ¶

compute_available_time(
    total_build_duration, testcase_count
)

Map generic budget to available time for this domain.

get ¶

get()

Get the next virtual scenario.

Called by __next__. Separates data by builds and returns each successive build as a scenario.

Returns:

Type	Description
`VirtualScenario or None`	The next scenario, or None if no more builds remain.

get_avail_time_ratio ¶

get_avail_time_ratio()

Return a legacy ratio view derived from budget settings.

This compatibility accessor is kept for integrations that still read a ratio-style budget, but the canonical representation is budget_mode + budget_value.

get_budget_mode ¶

get_budget_mode()

Return current budget mode.

get_budget_value ¶

get_budget_value()

Return configured budget value.

last_build ¶

last_build(build)

Set the last build number.

Parameters:

Name	Type	Description	Default
`build`	`int`	The build number to set.	required

VirtualContextScenario ¶

Bases: VirtualScenario

Extends VirtualScenario to include context-specific features for each commit.

Parameters:

Name	Type	Description	Default
`*args`		Positional arguments passed to `VirtualScenario`.	`()`
`feature_group`	`str`	The name of the feature group.	required
`features`	`list of str`	The feature names.	required
`context_features`	`DataFrame`	DataFrame containing context features.	required
`**kwargs`		Keyword arguments passed to `VirtualScenario`.	`{}`

Attributes:

Name	Type	Description
`feature_group`	`str`	The name of the feature group.
`features`	`list of str`	The feature names.
`context_features`	`DataFrame`	DataFrame containing context features.

init ¶

__init__(
    *args,
    feature_group,
    features,
    context_features,
    **kwargs,
)

Initialise the VirtualContextScenario.

Parameters:

Name	Type	Description	Default
`*args`		Positional arguments passed to `VirtualScenario`.	`()`
`feature_group`	`str`	The name of the feature group.	required
`features`	`list of str`	The feature names.	required
`context_features`	`DataFrame`	DataFrame containing context features.	required
`**kwargs`		Keyword arguments passed to `VirtualScenario`.	`{}`

get_context_features ¶

get_context_features()

Return the context features associated with the scenario.

Returns:

Type	Description
`DataFrame`	DataFrame containing context features.

get_feature_group ¶

get_feature_group()

Return the feature group.

Returns:

Type	Description
`str`	The feature group name.

get_features ¶

get_features()

Return the features associated with the scenario.

Returns:

Type	Description
`list of str`	The feature names.

VirtualHCSScenario ¶

Bases: VirtualScenario

Extends VirtualScenario to handle data in an HCS-specific context.

Parameters:

Name	Type	Description	Default
`*args`		Positional arguments passed to `VirtualScenario`.	`()`
`variants`	`DataFrame`	DataFrame containing variant information.	required
`**kwargs`		Keyword arguments passed to `VirtualScenario`.	`{}`

Attributes:

Name	Type	Description
`variants`	`DataFrame`	DataFrame containing variant information.

init ¶

__init__(*args, variants, **kwargs)

Initialize the VirtualHCSScenario.

Parameters:

Name	Type	Description	Default
`*args`		Positional arguments passed to `VirtualScenario`.	`()`
`variants`	`DataFrame`	DataFrame containing variant information.	required
`**kwargs`		Keyword arguments passed to `VirtualScenario`.	`{}`

get_variants ¶

get_variants()

Return the variants associated with the system.

Returns:

Type	Description
`DataFrame`	DataFrame containing variant information.

VirtualScenario ¶

Virtual scenario used to manipulate data for each commit.

Parameters:

Name	Type	Description	Default
`available_time`	`float`	The time available to execute tests.	required
`testcases`	`list of dict or polars.DataFrame`	The test cases for the scenario.	required
`build_id`	`int`	The build identifier.	required
`total_build_duration`	`float`	The total duration of the build.	required

Attributes:

Name	Type	Description
`available_time`	`float`	The time available to execute tests.
`build_id`	`int`	The build identifier.
`total_build_duration`	`float`	The total duration of the build.

testcases `property` `writable` ¶

testcases

Return the test cases as a list of dicts (legacy access).

init ¶

__init__(
    available_time,
    testcases,
    build_id,
    total_build_duration,
    budget_mode=BudgetMode.RATIO,
    budget_value=None,
)

Initialize the VirtualScenario.

Parameters:

Name	Type	Description	Default
`available_time`	`float`	The time available to execute tests.	required
`testcases`	`list of dict or polars.DataFrame`	The test cases for the scenario.	required
`build_id`	`int`	The build identifier.	required
`total_build_duration`	`float`	The total duration of the build.	required

get_available_time ¶

get_available_time()

Return the available time to execute the tests.

Returns:

Type	Description
`float`	The available time.

get_testcases ¶

get_testcases()

Return the test cases for the scenario.

Returns:

Type	Description
`list of dict`	The test cases.

get_testcases_df ¶

get_testcases_df()

Return the test cases as a Polars DataFrame.

Returns:

Type	Description
`DataFrame`	DataFrame containing test case data.

reset ¶

reset()

Reset the priorities for all test cases in the scenario.

Scenarios¶

coleman.scenarios ¶

ContextScenarioLoader ¶

__init__ ¶

__next__ ¶

__str__ ¶

get ¶

HCSScenarioLoader ¶

variants property ¶

__init__ ¶

__next__ ¶

get ¶

get_all_variants ¶

get_total_variants ¶

ScenarioLoader ¶

tcdf property ¶

__init__ ¶

__iter__ ¶

__next__ ¶

__str__ ¶

compute_available_time ¶

get ¶

get_avail_time_ratio ¶

get_budget_mode ¶

get_budget_value ¶

last_build ¶

VirtualContextScenario ¶

__init__ ¶

get_context_features ¶

get_feature_group ¶

get_features ¶

VirtualHCSScenario ¶

__init__ ¶

get_variants ¶

VirtualScenario ¶

testcases property writable ¶

__init__ ¶

get_available_time ¶

get_testcases ¶

get_testcases_df ¶

reset ¶

init ¶

next ¶

str ¶

variants `property` ¶

init ¶

next ¶

tcdf `property` ¶

init ¶

iter ¶

next ¶

str ¶

init ¶

init ¶

testcases `property` `writable` ¶

init ¶