`qc`#

Quality-control checks and trend tracking for routine measurements.

Define a QC configuration listing the metrics to watch (SNR, linewidth, peak position, …) with pass/fail limits, run measure on a reference spectrum to record pass/fail, then review history, trends, statistics, and control charts over time. Useful for daily instrument checks.

add_metric #

add_metric(
    config_name: str,
    metric_type: str,
    name: str | None = None,
    unit: str = "",
    lower_limit: float | None = None,
    upper_limit: float | None = None,
    target_value: float | None = None,
    peak_index: int | None = None,
    region_start_hz: float | None = None,
    region_end_hz: float | None = None,
) -> bool

Add a metric to an existing configuration.

Parameters:

Name	Type	Description	Default
`config_name`	`str`	Name of the configuration to modify.	required
`metric_type`	`str`	Type of metric ("snr", "linewidth_hz", etc.).	required
`name`	`str \| None`	Display name (defaults to metric_type if not provided).	`None`
`unit`	`str`	Unit string.	`''`
`lower_limit`	`float \| None`	Minimum acceptable value.	`None`
`upper_limit`	`float \| None`	Maximum acceptable value.	`None`
`target_value`	`float \| None`	Expected nominal value.	`None`
`peak_index`	`int \| None`	For peak-specific metrics.	`None`
`region_start_hz`	`float \| None`	Start of integration region (for integral).	`None`
`region_end_hz`	`float \| None`	End of integration region (for integral).	`None`

Returns:

Type	Description
`bool`	True if successful, False if configuration not found.

clear_history #

clear_history(config_name: str | None = None) -> int

Clear QC history.

Parameters:

Name	Type	Description	Default
`config_name`	`str \| None`	Clear only for this config (None for all).	`None`

Returns:

Type	Description
`int`	Number of records deleted.

create_configuration #

create_configuration(
    name: str,
    reference_sample: str = "",
    metrics: list[dict[str, Any]] | None = None,
    sequence_preset: str | None = None,
    enabled: bool = True,
) -> dict[str, Any]

Create a new QC configuration.

Parameters:

Name	Type	Description	Default
`name`	`str`	Configuration name (e.g., "daily_snr_check").	required
`reference_sample`	`str`	Reference sample description (e.g., "sucrose_standard").	`''`
`metrics`	`list[dict[str, Any]] \| None`	List of metric definitions, each containing: - type: Metric type ("snr", "linewidth_hz", "peak_position_hz", "peak_position_ppm", "integral", "baseline_rms", "custom") - name: Display name for the metric - unit: Unit string (optional) - lower_limit: Fail if value below this (optional) - upper_limit: Fail if value above this (optional) - target_value: Expected nominal value (optional) - peak_index: For peak-specific metrics (optional) - region_start_hz, region_end_hz: For integral metrics (optional)	`None`
`sequence_preset`	`str \| None`	Optional sequence preset name for QC acquisition.	`None`
`enabled`	`bool`	Whether the configuration is active.	`True`

Returns:

Type	Description
`dict[str, Any]`	A summary of the created configuration with keys: `name`,
`dict[str, Any]`	`reference_sample`, `metrics_count` (how many metrics it has), and
`dict[str, Any]`	`enabled`.

Example

qc.create_configuration(
    "daily_snr",
    reference_sample="sucrose",
    metrics=[
        {"type": "snr", "name": "SNR", "lower_limit": 50},
        {"type": "linewidth_hz", "name": "Linewidth", "upper_limit": 2.0, "peak_index": 0},
    ],
)

delete_configuration #

delete_configuration(name: str) -> bool

Delete a QC configuration.

Parameters:

Name	Type	Description	Default
`name`	`str`	Configuration name to delete.	required

Returns:

Type	Description
`bool`	True if deleted, False if not found.

generate_chart #

