End-to-end worked example

One realistic scenario, start to finish — folder to pipeline to comparison — using nearly every function in the library.

This page follows one dataset all the way through Braven: a temperature sweep run across several read-out boards, each identified by a device key. It uses log_config, log_summary, log_series, plot_series, device(), path_params(), and upload() with a matplotlib Figure — the full set from Write a pipeline script.

The shape of the flow

1. The data on disk

Each board’s run at each temperature lands as one CSV, dropped by the instrument’s own software into a watched folder:

BoardCalibration/
  ├── run_boardS1_30C/
  │     └── boardS1_30C.csv
  ├── run_boardS1_50C/
  │     └── boardS1_50C.csv
  ├── run_boardS2_30C/
  │     └── boardS2_30C.csv
  └── run_boardS2_50C/
        └── boardS2_50C.csv

Each subfolder becomes one Experiment automatically — see Ingest data. 30C / 50C in the filename is exactly the pattern braven.path_params() recognizes.

2. The pipeline script

Assigned once, to the BoardCalibration folder — every new subfolder runs this automatically.

# requirements: pandas numpy matplotlib

import re
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import braven

# --- Read the one file this experiment carries -----------------------------
filename = next(iter(braven.files))
df = pd.read_csv(filename)

# --- Pull the temperature straight from the filename ------------------------
params = braven.path_params()             # {"temperature": 30.0} from "...30C..."
temperature_c = params.get("temperature")
braven.log_config("temperature_c", str(temperature_c))

# --- Identify the physical board from the filename and tag everything to it -
board_match = re.search(r"board(\w+?)_\d", filename)
board_key = board_match.group(1) if board_match else "unknown"
board = braven.device(board_key, type="Read-out board")

board.log_config("temperature_c", str(temperature_c))

signal = df["signal"].to_numpy()
noise = df["noise"].to_numpy()
snr = float(np.mean(signal) / np.std(noise))
board.log_summary("snr", f"{snr:.3f}")

# Experiment-level summary — not tied to one board.
braven.log_summary("row_count", str(len(df)))

# --- Plottable curve, overlayable across every board/temperature combo ------
board.plot_series(
    "signal_vs_time",
    y=signal.tolist(),
    x=df["time"].tolist(),
    x_label="Time (s)",
    y_label=f"{board_key} @ {temperature_c:.0f}C",
)

# --- A rendered figure, auto-converted into an interactive companion -------
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(9, 3.5))
ax1.plot(df["time"], signal)
ax1.set_title("Signal"); ax1.set_xlabel("Time (s)")
ax2.hist(noise, bins=30)
ax2.set_title("Noise distribution")
braven.upload(fig, f"{board_key}_{temperature_c:.0f}C_summary.png")

3. What shows up in the app

1. Experiments

   Four experiments — one per file — each with a temperature_c Config value, a row_count Summary value, a two-panel Figure in its Images tab, and a signal_vs_time Series.

2. Devices

   Two devices, S1 and S2 (type Read-out board), each accumulating an snr history across every temperature it’s been run at — no manual linking step, because the script tagged them with braven.device(board_key).

3. Analysis

   Mark all four experiments visible, open Analysis, and ctrl+click each board’s signal_vs_time series to build one chart with all four curves overlaid — instantly comparable across board and temperature. See Analyze and compare.

4. Reports

   Once the comparison says what you want it to say, save it as a Report — a live KPI plot segment keeps referencing the same experiments, so it stays current if you add a 70C run later. See Reports.

Why this example uses device() instead of encoding the board into every key name

Compare board.log_summary("snr", ...) against the alternative of writing braven.log_summary("snr_S1", ...) per board. The device-scoped version keeps the metric name identical ("snr") across every board — the device is a separate coordinate, not a suffix — which is what makes it possible to later query or plot “SNR across boards” as one consistent field instead of parsing it back out of ad-hoc key names.