Analyzing Experiment Results
This tutorial demonstrates how to use HydraFlow's powerful analysis capabilities to work with your experiment results.
Prerequisites
Before you begin this tutorial, you should:
- Understand the basic structure of a HydraFlow application (from the Basic Application tutorial)
- Be familiar with the concept of job definitions (from the Automated Workflows tutorial)
Project Setup
We'll start by running several experiments that we can analyze. We'll execute the three jobs defined in the Automated Workflows tutorial:
$ hydraflow run job_sequential
$ hydraflow run job_parallel
$ hydraflow run job_submit
2025/07/27 00:14:44 INFO mlflow.tracking.fluent: Experiment with name 'job_sequential' does not exist. Creating a new experiment.
[2025-07-27 00:14:46,307][HYDRA] Launching 3 jobs locally
[2025-07-27 00:14:46,307][HYDRA] #0 : width=100 height=100
[2025-07-27 00:14:46,432][__main__][INFO] - 1d3e153ebff14fe889fc99b4bf9ff37c
[2025-07-27 00:14:46,432][__main__][INFO] - {'width': 100, 'height': 100}
[2025-07-27 00:14:46,435][HYDRA] #1 : width=100 height=200
[2025-07-27 00:14:46,519][__main__][INFO] - f17a2b5938734bcfbfea71207e2667c7
[2025-07-27 00:14:46,519][__main__][INFO] - {'width': 100, 'height': 200}
[2025-07-27 00:14:46,521][HYDRA] #2 : width=100 height=300
[2025-07-27 00:14:46,607][__main__][INFO] - 3657aaa19d394549a1b715e079e95599
[2025-07-27 00:14:46,607][__main__][INFO] - {'width': 100, 'height': 300}
[2025-07-27 00:14:48,116][HYDRA] Launching 3 jobs locally
[2025-07-27 00:14:48,116][HYDRA] #0 : width=300 height=100
[2025-07-27 00:14:48,238][__main__][INFO] - 1cfe500630214d5ca1451940857b12aa
[2025-07-27 00:14:48,238][__main__][INFO] - {'width': 300, 'height': 100}
[2025-07-27 00:14:48,240][HYDRA] #1 : width=300 height=200
[2025-07-27 00:14:48,322][__main__][INFO] - 8268e975f36e417895045946911a3660
[2025-07-27 00:14:48,322][__main__][INFO] - {'width': 300, 'height': 200}
[2025-07-27 00:14:48,324][HYDRA] #2 : width=300 height=300
[2025-07-27 00:14:48,407][__main__][INFO] - 9a00dd02fb2b4bf5aba10b6fa827c212
[2025-07-27 00:14:48,407][__main__][INFO] - {'width': 300, 'height': 300}
0:00:03 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0:00:00 2/2 100%
2025/07/27 00:14:49 INFO mlflow.tracking.fluent: Experiment with name 'job_parallel' does not exist. Creating a new experiment.
[2025-07-27 00:14:51,290][HYDRA]
Joblib.Parallel(n_jobs=3,backend=loky,prefer=processes,require=None,verbose=0,ti
meout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=Non
e,mmap_mode=r) is launching 3 jobs
[2025-07-27 00:14:51,290][HYDRA] Launching jobs, sweep output dir :
multirun/01K14KPX2D5YR153AEN3B564CA
[2025-07-27 00:14:51,290][HYDRA] #0 : width=200 height=100
[2025-07-27 00:14:51,290][HYDRA] #1 : width=200 height=200
[2025-07-27 00:14:51,290][HYDRA] #2 : width=200 height=300
[2025-07-27 00:14:52,762][__main__][INFO] - 5f83c5c24f704fd2bcd8c5731a9dc9ac
[2025-07-27 00:14:52,762][__main__][INFO] - {'width': 200, 'height': 300}
[2025-07-27 00:14:53,175][__main__][INFO] - a412f2b4482f4f35a240b65ed384a39b
[2025-07-27 00:14:53,175][__main__][INFO] - {'width': 200, 'height': 100}
[2025-07-27 00:14:53,191][__main__][INFO] - fc66fa10c59b434db30e7c190dd342fe
[2025-07-27 00:14:53,191][__main__][INFO] - {'width': 200, 'height': 200}
[2025-07-27 00:14:55,260][HYDRA]
Joblib.Parallel(n_jobs=3,backend=loky,prefer=processes,require=None,verbose=0,ti
meout=None,pre_dispatch=2*n_jobs,batch_size=auto,temp_folder=None,max_nbytes=Non
e,mmap_mode=r) is launching 3 jobs
[2025-07-27 00:14:55,260][HYDRA] Launching jobs, sweep output dir :
multirun/01K14KPX2DFD8DK5TD8SSXDAC5
[2025-07-27 00:14:55,260][HYDRA] #0 : width=400 height=100
[2025-07-27 00:14:55,260][HYDRA] #1 : width=400 height=200
[2025-07-27 00:14:55,260][HYDRA] #2 : width=400 height=300
[2025-07-27 00:14:56,682][__main__][INFO] - 242a7d42501547cf861013303f6220ee
[2025-07-27 00:14:56,682][__main__][INFO] - {'width': 400, 'height': 200}
[2025-07-27 00:14:57,098][__main__][INFO] - 03e16ea01f7848a2ba4601e266c14867
[2025-07-27 00:14:57,099][__main__][INFO] - {'width': 400, 'height': 100}
[2025-07-27 00:14:57,108][__main__][INFO] - 02859139e38f45bda6f6eb403a955c97
[2025-07-27 00:14:57,108][__main__][INFO] - {'width': 400, 'height': 300}
0:00:07 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0:00:00 2/2 100%
2025/07/27 00:14:59 INFO mlflow.tracking.fluent: Experiment with name 'job_submit' does not exist. Creating a new experiment.
[2025-07-27 00:15:00,426][HYDRA] Launching 2 jobs locally
[2025-07-27 00:15:00,426][HYDRA] #0 : width=250 height=150
[2025-07-27 00:15:00,555][__main__][INFO] - a031af13bed84bb396cd1f15c2be90ba
[2025-07-27 00:15:00,555][__main__][INFO] - {'width': 250, 'height': 150}
[2025-07-27 00:15:00,558][HYDRA] #1 : width=250 height=250
[2025-07-27 00:15:00,643][__main__][INFO] - c6f34834426f4856b62151685c743738
[2025-07-27 00:15:00,644][__main__][INFO] - {'width': 250, 'height': 250}
[2025-07-27 00:15:02,286][HYDRA] Launching 2 jobs locally
[2025-07-27 00:15:02,287][HYDRA] #0 : width=350 height=150
[2025-07-27 00:15:02,426][__main__][INFO] - f17c7c6be50b424dab6bdf4cd2cc016a
[2025-07-27 00:15:02,426][__main__][INFO] - {'width': 350, 'height': 150}
[2025-07-27 00:15:02,429][HYDRA] #1 : width=350 height=250
[2025-07-27 00:15:02,516][__main__][INFO] - 44912afec34c4e29b3621ae07e8041ee
[2025-07-27 00:15:02,516][__main__][INFO] - {'width': 350, 'height': 250}
['/home/runner/work/hydraflow/hydraflow/.venv/bin/python', 'example.py', '--multirun', 'width=250', 'height=150,250', 'hydra.job.name=job_submit', 'hydra.sweep.dir=multirun/01K14KQ5Z7PJVWMHCS69XTQWHF']
['/home/runner/work/hydraflow/hydraflow/.venv/bin/python', 'example.py', '--multirun', 'width=350', 'height=150,250', 'hydra.job.name=job_submit', 'hydra.sweep.dir=multirun/01K14KQ5Z7T7QY4TX0E9BZVKR4']
After running these commands, our project structure looks like this:
.
├── mlruns
│ ├── 0
│ │ └── meta.yaml
│ ├── 323383529440857294
│ │ ├── 1cfe500630214d5ca1451940857b12aa
│ │ ├── 1d3e153ebff14fe889fc99b4bf9ff37c
│ │ ├── 3657aaa19d394549a1b715e079e95599
│ │ ├── 8268e975f36e417895045946911a3660
│ │ ├── 9a00dd02fb2b4bf5aba10b6fa827c212
│ │ ├── f17a2b5938734bcfbfea71207e2667c7
│ │ └── meta.yaml
│ ├── 521945427938310527
│ │ ├── 02859139e38f45bda6f6eb403a955c97
│ │ ├── 03e16ea01f7848a2ba4601e266c14867
│ │ ├── 242a7d42501547cf861013303f6220ee
│ │ ├── 5f83c5c24f704fd2bcd8c5731a9dc9ac
│ │ ├── a412f2b4482f4f35a240b65ed384a39b
│ │ ├── fc66fa10c59b434db30e7c190dd342fe
│ │ └── meta.yaml
│ └── 721705491711248679
│ ├── 44912afec34c4e29b3621ae07e8041ee
│ ├── a031af13bed84bb396cd1f15c2be90ba
│ ├── c6f34834426f4856b62151685c743738
│ ├── f17c7c6be50b424dab6bdf4cd2cc016a
│ └── meta.yaml
├── example.py
├── hydraflow.yaml
└── submit.py
The mlruns directory contains all our experiment data.
Let's explore how to access and analyze this data using HydraFlow's API.
Discovering Runs
Finding Run Directories
HydraFlow provides the iter_run_dirs
function to discover runs in your MLflow tracking directory:
>>> from hydraflow import iter_run_dirs
>>> run_dirs = list(iter_run_dirs("mlruns"))
>>> print(len(run_dirs))
>>> for run_dir in run_dirs[:4]:
... print(run_dir)
16
mlruns/521945427938310527/fc66fa10c59b434db30e7c190dd342fe
mlruns/521945427938310527/5f83c5c24f704fd2bcd8c5731a9dc9ac
mlruns/521945427938310527/242a7d42501547cf861013303f6220ee
mlruns/521945427938310527/a412f2b4482f4f35a240b65ed384a39b
This function finds all run directories in your MLflow tracking directory, making it easy to collect runs for analysis.
Filtering by Experiment Name
You can filter runs by experiment name to focus on specific experiments:
>>> print(len(list(iter_run_dirs("mlruns", "job_sequential"))))
>>> names = ["job_sequential", "job_parallel"]
>>> print(len(list(iter_run_dirs("mlruns", names))))
>>> print(len(list(iter_run_dirs("mlruns", "job_*"))))
6
12
16
As shown above, you can:
- Filter by a single experiment name
- Provide a list of experiment names
- Use pattern matching with wildcards
Working with Individual Runs
Loading a Run
The Run class represents a single
experiment run in HydraFlow:
>>> from hydraflow import Run
>>> run_dirs = iter_run_dirs("mlruns")
>>> run_dir = next(run_dirs) # run_dirs is an iterator
>>> run = Run(run_dir)
>>> print(run)
>>> print(type(run))
Run('fc66fa10c59b434db30e7c190dd342fe')
<class 'hydraflow.core.run.Run'>
You can also use the load
class method, which accepts both string paths and Path objects:
>>> Run.load(str(run_dir))
>>> print(run)
Run('fc66fa10c59b434db30e7c190dd342fe')
Accessing Run Information
Each Run instance provides access to run information and configuration:
>>> print(run.info.run_dir)
>>> print(run.info.run_id)
>>> print(run.info.job_name) # Hydra job name = MLflow experiment name
mlruns/521945427938310527/fc66fa10c59b434db30e7c190dd342fe
fc66fa10c59b434db30e7c190dd342fe
job_parallel
The configuration is available through the cfg attribute:
>>> print(run.cfg)
{'width': 200, 'height': 200}
Type-Safe Configuration Access
For better IDE integration and type checking, you can specify the configuration type:
from dataclasses import dataclass
@dataclass
class Config:
width: int = 1024
height: int = 768
>>> run = Run[Config](run_dir)
>>> print(run)
Run('fc66fa10c59b434db30e7c190dd342fe')
When you use Run[Config], your IDE will recognize run.cfg as
having the specified type, enabling autocompletion and type checking.
Accessing Configuration Values
The get method provides a unified interface to access values from a run:
>>> print(run.get("width"))
>>> print(run.get("height"))
200
200
Adding Custom Implementations
Basic Implementation
You can extend runs with custom implementation classes to add domain-specific functionality:
from pathlib import Path
class Impl:
root_dir: Path
def __init__(self, root_dir: Path):
self.root_dir = root_dir
def __repr__(self) -> str:
return f"Impl({self.root_dir.stem!r})"
>>> run = Run[Config, Impl](run_dir, Impl)
>>> print(run)
Run[Impl]('fc66fa10c59b434db30e7c190dd342fe')
The implementation is lazily initialized when you first access the impl attribute:
>>> print(run.impl)
>>> print(run.impl.root_dir)
Impl('artifacts')
mlruns/521945427938310527/fc66fa10c59b434db30e7c190dd342fe/artifacts
Configuration-Aware Implementation
Implementations can also access the run's configuration:
from dataclasses import dataclass, field
@dataclass
class Size:
root_dir: Path = field(repr=False)
cfg: Config
@property
def size(self) -> int:
return self.cfg.width * self.cfg.height
def is_large(self) -> bool:
return self.size > 100000
>>> run = Run[Config, Size].load(run_dir, Size)
>>> print(run)
>>> print(run.impl)
>>> print(run.impl.size)
Run[Size]('fc66fa10c59b434db30e7c190dd342fe')
Size(cfg={'width': 200, 'height': 200})
40000
This allows you to define custom analysis methods that use both the run's artifacts and its configuration.
Working with Multiple Runs
Creating a Run Collection
The RunCollection
class helps you analyze multiple runs:
>>> run_dirs = iter_run_dirs("mlruns")
>>> rc = Run[Config, Size].load(run_dirs, Size)
>>> print(rc)
RunCollection(Run[Size], n=16)
The load method automatically creates a RunCollection when
given multiple run directories.
Basic Run Collection Operations
You can perform basic operations on a collection:
>>> print(rc.first())
>>> print(rc.last())
Run[Size]('fc66fa10c59b434db30e7c190dd342fe')
Run[Size]('1cfe500630214d5ca1451940857b12aa')
Filtering Runs
The filter method
lets you select runs based on various criteria:
>>> print(rc.filter(width=400))
RunCollection(Run[Size], n=3)
You can use lists to filter by multiple values (OR logic):
>>> print(rc.filter(height=[100, 300]))
RunCollection(Run[Size], n=8)
Tuples create range filters (inclusive):
>>> print(rc.filter(height=(100, 300)))
RunCollection(Run[Size], n=16)
You can even use custom filter functions:
>>> print(rc.filter(lambda r: r.impl.is_large()))
RunCollection(Run[Size], n=1)
Finding Specific Runs
The get method
returns a single run matching your criteria:
>>> run = rc.get(width=250, height=(100, 200))
>>> print(run)
>>> print(run.impl)
Run[Size]('a031af13bed84bb396cd1f15c2be90ba')
Size(cfg={'width': 250, 'height': 150})
Converting to DataFrames
For data analysis, you can convert runs to a Polars DataFrame:
>>> print(rc.to_frame("width", "height", "size"))
shape: (16, 3)
┌───────┬────────┬────────┐
│ width ┆ height ┆ size │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═══════╪════════╪════════╡
│ 200 ┆ 200 ┆ 40000 │
│ 200 ┆ 300 ┆ 60000 │
│ 400 ┆ 200 ┆ 80000 │
│ 200 ┆ 100 ┆ 20000 │
│ 400 ┆ 300 ┆ 120000 │
│ … ┆ … ┆ … │
│ 100 ┆ 100 ┆ 10000 │
│ 300 ┆ 300 ┆ 90000 │
│ 100 ┆ 300 ┆ 30000 │
│ 100 ┆ 200 ┆ 20000 │
│ 300 ┆ 100 ┆ 30000 │
└───────┴────────┴────────┘
You can add custom columns using callables:
>>> print(rc.to_frame("width", "height", is_large=lambda r: r.impl.is_large()))
shape: (16, 3)
┌───────┬────────┬──────────┐
│ width ┆ height ┆ is_large │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ bool │
╞═══════╪════════╪══════════╡
│ 200 ┆ 200 ┆ false │
│ 200 ┆ 300 ┆ false │
│ 400 ┆ 200 ┆ false │
│ 200 ┆ 100 ┆ false │
│ 400 ┆ 300 ┆ true │
│ … ┆ … ┆ … │
│ 100 ┆ 100 ┆ false │
│ 300 ┆ 300 ┆ false │
│ 100 ┆ 300 ┆ false │
│ 100 ┆ 200 ┆ false │
│ 300 ┆ 100 ┆ false │
└───────┴────────┴──────────┘
Functions can return lists for multiple values:
>>> def to_list(run: Run) -> list[int]:
... return [2 * run.get("width"), 3 * run.get("height")]
>>> print(rc.to_frame("width", from_list=to_list))
shape: (16, 2)
┌───────┬────────────┐
│ width ┆ from_list │
│ --- ┆ --- │
│ i64 ┆ list[i64] │
╞═══════╪════════════╡
│ 200 ┆ [400, 600] │
│ 200 ┆ [400, 900] │
│ 400 ┆ [800, 600] │
│ 200 ┆ [400, 300] │
│ 400 ┆ [800, 900] │
│ … ┆ … │
│ 100 ┆ [200, 300] │
│ 300 ┆ [600, 900] │
│ 100 ┆ [200, 900] │
│ 100 ┆ [200, 600] │
│ 300 ┆ [600, 300] │
└───────┴────────────┘
Or dictionaries for multiple named columns:
>>> def to_dict(run: Run) -> dict[int, str]:
... width2 = 2 * run.get("width")
... name = f"h{run.get('height')}"
... return {"width2": width2, "name": name}
>>> print(rc.to_frame("width", from_dict=to_dict))
shape: (16, 2)
┌───────┬──────────────┐
│ width ┆ from_dict │
│ --- ┆ --- │
│ i64 ┆ struct[2] │
╞═══════╪══════════════╡
│ 200 ┆ {400,"h200"} │
│ 200 ┆ {400,"h300"} │
│ 400 ┆ {800,"h200"} │
│ 200 ┆ {400,"h100"} │
│ 400 ┆ {800,"h300"} │
│ … ┆ … │
│ 100 ┆ {200,"h100"} │
│ 300 ┆ {600,"h300"} │
│ 100 ┆ {200,"h300"} │
│ 100 ┆ {200,"h200"} │
│ 300 ┆ {600,"h100"} │
└───────┴──────────────┘
Grouping Runs
The group_by
method organizes runs by common attributes:
>>> grouped = rc.group_by("width")
>>> for key, group in grouped.items():
... print(key, group)
200 RunCollection(Run[Size], n=3)
400 RunCollection(Run[Size], n=3)
250 RunCollection(Run[Size], n=2)
350 RunCollection(Run[Size], n=2)
300 RunCollection(Run[Size], n=3)
100 RunCollection(Run[Size], n=3)
You can group by multiple keys:
>>> grouped = rc.group_by("width", "height")
>>> for key, group in grouped.items():
... print(key, group)
(200, 200) RunCollection(Run[Size], n=1)
(200, 300) RunCollection(Run[Size], n=1)
(400, 200) RunCollection(Run[Size], n=1)
(200, 100) RunCollection(Run[Size], n=1)
(400, 300) RunCollection(Run[Size], n=1)
(400, 100) RunCollection(Run[Size], n=1)
(250, 150) RunCollection(Run[Size], n=1)
(250, 250) RunCollection(Run[Size], n=1)
(350, 250) RunCollection(Run[Size], n=1)
(350, 150) RunCollection(Run[Size], n=1)
(300, 200) RunCollection(Run[Size], n=1)
(100, 100) RunCollection(Run[Size], n=1)
(300, 300) RunCollection(Run[Size], n=1)
(100, 300) RunCollection(Run[Size], n=1)
(100, 200) RunCollection(Run[Size], n=1)
(300, 100) RunCollection(Run[Size], n=1)
Adding aggregation functions using the
agg
method transforms the result into a DataFrame:
>>> grouped = rc.group_by("width")
>>> df = grouped.agg(n=lambda runs: len(runs))
>>> print(df)
shape: (6, 2)
┌───────┬─────┐
│ width ┆ n │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═══════╪═════╡
│ 200 ┆ 3 │
│ 400 ┆ 3 │
│ 250 ┆ 2 │
│ 350 ┆ 2 │
│ 300 ┆ 3 │
│ 100 ┆ 3 │
└───────┴─────┘
Summary
In this tutorial, you've learned how to:
- Discover experiment runs in your MLflow tracking directory
- Load and access information from individual runs
- Add custom implementation classes for domain-specific analysis
- Filter, group, and analyze collections of runs
- Convert run data to DataFrames for advanced analysis
These capabilities enable you to efficiently analyze your experiments and extract valuable insights from your machine learning workflows.
Next Steps
Now that you understand HydraFlow's analysis capabilities, you can:
- Dive deeper into the Run Class and Run Collection documentation
- Explore advanced analysis techniques in the Analyzing Results section
- Apply these analysis techniques to your own machine learning experiments