timeseries-qc 0.1.0__tar.gz

timeseries_qc-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: timeseries-qc
+Version: 0.1.0
+Summary: Classify timeseries rows as Good / Sus / Bad and render a multi-tag quality timeline chart.
+Author: timeseries-qc contributors
+License-Expression: MIT
+Project-URL: Homepage, https://nagusubra.github.io/timeseries-qc/
+Project-URL: Repository, https://github.com/nagusubra/timeseries-qc
+Project-URL: Issues, https://github.com/nagusubra/timeseries-qc/issues
+Keywords: timeseries,data quality,QC,SCADA,IoT,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5
+Requires-Dist: plotly>=5.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# timeseries-qc
+
+[![PyPI](https://img.shields.io/pypi/v/timeseries-qc)](https://pypi.org/project/timeseries-qc/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**The open source data quality-control layer for SCADA, DCS, IoT, and historian timeseries data.**
+
+Add `good / sus / bad` quality labels to every row of a pandas DataFrame in five lines. Then render a multi-tag horizontal status timeline, the chart that no other open-source library produces.
+
+A simple to digest and understand timeseries data quality check. Catch the issues in your process data before it affects your downstream analytics and business decisions. Build data quality checks based on business rules and monitor through interactive graph  components. 
+
+**Sample Input - Solar farm SCADA data:**
+
+```text
+| timestamp                 | tag_name       | value   |
+| :------------------------ | :------------- | :------ |
+| 2026-01-01 00:00:00+00:00 | INVERTER.MW    | 42.1    |
+| 2026-01-01 01:00:00+00:00 | INVERTER.MW    | NULL    |  <-- timeseries_qc will catch this (Null value)
+| 2026-01-01 02:00:00+00:00 | INVERTER.MW    | 52.3    |
+| 2026-01-01 00:00:00+00:00 | MET.IRRADIANCE | 600.001 |
+| 2026-01-01 01:00:00+00:00 | MET.IRRADIANCE | 600.001 |  <-- timeseries_qc will catch this (Stale/Frozen value)
+| 2026-01-01 02:00:00+00:00 | MET.IRRADIANCE | 810.818 |
+| 2026-01-01 00:00:00+00:00 | TRACKER.ANGLE  | 30.22   |
+| 2026-01-01 01:00:00+00:00 | TRACKER.ANGLE  | 45.31   |
+| 2026-01-01 02:00:00+00:00 | TRACKER.ANGLE  | 60.22   |
+```
+
+**Sample Output - Solar farm SCADA data:**
+
+![Solar farm SCADA data quality example](./docs/solar_farm_example.png)
+
+
+**Sample Input - Oil field SCADA data:**
+
+```text
+| timestamp                 | tag_name     | value  |
+| :------------------------ | :----------- | :----- |
+| 2026-01-01 00:00:00+00:00 | WHP.PSIG     | 0      |  <-- timeseries_qc will catch this (Flatline/Zero)
+| 2026-01-01 01:00:00+00:00 | WHP.PSIG     | 0      |  <-- timeseries_qc will catch this (Flatline/Zero)
+| 2026-01-01 02:00:00+00:00 | WHP.PSIG     | 0      |  <-- timeseries_qc will catch this (Flatline/Zero)
+| 2026-01-01 00:00:00+00:00 | FMRATE.MSCFD | 12.1   |
+| 2026-01-01 01:00:00+00:00 | FMRATE.MSCFD | 90.99  |  <-- timeseries_qc will catch this (Rate-of-change spike)
+| 2026-01-01 02:00:00+00:00 | FMRATE.MSCFD | 12.3   |
+| 2026-01-01 00:00:00+00:00 | OHT.TEMP_F   | 30.2   |
+| 2026-01-01 01:00:00+00:00 | OHT.TEMP_F   | 45.2   |
+| 2026-01-01 02:00:00+00:00 | OHT.TEMP_F   | 6000.2 |  <-- timeseries_qc will catch this (Out of bounds)
+```
+
+**Sample Output - Oil field SCADA data:**
+
+![Oil  field SCADA data quality example](./docs/oil_field_example.png)
+
+
+## Features
+
+- **Four built-in rules** cover ≥80% of real-world bad data: `NullRule`, `FlatlineRule`, `DeltaRule`, `RangeRule`
+- **Timeline chart** (`result.plot()`) — Plotly Gantt-style, one row per tag, Green/Yellow/Red, hover tooltips
+- **YAML config** — non-coders set thresholds in a text file, no Python required
+- **Timestamp health** (`result.check_timestamps()`) — detects gaps, duplicates, non-monotonic, freq drift, DST ambiguity
+- **Self-contained HTML export** (`result.export_report("report.html")`) — offline, no CDN, includes per-issue summary table
+- **Per-issue breakdown** (`result.issue_summary()`) — start/end times, row count, duration, and status for each contiguous bad/sus segment
+- **Pandas-native** — works with any DataFrame that has `timestamp`, `tag_name`, `value` columns
+
+---
+
+## Installation
+
+```bash
+pip install timeseries-qc
+```
+
+---
+
+## Quickstart (5 lines)
+
+```python
+import tsqc
+import pandas as pd
+
+df = pd.read_csv("sensor_data.csv")          # columns: timestamp, tag_name, value
+result = tsqc.check(df, assume_tz="UTC")     # assume_tz required for tz-naive CSVs
+result.plot().show()                          # renders the multi-tag quality timeline
+```
+
+If your CSV already contains tz-aware timestamps (ISO 8601 with `+00:00`), omit `assume_tz`.
+
+---
+
+## YAML Config Example
+
+```yaml
+# tsqc_rules.yaml
+default_rules:
+  - check: null
+    level: bad
+  - check: flatline
+    window: 1h
+    min_delta: 0.001
+    level: sus
+  - check: delta
+    threshold: 50.0
+    level: sus
+
+tag_rules:
+  FOREBAY.LEVEL:
+    - check: range
+      min: 900
+      max: 1100
+      level: bad
+  "GENERATOR.*":
+    - check: range
+      min: 0
+      max: 200
+      level: bad
+    - check: flatline
+      window: 30min
+      min_delta: 0.5   # 0 MW for <30min is valid; longer flatline at non-zero is suspect
+      level: sus
+```
+
+```python
+result = tsqc.check(df, rules="tsqc_rules.yaml")
+result.summary()           # DataFrame: pct_good/sus/bad per tag
+result.issue_summary()     # DataFrame: per-issue runs (start, end, rows, duration)
+result.check_timestamps()  # DataFrame: gap/duplicate/non_monotonic issues
+result.export_report("report.html")  # Full HTML with chart + all tables
+```
+
+---
+
+## Output Schema
+
+`result.df` adds two columns to your DataFrame:
+
+| Column | Values | Notes |
+|--------|--------|-------|
+| `quality` | `"good"`, `"sus"`, `"bad"` | Worst-level rule wins |
+| `quality_reasons` | e.g. `"flatline\|range"` | Pipe-delimited triggered rule names |
+
+---
+
+## Comparison with Alternatives
+
+**Pecos** (Sandia Labs) offers binary pass/fail and has been in maintenance mode since 2021 — no timeline chart and no YAML config. **SaQC** (Helmholtz UFZ) is a rich flagging engine for environmental science but has an environmental-domain API, no timeline visualization, and an LGPL license. **Great Expectations** is not timeseries-native and produces no visualization. `timeseries-qc` is the only library that combines (1) Good/Sus/Bad classification, (2) the multi-tag horizontal status timeline, and (3) YAML-driven configuration in a single `pip install`.
+
+---
+
+## Examples
+
+- [examples/solar_farm.ipynb](examples/solar_farm.ipynb) — solar farm SCADA data with anomaly injection
+- [examples/oilfield.ipynb](examples/oilfield.ipynb) — oil well pad SCADA data with anomaly injection
+
+---
+
+## Known Limitations (v0.1.0)
+
+1. **Pandas only.** PySpark and Polars support are deferred.
+2. **No YAML override of default rules.** Tag-specific rules add to, not replace, default rules.
+3. **Visualization requires Plotly ≥ 5.0.** Matplotlib output not supported.
+4. **`DeltaRule` is point-to-point diff only.** Rolling-window delta is a v0.2 feature.
+
+---
+
+## License
+
+MIT © timeseries-qc contributors

timeseries_qc-0.1.0/README.md

@@ -0,0 +1,166 @@
+# timeseries-qc
+
+[![PyPI](https://img.shields.io/pypi/v/timeseries-qc)](https://pypi.org/project/timeseries-qc/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**The open source data quality-control layer for SCADA, DCS, IoT, and historian timeseries data.**
+
+Add `good / sus / bad` quality labels to every row of a pandas DataFrame in five lines. Then render a multi-tag horizontal status timeline, the chart that no other open-source library produces.
+
+A simple to digest and understand timeseries data quality check. Catch the issues in your process data before it affects your downstream analytics and business decisions. Build data quality checks based on business rules and monitor through interactive graph  components. 
+
+**Sample Input - Solar farm SCADA data:**
+
+```text
+| timestamp                 | tag_name       | value   |
+| :------------------------ | :------------- | :------ |
+| 2026-01-01 00:00:00+00:00 | INVERTER.MW    | 42.1    |
+| 2026-01-01 01:00:00+00:00 | INVERTER.MW    | NULL    |  <-- timeseries_qc will catch this (Null value)
+| 2026-01-01 02:00:00+00:00 | INVERTER.MW    | 52.3    |
+| 2026-01-01 00:00:00+00:00 | MET.IRRADIANCE | 600.001 |
+| 2026-01-01 01:00:00+00:00 | MET.IRRADIANCE | 600.001 |  <-- timeseries_qc will catch this (Stale/Frozen value)
+| 2026-01-01 02:00:00+00:00 | MET.IRRADIANCE | 810.818 |
+| 2026-01-01 00:00:00+00:00 | TRACKER.ANGLE  | 30.22   |
+| 2026-01-01 01:00:00+00:00 | TRACKER.ANGLE  | 45.31   |
+| 2026-01-01 02:00:00+00:00 | TRACKER.ANGLE  | 60.22   |
+```
+
+**Sample Output - Solar farm SCADA data:**
+
+![Solar farm SCADA data quality example](./docs/solar_farm_example.png)
+
+
+**Sample Input - Oil field SCADA data:**
+
+```text
+| timestamp                 | tag_name     | value  |
+| :------------------------ | :----------- | :----- |
+| 2026-01-01 00:00:00+00:00 | WHP.PSIG     | 0      |  <-- timeseries_qc will catch this (Flatline/Zero)
+| 2026-01-01 01:00:00+00:00 | WHP.PSIG     | 0      |  <-- timeseries_qc will catch this (Flatline/Zero)
+| 2026-01-01 02:00:00+00:00 | WHP.PSIG     | 0      |  <-- timeseries_qc will catch this (Flatline/Zero)
+| 2026-01-01 00:00:00+00:00 | FMRATE.MSCFD | 12.1   |
+| 2026-01-01 01:00:00+00:00 | FMRATE.MSCFD | 90.99  |  <-- timeseries_qc will catch this (Rate-of-change spike)
+| 2026-01-01 02:00:00+00:00 | FMRATE.MSCFD | 12.3   |
+| 2026-01-01 00:00:00+00:00 | OHT.TEMP_F   | 30.2   |
+| 2026-01-01 01:00:00+00:00 | OHT.TEMP_F   | 45.2   |
+| 2026-01-01 02:00:00+00:00 | OHT.TEMP_F   | 6000.2 |  <-- timeseries_qc will catch this (Out of bounds)
+```
+
+**Sample Output - Oil field SCADA data:**
+
+![Oil  field SCADA data quality example](./docs/oil_field_example.png)
+
+
+## Features
+
+- **Four built-in rules** cover ≥80% of real-world bad data: `NullRule`, `FlatlineRule`, `DeltaRule`, `RangeRule`
+- **Timeline chart** (`result.plot()`) — Plotly Gantt-style, one row per tag, Green/Yellow/Red, hover tooltips
+- **YAML config** — non-coders set thresholds in a text file, no Python required
+- **Timestamp health** (`result.check_timestamps()`) — detects gaps, duplicates, non-monotonic, freq drift, DST ambiguity
+- **Self-contained HTML export** (`result.export_report("report.html")`) — offline, no CDN, includes per-issue summary table
+- **Per-issue breakdown** (`result.issue_summary()`) — start/end times, row count, duration, and status for each contiguous bad/sus segment
+- **Pandas-native** — works with any DataFrame that has `timestamp`, `tag_name`, `value` columns
+
+---
+
+## Installation
+
+```bash
+pip install timeseries-qc
+```
+
+---
+
+## Quickstart (5 lines)
+
+```python
+import tsqc
+import pandas as pd
+
+df = pd.read_csv("sensor_data.csv")          # columns: timestamp, tag_name, value
+result = tsqc.check(df, assume_tz="UTC")     # assume_tz required for tz-naive CSVs
+result.plot().show()                          # renders the multi-tag quality timeline
+```
+
+If your CSV already contains tz-aware timestamps (ISO 8601 with `+00:00`), omit `assume_tz`.
+
+---
+
+## YAML Config Example
+
+```yaml
+# tsqc_rules.yaml
+default_rules:
+  - check: null
+    level: bad
+  - check: flatline
+    window: 1h
+    min_delta: 0.001
+    level: sus
+  - check: delta
+    threshold: 50.0
+    level: sus
+
+tag_rules:
+  FOREBAY.LEVEL:
+    - check: range
+      min: 900
+      max: 1100
+      level: bad
+  "GENERATOR.*":
+    - check: range
+      min: 0
+      max: 200
+      level: bad
+    - check: flatline
+      window: 30min
+      min_delta: 0.5   # 0 MW for <30min is valid; longer flatline at non-zero is suspect
+      level: sus
+```
+
+```python
+result = tsqc.check(df, rules="tsqc_rules.yaml")
+result.summary()           # DataFrame: pct_good/sus/bad per tag
+result.issue_summary()     # DataFrame: per-issue runs (start, end, rows, duration)
+result.check_timestamps()  # DataFrame: gap/duplicate/non_monotonic issues
+result.export_report("report.html")  # Full HTML with chart + all tables
+```
+
+---
+
+## Output Schema
+
+`result.df` adds two columns to your DataFrame:
+
+| Column | Values | Notes |
+|--------|--------|-------|
+| `quality` | `"good"`, `"sus"`, `"bad"` | Worst-level rule wins |
+| `quality_reasons` | e.g. `"flatline\|range"` | Pipe-delimited triggered rule names |
+
+---
+
+## Comparison with Alternatives
+
+**Pecos** (Sandia Labs) offers binary pass/fail and has been in maintenance mode since 2021 — no timeline chart and no YAML config. **SaQC** (Helmholtz UFZ) is a rich flagging engine for environmental science but has an environmental-domain API, no timeline visualization, and an LGPL license. **Great Expectations** is not timeseries-native and produces no visualization. `timeseries-qc` is the only library that combines (1) Good/Sus/Bad classification, (2) the multi-tag horizontal status timeline, and (3) YAML-driven configuration in a single `pip install`.
+
+---
+
+## Examples
+
+- [examples/solar_farm.ipynb](examples/solar_farm.ipynb) — solar farm SCADA data with anomaly injection
+- [examples/oilfield.ipynb](examples/oilfield.ipynb) — oil well pad SCADA data with anomaly injection
+
+---
+
+## Known Limitations (v0.1.0)
+
+1. **Pandas only.** PySpark and Polars support are deferred.
+2. **No YAML override of default rules.** Tag-specific rules add to, not replace, default rules.
+3. **Visualization requires Plotly ≥ 5.0.** Matplotlib output not supported.
+4. **`DeltaRule` is point-to-point diff only.** Rolling-window delta is a v0.2 feature.
+
+---
+
+## License
+
+MIT © timeseries-qc contributors

timeseries_qc-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "timeseries-qc"
+version = "0.1.0"
+description = "Classify timeseries rows as Good / Sus / Bad and render a multi-tag quality timeline chart."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["timeseries", "data quality", "QC", "SCADA", "IoT", "pandas"]
+authors = [
+    { name = "timeseries-qc contributors" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas>=1.5",
+    "plotly>=5.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://nagusubra.github.io/timeseries-qc/"
+Repository = "https://github.com/nagusubra/timeseries-qc"
+Issues = "https://github.com/nagusubra/timeseries-qc/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+    "mypy>=1.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tsqc*"]
+exclude = ["synthetic_data_generation*", "examples*", "tests*"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+strict = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short"
+
+[tool.coverage.run]
+source = ["tsqc"]
+omit = ["tests/*"]

timeseries_qc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

timeseries_qc-0.1.0/tests/test_checker.py

@@ -0,0 +1,183 @@
+"""End-to-end tests for tsqc.check() (tsqc/checker.py)."""
+
+import numpy as np
+import pandas as pd
+import pytest
+
+import tsqc
+from tsqc.rules.builtins import CustomRule, NullRule, RangeRule
+
+
+def _utc_df(n=50, tag="SENSOR_A", with_nan=True, with_spike=True):
+    ts = pd.date_range("2026-01-01", periods=n, freq="1min", tz="UTC")
+    rng = np.random.default_rng(0)
+    vals = 10.0 + rng.normal(0, 0.5, n)
+    if with_nan:
+        vals[5] = float("nan")
+    if with_spike:
+        vals[20] = 999.0
+    df = pd.DataFrame({"timestamp": ts, "tag_name": tag, "value": vals})
+    return df
+
+
+# ─────────────────────────────  Basic  ─────────────────────────────────────
+
+class TestCheckBasic:
+    def test_returns_qcresult(self, single_tag_df):
+        result = tsqc.check(single_tag_df)
+        assert isinstance(result, tsqc.QCResult)
+
+    def test_output_has_quality_columns(self, single_tag_df):
+        result = tsqc.check(single_tag_df)
+        assert "quality" in result.df.columns
+        assert "quality_reasons" in result.df.columns
+
+    def test_quality_values_valid(self, single_tag_df):
+        result = tsqc.check(single_tag_df)
+        assert set(result.df["quality"].unique()).issubset({"good", "sus", "bad"})
+
+    def test_does_not_modify_original(self, single_tag_df):
+        original_cols = list(single_tag_df.columns)
+        tsqc.check(single_tag_df)
+        assert list(single_tag_df.columns) == original_cols
+
+    def test_row_count_preserved(self, single_tag_df):
+        result = tsqc.check(single_tag_df)
+        assert len(result.df) == len(single_tag_df)
+
+
+# ─────────────────────────────  Multi-tag  ─────────────────────────────────
+
+class TestCheckMultiTag:
+    def test_multi_tag_all_tags_present(self, multi_tag_df):
+        result = tsqc.check(multi_tag_df)
+        assert set(result.df["tag_name"].unique()) == {"TAG_A", "TAG_B", "TAG_C"}
+
+    def test_multi_tag_quality_column_populated(self, multi_tag_df):
+        result = tsqc.check(multi_tag_df)
+        assert result.df["quality"].notna().all()
+
+
+# ─────────────────────────────  quality_reasons  ───────────────────────────
+
+class TestQualityReasons:
+    def test_null_reason_set(self):
+        df = _utc_df(with_nan=True, with_spike=False)
+        result = tsqc.check(df, rules=[NullRule()])
+        nan_row = result.df[result.df["value"].isna()]
+        assert "null" in nan_row["quality_reasons"].iloc[0]
+
+    def test_pipe_delimited_multiple_reasons(self):
+        df = _utc_df(with_nan=True, with_spike=False)
+        rules = [
+            NullRule(level="bad"),
+            CustomRule(fn=lambda s: s.isna(), name="also_null", level="sus"),
+        ]
+        result = tsqc.check(df, rules=rules)
+        nan_row = result.df[result.df["value"].isna()]
+        reasons = nan_row["quality_reasons"].iloc[0]
+        assert "|" in reasons
+        assert "null" in reasons
+        assert "also_null" in reasons
+
+    def test_good_rows_have_empty_reasons(self):
+        df = _utc_df(with_nan=False, with_spike=False, n=10)
+        result = tsqc.check(df, rules=[NullRule()])
+        assert (result.df["quality_reasons"] == "").all()
+
+
+# ─────────────────────────────  Custom rules  ──────────────────────────────
+
+class TestCheckCustomRules:
+    def test_custom_rule_list_applied(self):
+        df = _utc_df(with_nan=False, with_spike=True)
+        rules = [RangeRule(min_val=0.0, max_val=100.0, level="bad")]
+        result = tsqc.check(df, rules=rules)
+        bad_rows = result.df[result.df["quality"] == "bad"]
+        # Spike at value=999 should be flagged
+        assert len(bad_rows) >= 1
+
+
+# ─────────────────────────────  Error handling  ────────────────────────────
+
+class TestCheckErrors:
+    def test_missing_value_column_raises(self):
+        df = pd.DataFrame(
+            {"timestamp": pd.date_range("2026-01-01", periods=3, freq="1min", tz="UTC")}
+        )
+        with pytest.raises(ValueError, match="value"):
+            tsqc.check(df)
+
+    def test_missing_timestamp_column_raises(self):
+        df = pd.DataFrame({"value": [1.0, 2.0]})
+        with pytest.raises(ValueError, match="timestamp"):
+            tsqc.check(df)
+
+    def test_tz_naive_without_assume_tz_raises(self):
+        ts = pd.date_range("2026-01-01", periods=5, freq="1min")  # tz-naive
+        df = pd.DataFrame(
+            {"timestamp": ts, "tag_name": "T", "value": [1.0] * 5}
+        )
+        with pytest.raises(ValueError, match="assume_tz"):
+            tsqc.check(df)
+
+    def test_tz_naive_with_assume_tz_utc_succeeds(self):
+        ts = pd.date_range("2026-01-01", periods=5, freq="1min")  # tz-naive
+        df = pd.DataFrame({"timestamp": ts, "tag_name": "T", "value": [1.0] * 5})
+        result = tsqc.check(df, assume_tz="UTC")
+        assert result.df["timestamp"].dt.tz is not None
+        assert str(result.df["timestamp"].dt.tz) == "UTC"
+
+    def test_invalid_assume_tz_raises(self):
+        ts = pd.date_range("2026-01-01", periods=3, freq="1min")
+        df = pd.DataFrame({"timestamp": ts, "tag_name": "T", "value": [1.0] * 3})
+        with pytest.raises(ValueError, match="IANA"):
+            tsqc.check(df, assume_tz="NotATimezone/Bogus")
+
+    def test_tz_aware_non_utc_converted_to_utc(self):
+        ts = pd.date_range("2026-01-01", periods=5, freq="1min", tz="America/Chicago")
+        df = pd.DataFrame({"timestamp": ts, "tag_name": "T", "value": [1.0] * 5})
+        result = tsqc.check(df)
+        assert str(result.df["timestamp"].dt.tz) == "UTC"
+
+
+# ─────────────────────────────  No tag column  ─────────────────────────────
+
+class TestCheckNoTagCol:
+    def test_single_tag_no_tag_col(self):
+        ts = pd.date_range("2026-01-01", periods=10, freq="1min", tz="UTC")
+        df = pd.DataFrame({"timestamp": ts, "value": list(range(10))})
+        result = tsqc.check(df, tag_col=None)
+        assert "quality" in result.df.columns
+
+    def test_summary_with_no_tag_col(self):
+        ts = pd.date_range("2026-01-01", periods=10, freq="1min", tz="UTC")
+        df = pd.DataFrame({"timestamp": ts, "value": list(range(10))})
+        result = tsqc.check(df, tag_col=None)
+        summary = result.summary()
+        assert "tag_name" in summary.columns
+        assert len(summary) == 1
+
+
+# ─────────────────────────────  summary()  ─────────────────────────────────
+
+class TestSummary:
+    def test_summary_columns(self, single_tag_df):
+        result = tsqc.check(single_tag_df)
+        summary = result.summary()
+        expected_cols = {"tag_name", "total_rows", "pct_good", "pct_sus", "pct_bad",
+                         "n_good", "n_sus", "n_bad"}
+        assert expected_cols.issubset(set(summary.columns))
+
+    def test_summary_pcts_sum_to_100(self, single_tag_df):
+        result = tsqc.check(single_tag_df)
+        summary = result.summary()
+        for _, row in summary.iterrows():
+            total = row["pct_good"] + row["pct_sus"] + row["pct_bad"]
+            assert abs(total - 100.0) < 0.5, f"Percentages don't sum to 100 for {row['tag_name']}"
+
+    def test_summary_sorted_by_pct_bad(self, multi_tag_df):
+        result = tsqc.check(multi_tag_df)
+        summary = result.summary()
+        pct_bad_values = list(summary["pct_bad"])
+        assert pct_bad_values == sorted(pct_bad_values, reverse=True)