generate_chart(
    config_name: str,
    metric_name: str,
    days: int = 30,
    width: int = 800,
    height: int = 400,
    scale: float = 2.0,
    title: str | None = None,
) -> str | None

Generate a QC control chart image as base64-encoded PNG.

Use this to create custom charts for reports with specific parameters.

Parameters:

Name	Type	Description	Default
`config_name`	`str`	QC configuration name.	required
`metric_name`	`str`	Metric to chart.	required
`days`	`int`	Number of days of trend data to include.	`30`
`width`	`int`	Image width in pixels.	`800`
`height`	`int`	Image height in pixels.	`400`
`scale`	`float`	Scale factor for high-DPI output.	`2.0`
`title`	`str \| None`	Custom chart title (auto-generated if None).	`None`

Returns:

Type	Description
`str \| None`	Base64-encoded PNG image string, or None if no data/error.

Example

# Generate high-resolution chart for specific period
chart = qc.generate_chart("daily_snr", "SNR", days=90, width=1200, height=600, title="SNR Trend (Last 90 Days)")

# Use in report template via custom data
reporting.set_data("snr_chart", chart)

generate_chart_html #

generate_chart_html(
    config_name: str,
    metric_name: str,
    days: int = 30,
    width: int = 800,
    height: int = 400,
    scale: float = 2.0,
    title: str | None = None,
) -> str

Generate a QC control chart as an HTML img tag.

Like generate_chart() but returns complete HTML that can be directly embedded in report templates.

Parameters:

Name	Type	Description	Default
`config_name`	`str`	QC configuration name.	required
`metric_name`	`str`	Metric to chart.	required
`days`	`int`	Number of days of trend data to include.	`30`
`width`	`int`	Image width in pixels.	`800`
`height`	`int`	Image height in pixels.	`400`
`scale`	`float`	Scale factor for high-DPI output.	`2.0`
`title`	`str \| None`	Custom chart title (auto-generated if None).	`None`

Returns:

Type	Description
`str`	HTML img tag with embedded base64 image, or error message.

Example

# Generate chart and embed in report
chart_html = qc.generate_chart_html("daily_snr", "SNR", days=60)
reporting.set_data("snr_chart_html", chart_html)

get_configuration #

get_configuration(name: str) -> dict[str, Any] | None

Get a QC configuration by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Configuration name.	required

Returns:

Type	Description
`dict[str, Any] \| None`	The configuration as a dictionary, or `None` if not found. Keys:
`dict[str, Any] \| None`	`name`, `reference_sample`, `sequence_preset`, `enabled`, and
`dict[str, Any] \| None`	`metrics` (a list of metric definitions, each with `type`,
`dict[str, Any] \| None`	`name`, `unit`, `lower_limit`, `upper_limit`, `target_value`,
`dict[str, Any] \| None`	`peak_index`, `region_start_hz`, `region_end_hz`).

get_history #

get_history(
    config_name: str | None = None, limit: int = 100
) -> list[dict[str, Any]]

Get QC measurement history.

Parameters:

Name	Type	Description	Default
`config_name`	`str \| None`	Filter by configuration (None for all).	`None`
`limit`	`int`	Maximum records to return.	`100`

Returns:

Name	Type	Description
	`list[dict[str, Any]]`	A list of past measurement records, newest first. Each record has
`keys`	`list[dict[str, Any]]`	`id`, `config_name`, `timestamp`, `overall_pass`, and
	`list[dict[str, Any]]`	`measurements` (a list of `{name, value, passed}` per metric).

get_statistics #

get_statistics(
    config_name: str, metric_name: str, days: int = 30
) -> dict[str, Any] | None

Get statistics for a specific metric.

Parameters:

Name	Type	Description	Default
`config_name`	`str`	QC configuration name.	required
`metric_name`	`str`	Metric to analyze.	required
`days`	`int`	Number of days of history.	`30`

Returns:

