matrix

Run pipelines across multiple files with parameter combinations for reproducible batch processing.

Pipeline Matrix enables you to define a pipeline once and sweep across multiple input files and parameter variations in a single reproducible batch. Each combination is run in isolation with outputs organized by row for easy comparison and aggregation.

Concepts

Matrix Rows: A matrix is a CSV where each row specifies: - An input file (must exist in data/raw/ or project root) - Parameter overrides for selected pipeline steps

Parameter Specs: Define which step options to vary: - Format: step.option=value1,value2,value3 - Steps are indexed (0-based) or named (if defined in triton.toml) - Values are auto-parsed as bool, int, float, or string

Isolated Outputs: Each matrix row gets its own output folder (e.g. row_0, row_1, ...) so results never collide and can be compared side-by-side.

generate

Generate a CSV matrix from files and parameter combinations.

pixi run triton matrix generate <project-dir> <pipeline-name> <output-csv> \
  [--param SPEC] [--param ...] \
  [--file PATH] [--file ...]

Arguments

• project-dir: Path to Triton project root
• pipeline-name: Name of pipeline defined in triton.toml
• output-csv: Path where CSV matrix will be written (e.g. matrix.csv)

Options

• --param SPEC (repeatable): Parameter specification (step.option=v1,v2,v3)
• --file PATH (repeatable): Input file (relative to data/raw/ or absolute)

Example

# Generate matrix with all combinations of target_peak and files
pixi run triton matrix generate my-project my-pipeline matrix.csv \
  --param '0.target_peak=0.5,0.8' \
  --file normalized/speech_001.wav \
  --file normalized/speech_002.wav \
  --file normalized/speech_003.wav

This creates a CSV with 6 rows (3 files × 2 target_peak values). Each row can be edited or filtered before running.

CSV Format

The generated CSV has this structure:

file	0.target_peak
normalized/speech_001.wav	0.5
normalized/speech_001.wav	0.8
normalized/speech_002.wav	0.5
normalized/speech_002.wav	0.8
...	...

• First column: file (input path)
• Remaining columns: step.option for each parameter spec
• Rows are ordered file-first (all parameters for file_0, then file_1, etc.)

You can manually edit or filter rows before running.

run

Execute all rows in a matrix CSV against the pipeline.

pixi run triton matrix run <project-dir> <pipeline-name> <matrix-csv> \
  [--run-id RUN_ID]

Arguments

• project-dir: Path to Triton project root
• pipeline-name: Name of pipeline defined in triton.toml
• matrix-csv: Path to CSV generated by matrix generate

Options

• --run-id RUN_ID: Custom run ID. If omitted, a timestamp-based ID is generated.

Example

# Run all matrix rows
pixi run triton matrix run my-project my-pipeline matrix.csv

# Run with explicit run ID for easy reference
pixi run triton matrix run my-project my-pipeline matrix.csv --run-id sweep_001

Output Structure

Outputs are organized under data/derived/pipelines/<pipeline-name>/<run-id>/:

data/derived/pipelines/
  my-pipeline/
    <run-id>/
      row_0/
        <step-1-output>/
        <step-2-output>/
        run.log.jsonl
      row_1/
        <step-1-output>/
        <step-2-output>/
        run.log.jsonl
      ...

Each row is independent, so you can: - Compare outputs side-by-side - Aggregate results programmatically - Rerun specific rows later - Archive successful runs with confidence

Workflow Example

1. Define a pipeline in triton.toml

[[pipeline]]
name = "degrade_and_transcode"

[[pipeline.step]]
name = "degrade"
action = "degrade.vocode"
target_peak = 0.6
vocoder_type = "noise"
n_bands = 8

[[pipeline.step]]
name = "convert"
action = "convert.resample"
target_sr = 16000

2. Generate the matrix

pixi run triton matrix generate my-project degrade_and_transcode matrix.csv \
  --param '0.target_peak=0.5,0.6,0.8' \
  --param '0.n_bands=4,8,16' \
  --file normalized/sample_001.wav \
  --file normalized/sample_002.wav \
  --file normalized/sample_003.wav

This creates 27 rows (3 files × 3 target_peak × 3 n_bands).

3. (Optional) Review and edit the CSV

Open matrix.csv in your editor to: - Delete rows you don't need - Modify parameter values - Add new rows manually

4. Run the matrix

pixi run triton matrix run my-project degrade_and_transcode matrix.csv --run-id sweep_001

Monitor progress: each row logs to its own run.log.jsonl.

5. Analyze and compare

# List all outputs
ls -la my-project/data/derived/pipelines/degrade_and_transcode/sweep_001/

# Compare spectrograms or metrics across rows
for row in row_*; do
  echo "=== $row ==="
  ls "$row"/
done

Python API

You can also use Pipeline Matrix from Python:

from triton.core import generate_matrix_csv, run_matrix_csv
from triton.core.project import load_project_config, load_project_pipelines

project = load_project_config("my-project")
pipelines = load_project_pipelines("my-project")
pipeline = pipelines[0]  # or find by name

# Generate matrix
rows = generate_matrix_csv(
    project,
    pipeline,
    output_csv="matrix.csv",
    parameter_specs=["0.target_peak=0.5,0.8"],
    files=["normalized/speech.wav"],
)

# Run matrix
run_matrix_csv(
    project,
    pipeline,
    matrix_csv="matrix.csv",
    run_id="my_run",
)

Design Notes

• Each row is independent, so runs are parallelizable in future versions.
• Parameter overrides are shallow (step-level), so nested options are not yet supported.
• Empty cells in the CSV (blanks) are treated as "do not override" for that parameter.
• File paths are resolved relative to data/raw/ first, then project root. Use absolute paths to reference files outside the project.