Queries#
Queries are used to transform, filter, and organize experiment runs in a functional and composable way.
They operate on lists of Run objects and return new a (grouped) query, preserving immutability.
Typical operations include filtering, sorting, grouping, aggregating, and computing derived values.
All queries are applied through the Query and GroupedQuery interfaces using a chainable syntax.
Tip
Queries can be reused and recombined without modifying the original data.
Query and Grouped Query#
- class ablate.queries.Query(runs)[source]#
Query interface for manipulating runs in a functional way.
All methods operate on a shallow copy of the runs in the query, so the original runs are not modified and assumed to be immutable.
- Parameters:
runs (
List[Run]) – List of runs to be queried.
- map(fn)[source]#
Apply a function to each run in the query.
This function is intended to be used for modifying the runs in the query. The function should return a new run object as the original run is not modified.
- sort(key, ascending=False)[source]#
Sort the runs in the query based on a metric.
- Parameters:
key (
AbstractMetric) – Metric to sort the runs by.ascending (
bool) – Whether to sort in ascending order. Defaults to False (descending order).
- Return type:
- Returns:
A new query with the runs sorted by the specified metric.
- project(selectors)[source]#
Project the parameter space of the runs in the query to a subset of parameters only including the specified selectors.
This function is intended to be used for reducing the dimensionality of the parameter space and therefore operates on a deep copy of the runs in the query.
- Parameters:
selectors (
Union[AbstractParam,List[AbstractParam]]) – Selector or list of selectors to project the runs by.- Return type:
- Returns:
A new query with the projected runs.
- groupby(selectors)[source]#
Group the runs in the query by one or more selectors.
- Parameters:
selectors (
Union[AbstractParam,List[AbstractParam]]) – Selector or list of selectors to group the runs by.- Return type:
- Returns:
A grouped query containing the grouped runs.
- groupdiff(selectors)[source]#
Group the runs in the query by one or more selectors, excluding the keys. This is similar to groupby but it excludes the specified keys from the grouping key.
- Parameters:
selectors (
Union[AbstractParam,List[AbstractParam]]) – Selector or list of selectors to exclude from the grouping key.- Return type:
- Returns:
A grouped query containing the grouped runs.
- head(n)[source]#
Get the first n runs in the query.
- Parameters:
n (
int) – Number of runs to return.- Return type:
- Returns:
A new query with the first n runs.
- tail(n)[source]#
Get the last n runs in the query.
- Parameters:
n (
int) – Number of runs to return.- Return type:
- Returns:
A new query with the last n runs.
- topk(metric, k)[source]#
Get the top k runs in the query based on a metric.
- Parameters:
metric (
AbstractMetric) – Metric to sort the runs by.k (
int) – Number of top runs to return.
- Return type:
- Returns:
A new query with the top k runs based on the specified metric.
- bottomk(metric, k)[source]#
Get the bottom k runs in the query based on a metric.
- Parameters:
metric (
AbstractMetric) – Metric to sort the runs by.k (
int) – Number of bottom runs to return.
- Return type:
- Returns:
A new query with the bottom k runs based on the specified metric.
- all()[source]#
Collect all runs in the query.
- Return type:
List[Run]- Returns:
A list of all runs in the query.
- class ablate.queries.GroupedQuery(groups)[source]#
Query interface for manipulating grouped runs in a functional way.
All methods operate on a shallow copy of the runs in the query, so the original runs are not modified and assumed to be immutable.
- Parameters:
groups (
List[GroupedRun]) – A list of grouped runs to be queried.
- filter(fn)[source]#
Filter the grouped runs in the grouped query based on a predicate function.
- Parameters:
fn (
Callable[[GroupedRun],bool]) – Predicate function that takes in a grouped run and returns a boolean value.- Return type:
- Returns:
A new grouped query with the grouped runs that satisfy the predicate function.
- map(fn)[source]#
Apply a function to each grouped run in the grouped query.
This function is intended to be used for modifying the grouped runs in the grouped query. The function should return a new grouped run object as the original grouped run is not modified.
- Parameters:
fn (
Callable[[GroupedRun],GroupedRun]) – Function that takes in a grouped run and returns a new grouped run object.- Return type:
- Returns:
A new grouped query with the modified grouped runs.
- sort(key, ascending=False)[source]#
Sort the runs inside each grouped run in the grouped query based on a metric.
- Parameters:
key (
AbstractMetric) – Metric to sort the grouped runs by.ascending (
bool) – Whether to sort in ascending order. Defaults to False (descending order).
- Return type:
- Returns:
A new grouped query with the grouped runs sorted by the specified metric.
- project(selectors)[source]#
Project the parameter space of the grouped runs in the grouped query to a subset of parameters only including the specified selectors.
This function is intended to be used for reducing the dimensionality of the parameter space and therefore operates on a deep copy of the grouped runs in the grouped query.
- Parameters:
selectors (
Union[AbstractParam,List[AbstractParam]]) – Selector or list of selectors to project the grouped runs by.- Return type:
- Returns:
A new grouped query with the projected grouped runs.
- head(n)[source]#
Get the first n runs inside each grouped run.
- Parameters:
n (
int) – Number of runs to return per group.- Return type:
- Returns:
A new query with the first n runs from each grouped run.
- tail(n)[source]#
Get the last n runs inside each grouped run.
- Parameters:
n (
int) – Number of runs to return per group.- Return type:
- Returns:
A new query with the last n runs from each grouped run.
- topk(metric, k)[source]#
Get the top k runs inside each grouped run based on a metric.
- Parameters:
metric (
AbstractMetric) – Metric to sort the runs by.k (
int) – Number of top runs to return per group.
- Return type:
- Returns:
A new query with the top k runs from each grouped run based on the specified metric.
- bottomk(metric, k)[source]#
Get the bottom k runs inside each grouped run based on a metric.
- Parameters:
metric (
AbstractMetric) – Metric to sort the runs by.k (
int) – Number of bottom runs to return per group.
- Return type:
- Returns:
A new query with the bottom k runs from each grouped run based on the specified metric.
- aggregate(method, over=None)[source]#
Aggregate each group of runs using a specified method.
- Supported methods include:
"first": Selects the first run from each group."last": Selects the last run from each group."best": Selects the run with the best value based on the given metric."worst": Selects the run with the worst value based on the given metric."mean": Computes the mean run across all runs in each group, including averaged metrics and temporal data, and collapsed metadata.
- Parameters:
method (
Literal['first','last','best','worst','mean']) – Aggregation strategy to apply per group.over (
Optional[AbstractMetric]) – The metric used for comparison when using “best” or “worst” methods. Has no effect for “first”, “last”, or “mean” methods. Defaults to None.
- Raises:
ValueError – If an unsupported aggregation method is provided or if the “best” or “worst” method is used without a specified metric.
- Return type:
- Returns:
A new query with the aggregated runs from each group.
- all()[source]#
Collect all runs in the grouped query by flattening the grouped runs.
- Return type:
List[Run]- Returns:
A list of all runs in the grouped query.
- copy()[source]#
Obtain a shallow copy of the grouped query.
- Return type:
- Returns:
A new grouped query with the same grouped runs as the original grouped query.
Query Selectors#
Query selectors are the building blocks for expressing transformations. Selectors can be used directly in queries to define filter conditions, sort keys, group keys, and aggregations.
- class ablate.queries.AbstractSelector(name, label=None)[source]#
Abstract class for selecting runs based on a specific attribute.
- Parameters:
name (
str) – Name of the attribute to select on.label (
Optional[str]) – Optional label for displaying purposes. If None, defaults to name. Defaults to None.
Parameter Selectors#
- class ablate.queries.AbstractParam(name, label=None)[source]#
Abstract class for selecting runs based on a specific attribute.
- Parameters:
name (
str) – Name of the attribute to select on.label (
Optional[str]) – Optional label for displaying purposes. If None, defaults to name. Defaults to None.
Metric Selectors#
- class ablate.queries.AbstractMetric(name, direction, label=None)[source]#
Abstract class for selecting runs based on a specific attribute.
- Parameters:
name (
str) – Name of the attribute to select on.label (
Optional[str]) – Optional label for displaying purposes. If None, defaults to name. Defaults to None.
- class ablate.queries.Metric(name, direction, label=None)[source]#
Abstract class for selecting runs based on a specific attribute.
- Parameters:
name (
str) – Name of the attribute to select on.label (
Optional[str]) – Optional label for displaying purposes. If None, defaults to name. Defaults to None.
- class ablate.queries.TemporalMetric(name, direction, reduction=None, label=None)[source]#
Selector for a specific temporal metric of the run.
- Parameters:
name (
str) – Name of the temporal metric to select on.direction (
Literal['min','max']) – Direction of the metric. “min” for minimization, “max” for maximization.reduction (
Optional[Literal['min','max','first','last']]) – Reduction method to apply to the temporal metric. “min” for minimum, “max” for maximum, “first” for the first value, and “last” for the last value. If None, the direction is used as the reduction. Defaults to None.label (
Optional[str]) – Optional label for displaying purposes. If None, defaults to name. Defaults to None.