radiens-qc

radiens-qc turns a Radiens recording into an answerable question: is this data good enough to use?

Give it a recording and a VidereClient. It configures read-time DSP so the KPIs reflect the spike band, walks the recording in windows, and returns a report: per-channel SNR / noise floor / event rate, a quality tier per channel, and a single-letter grade — plus a one-page figure you can hand to a PI.

Quick start

from pathlib import Path

from radiens_core import VidereClient
from radiens_qc import compute_report, save_report

vc = VidereClient()
report = compute_report(vc, Path("/data/rec01.xdat"), source="exp/day3")

print(report.grade())            # "A"
print(report.median("snr"))      # 6.2
print(report.quality_counts())   # {"good": 26, "fair": 4, "poor": 1, "dead": 1}

save_report(report, Path("reports"))   # -> reports/rec01/

Comparing sessions

save_report writes a self-describing folder, and the comparative report is built from those folders — no server, no KPI recompute:

from radiens_qc.compare import ComparativeReport, load_session_summaries, save_comparative_report

summaries = load_session_summaries(Path("reports"))
save_comparative_report(ComparativeReport.from_summaries(summaries), Path("reports"))

Where recordings come from is not this package's problem

compute_report takes either a local Path or an already-linked DatasetMetadata. Given a path it links the file itself — linking is idempotent server-side, so passing a path for an already-linked file costs nothing. Fetching bytes from Drive, S3, or a lab share stays with the caller, which is what lets the same report code serve any project.

A bare str is deliberately not accepted: in radiens-core a string means a dataset id, not a path. Wrap yours in Path(...).

What gets written

save_report(report, out_dir) creates <out_dir>/<base_name>/:

load_report reads folders written by any version; pre-schema_version folders load with empty matrices, which blanks the temporal panels rather than failing.

Plotting

Plot functions are pure — they build and return matplotlib Figure objects and never touch the filesystem, so figure routing stays yours:

from radiens_qc import plot_report, plot_report_panels

fig = plot_report(report)                 # composite page
panels = plot_report_panels(report)       # {"spatial_snr": Figure, "ranked_bar": Figure, ...}

The composite is laid out as an exact 8.5×11in page. Save it with bbox_inches=None — matplotlib's "tight" default crops the page sizing away. save_report already does this.

Installation

This project uses uv for dependency management.

Installing uv

If you don't have uv installed yet, you can do so using the following methods:

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

For more installation options, see the uv documentation.

Project Setup

Once uv is installed, run:

uv venv
uv sync

Development

Running Checks

To run all formatting, linting, type-checking, and tests:

uv run dev check

Pass extra args to ruff check:

uv run dev check --select E

Remove build artifacts and caches:

uv run dev clean

Documentation

Serve documentation locally:

uv run mkdocs serve

Build documentation:

uv run mkdocs build