Type	Description
`dict[str, Any] \| None`	Statistics dictionary or None if no data:
`dict[str, Any] \| None`	count: Number of measurements
`dict[str, Any] \| None`	mean: Average value
`dict[str, Any] \| None`	std: Standard deviation
`dict[str, Any] \| None`	min: Minimum value
`dict[str, Any] \| None`	max: Maximum value
`dict[str, Any] \| None`	pass_rate: Fraction of measurements that passed (0-1)
`dict[str, Any] \| None`	last_value: Most recent value
`dict[str, Any] \| None`	last_passed: Whether most recent passed

get_trend #

get_trend(
    config_name: str, metric_name: str, days: int = 30
) -> list[dict[str, Any]]

Get trend data for a specific metric.

Parameters:

Name	Type	Description	Default
`config_name`	`str`	QC configuration name.	required
`metric_name`	`str`	Metric to get trend for.	required
`days`	`int`	Number of days of history.	`30`

Returns:

Type	Description
`list[dict[str, Any]]`	List of {timestamp, value, passed} dicts.

list_configurations #

list_configurations() -> list[str]

List all QC configuration names.

Returns:

Type	Description
`list[str]`	List of configuration names.

measure #

measure(
    config_name: str,
    spectrum: Spectrum1D | None = None,
    scan_id: str | None = None,
    notes: str = "",
    dry_run: bool = False,
) -> dict[str, Any]

Run QC measurement using current or provided spectrum.

Parameters:

Name	Type	Description	Default
`config_name`	`str`	Name of QC configuration to use.	required
`spectrum`	`Spectrum1D \| None`	Spectrum to analyze (uses current spectrum if None).	`None`
`scan_id`	`str \| None`	Optional scan ID to associate with measurement.	`None`
`notes`	`str`	Optional notes.	`''`
`dry_run`	`bool`	If True, compute metrics but don't save to history. Use this to preview results before committing.	`False`

Returns:

Type	Description
`dict[str, Any]`	Dictionary with measurement results:
`dict[str, Any]`	id: Record ID
`dict[str, Any]`	overall_pass: True if all metrics passed
`dict[str, Any]`	measurements: List of individual metric results
`dict[str, Any]`	timestamp: ISO timestamp
`dict[str, Any]`	dry_run: Whether this was a dry run (not saved)

Example

# Preview first
preview = qc.measure("daily_snr", dry_run=True)
print(f"Preview: {'PASS' if preview['overall_pass'] else 'FAIL'}")

# Then record if satisfied
result = qc.measure("daily_snr")
if result["overall_pass"]:
    print("QC PASSED!")
else:
    for m in result["measurements"]:
        if not m["passed"]:
            print(f"FAILED: {m['name']} = {m['value']}")

set_report_options #

set_report_options(
    config_name: str | None = None,
    days: int = 30,
    width: int = 800,
    height: int = 400,
    scale: float = 2.0,
    include_charts: bool = True,
) -> None

Set options for QC data in auto-generated reports.

These options affect how QC data appears in reports when using the {{qc}} template variable. Call before generating a report.

Parameters:

Name	Type	Description	Default
`config_name`	`str \| None`	Only include this config in reports (None = all).	`None`
`days`	`int`	Days of trend data to include.	`30`
`width`	`int`	Chart width in pixels.	`800`
`height`	`int`	Chart height in pixels.	`400`
`scale`	`float`	Chart scale factor.	`2.0`
`include_charts`	`bool`	Whether to generate chart images.	`True`

Example

# Configure report to show 60 days of data with larger charts
qc.set_report_options(days=60, width=1000, height=500)

# Only show specific configuration
qc.set_report_options(config_name="daily_snr")

# Disable chart generation for faster reports
qc.set_report_options(include_charts=False)

qc#

add_metric #

clear_history #

create_configuration #

delete_configuration #

generate_chart #

generate_chart_html #

get_configuration #

get_history #

get_statistics #

get_trend #

list_configurations #

measure #

set_report_options #

`qc`#