battery-data-steward 0.4.0__py3-none-any.whl

battery_data_standard/__init__.py

@@ -0,0 +1,99 @@
+"""Battery Data Steward: battery data inspection, QA, and preprocessing."""
+
+from ._version import __version__
+from .api import (
+    batch_convert,
+    convert,
+    convert_eis,
+    convert_neware_groups,
+    detect,
+    detect_kind,
+    group_neware_files,
+    list_export_targets,
+    list_supported_formats,
+    read,
+    read_eis,
+    read_with_report,
+    validate_eis,
+    validate_file,
+)
+from .audit import AuditRecord, AuditReport, audit, audit_file
+from .diagnostics import ExplainReport, explain
+from .doctor import DoctorReport, doctor
+from .exceptions import (
+    AmbiguousDetectionError,
+    BatteryDataStandardError,
+    ConversionError,
+    DetectionError,
+    FileIOError,
+    UnsupportedFeatureError,
+    UnsupportedFormatError,
+    ValidationFailed,
+)
+from .export import to_export_frame
+from .inspection import InspectionReport, inspect
+from .reporting import (
+    render_explain_html,
+    write_conversion_report,
+    write_conversion_reports,
+    write_explain_report,
+    write_explain_reports,
+    write_inspection_report,
+    write_inspection_reports,
+)
+from .reports import ConversionReport, DetectionResult, ValidationReport
+from .schema import BDF_SCHEMA_VERSION, BDS_SCHEMA_VERSION
+from .summary import summarize_cycles, summarize_steps
+from .validation import validate
+
+__all__ = [
+    "AmbiguousDetectionError",
+    "AuditRecord",
+    "AuditReport",
+    "BDF_SCHEMA_VERSION",
+    "BDS_SCHEMA_VERSION",
+    "BatteryDataStandardError",
+    "ConversionReport",
+    "ConversionError",
+    "DetectionResult",
+    "DetectionError",
+    "DoctorReport",
+    "ExplainReport",
+    "InspectionReport",
+    "FileIOError",
+    "UnsupportedFeatureError",
+    "UnsupportedFormatError",
+    "ValidationFailed",
+    "ValidationReport",
+    "__version__",
+    "batch_convert",
+    "audit",
+    "audit_file",
+    "convert",
+    "convert_eis",
+    "convert_neware_groups",
+    "detect",
+    "detect_kind",
+    "doctor",
+    "explain",
+    "group_neware_files",
+    "inspect",
+    "list_export_targets",
+    "list_supported_formats",
+    "read",
+    "read_eis",
+    "read_with_report",
+    "render_explain_html",
+    "summarize_cycles",
+    "summarize_steps",
+    "to_export_frame",
+    "validate",
+    "validate_file",
+    "validate_eis",
+    "write_explain_report",
+    "write_explain_reports",
+    "write_inspection_report",
+    "write_inspection_reports",
+    "write_conversion_report",
+    "write_conversion_reports",
+]

battery_data_standard/__main__.py

@@ -0,0 +1,5 @@
+"""Run the CLI with ``python -m battery_data_standard``."""
+
+from .cli import main
+
+raise SystemExit(main())

battery_data_standard/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.4.0"

battery_data_standard/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapter registry exports."""
+
+from .registry import all_adapters, detect_adapter, get_adapter
+
+__all__ = ["all_adapters", "detect_adapter", "get_adapter"]

battery_data_standard/adapters/arbin.py

@@ -0,0 +1,84 @@
+"""Arbin cycler adapter."""
+
+from __future__ import annotations
+
+from .generic import GenericAdapter
+
+
+class ArbinAdapter(GenericAdapter):
+    id = "arbin"
+    display_name = "Arbin"
+    adapter_version = "1"
+    support_tier = "fixture-backed"
+    evidence_tier = "public-fixture-backed"
+    raw_current_sign = "charge-positive"
+    signatures = (
+        "arbin",
+        "cycle index",
+        "cycle_index",
+        "step index",
+        "step_index",
+        "test time",
+        "test_time",
+        "data point",
+        "data_point",
+        "date_time",
+        "charge_capacity",
+        "discharge_capacity",
+        "statisticbystep",
+        "statisticbycycle",
+    )
+    column_aliases = {
+        "test_time_s": (
+            "Test_Time",
+            "Test Time (s)",
+            "Test Time (min)",
+            "Test Time (h)",
+            "Test Time",
+            "Test_Time(s)",
+            "TestTime(s)",
+        ),
+        "date_time": ("DateTime", "Date Time", "Date_Time", "Date_Time                    "),
+        "step_time_s": (
+            "Step_Time",
+            "Step Time (s)",
+            "Step Time (min)",
+            "Step Time (h)",
+            "Step_Time(s)",
+            "StepTime(s)",
+        ),
+        "cycle_index": ("Cycle_Index", "Cycle Index"),
+        "step_index": ("Step_Index", "Step Index"),
+        "record_index": ("Data_Point", "Data Point", "DataPoint"),
+        "current_a": ("Current", "Current (A)", "Current(A)", "Current_mA", "Current (mA)"),
+        "voltage_v": ("Voltage", "Voltage (V)", "Voltage(V)"),
+        "charge_capacity_ah": ("Charge_Capacity", "Charge Capacity (Ah)", "Charge_Capacity(Ah)"),
+        "discharge_capacity_ah": (
+            "Discharge_Capacity",
+            "Discharge Capacity (Ah)",
+            "Discharge_Capacity(Ah)",
+        ),
+        "charge_energy_wh": ("Charge_Energy", "Charge Energy (Wh)", "Charge_Energy(Wh)"),
+        "discharge_energy_wh": ("Discharge_Energy", "Discharge Energy (Wh)", "Discharge_Energy(Wh)"),
+        "power_w": ("Power", "Power (W)", "Power(W)"),
+        "internal_resistance_ohm": (
+            "Internal_Resistance",
+            "Internal Resistance",
+            "Internal Resistance (Ohm)",
+            "ACR (Ohm)",
+            "IR (Ohms)",
+        ),
+        "ambient_temperature_deg_c": (
+            "Temperature",
+            "Aux_Temperature_1 (C)",
+            "Aux_Temperature_1(C)",
+            "Aux_Temperature(C)_1",
+            "Aux_Temperature(degC)_1",
+            "Aux_Temperature(°C)_1",
+            "Aux_Temperature(°C)_1",
+            "Aux_Temperature(Ąć)_1",
+            "Aux_Temperature(¡æ)_1",
+            "Aux_Temperature_2 (C)",
+            "Aux_Temperature_2(C)",
+        ),
+    }

battery_data_standard/adapters/base.py

@@ -0,0 +1,124 @@
+"""Adapter base classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+from ..reports import ColumnProvenance, DetectionResult
+
+
+@dataclass
+class AdapterResult:
+    data: pl.DataFrame
+    warnings: list[str] = field(default_factory=list)
+    provenance: list[ColumnProvenance] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Adapter:
+    id = "abstract"
+    display_name = "Abstract"
+    adapter_version = "1"
+    support_tier = "best_effort"
+    evidence_tier = "best-effort"
+    extensions: tuple[str, ...] = ()
+    signatures: tuple[str, ...] = ()
+    column_aliases: dict[str, tuple[str, ...]] = {}
+    raw_current_sign: str = "unknown"
+
+    def sniff(self, path: Path, sample: str) -> DetectionResult:
+        common_table_suffixes = {".csv", ".txt", ".tsv", ".xlsx", ".xls", ".mat", ".parquet"}
+        suffix = path.suffix.lower()
+        suffix_score = (
+            0.1
+            if (not self.extensions or suffix in self.extensions) and suffix not in common_table_suffixes
+            else 0.0
+        )
+        sample_lower = sample.lower()
+        hits = [token for token in self.signatures if token.lower() in sample_lower]
+        confidence = suffix_score + min(0.8, 0.2 * len(hits))
+        reason = "signature match" if hits else "extension fallback"
+        return DetectionResult(self.id, confidence, reason)
+
+    def read_raw(self, path: Path, options: dict[str, Any] | None = None) -> pl.DataFrame:
+        raise NotImplementedError
+
+    def read_raw_with_metadata(self, path: Path, options: dict[str, Any] | None = None) -> AdapterResult:
+        return AdapterResult(self.read_raw(path, options=options))
+
+    def normalize(
+        self,
+        raw: pl.DataFrame,
+        *,
+        profile: dict[str, Any] | None = None,
+        strict: bool = True,
+        keep_raw: bool = False,
+        current_sign: str = "charge-positive",
+        repair_policy: str = "warn",
+    ) -> AdapterResult:
+        from .normalization import normalize_raw_frame
+
+        return normalize_raw_frame(
+            raw,
+            adapter_id=self.id,
+            aliases=self.column_aliases,
+            profile=profile,
+            strict=strict,
+            keep_raw=keep_raw,
+            current_sign=current_sign,
+            raw_current_sign=self.raw_current_sign,
+        )
+
+    def repair(self, data: pl.DataFrame, *, repair_policy: str = "warn") -> AdapterResult:
+        from .normalization import repair_bds_frame
+
+        df, warnings = repair_bds_frame(data, policy=repair_policy)
+        return AdapterResult(df, warnings=warnings, metadata={"repair_operations": list(warnings)})
+
+    def extract_metadata(self, raw: pl.DataFrame) -> dict[str, Any]:
+        return {"source_adapter": self.id, "raw_columns": list(raw.columns)}
+
+    def process(
+        self,
+        path: Path,
+        *,
+        profile: dict[str, Any] | None = None,
+        strict: bool = True,
+        keep_raw: bool = False,
+        current_sign: str = "charge-positive",
+        repair_policy: str = "warn",
+        options: dict[str, Any] | None = None,
+    ) -> AdapterResult:
+        raw_result = self.read_raw_with_metadata(path, options=options)
+        raw = raw_result.data
+        normalized = self.normalize(
+            raw,
+            profile=profile,
+            strict=strict,
+            keep_raw=keep_raw,
+            current_sign=current_sign,
+            repair_policy=repair_policy,
+        )
+        repaired = self.repair(normalized.data, repair_policy=repair_policy)
+        normalized.data = repaired.data
+        normalized.warnings[:0] = raw_result.warnings
+        normalized.warnings.extend(repaired.warnings)
+        normalized.metadata.update(raw_result.metadata)
+        normalized.metadata.update(self.extract_metadata(raw))
+        normalized.metadata.update(repaired.metadata)
+        normalized.metadata.update(
+            {
+                "source_backend": "native",
+                "raw_current_sign": self.raw_current_sign,
+                "repair_policy": repair_policy,
+                "adapter_version": self.adapter_version,
+                "support_tier": self.support_tier,
+                "evidence_tier": self.evidence_tier,
+                "output_rows": normalized.data.height,
+            }
+        )
+        return normalized

battery_data_standard/adapters/basytec.py

@@ -0,0 +1,88 @@
+"""BaSyTec cycler adapter."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+from ..io import read_table_with_metadata, read_text
+from .base import AdapterResult
+from .generic import GenericAdapter
+
+
+class BasytecAdapter(GenericAdapter):
+    id = "basytec"
+    display_name = "BaSyTec"
+    adapter_version = "1"
+    support_tier = "fixture-backed"
+    evidence_tier = "public-fixture-backed"
+    raw_current_sign = "charge-positive"
+    signatures = ("basytec", "run_time", "c_vol", "c_cur", "~time[h]", "u[v]", "i[a]")
+    column_aliases = {
+        "test_time_s": ("run_time", "time", "~Time[h]", "Time[h]", "Time[s]"),
+        "step_time_s": ("t-Step[h]", "t-Set[h]"),
+        "voltage_v": ("c_vol", "voltage", "U[V]", "U_Battery"),
+        "current_a": ("c_cur", "current", "I[A]", "I_Battery"),
+        "cycle_index": ("Cyc-Count", "Cycle", "CycCount"),
+        "step_index": ("Line", "Step", "Command"),
+        "ambient_temperature_deg_c": (
+            "c_temp",
+            "c_surf_temp",
+            "amb_temp",
+            "temperature",
+            "T1[°C]",
+            "T1[癈]",
+        ),
+        "charge_capacity_ah": ("ah_ch", "Ah[Ah]"),
+        "discharge_capacity_ah": ("ah_dch",),
+    }
+
+    def read_raw_with_metadata(self, path: Path, options: dict[str, Any] | None = None) -> AdapterResult:
+        result = read_table_with_metadata(path, options=options)
+        metadata = dict(result.metadata)
+        data = result.data
+
+        try:
+            text, _encoding = read_text(path)
+        except OSError:
+            text = ""
+        start = _parse_basytec_start_time(text)
+        if start is not None:
+            metadata["basytec_start_of_test"] = start.isoformat()
+            data = _add_datetime_column(data, start)
+
+        return AdapterResult(data, metadata=metadata)
+
+
+def _parse_basytec_start_time(text: str) -> datetime | None:
+    for line in text.splitlines()[:80]:
+        if "start of test" not in line.lower():
+            continue
+        _label, _sep, value = line.partition(":")
+        value = value.strip()
+        for fmt in ("%d.%m.%Y %H:%M:%S", "%Y-%m-%d %H:%M:%S", "%m/%d/%Y %H:%M:%S"):
+            try:
+                return datetime.strptime(value, fmt)
+            except ValueError:
+                continue
+    return None
+
+
+def _add_datetime_column(data: pl.DataFrame, start: datetime) -> pl.DataFrame:
+    if data.is_empty() or "DateTime" in data.columns:
+        return data
+    source = next(
+        (column for column in ("~Time[h]", "Time[h]", "Time[s]", "run_time") if column in data.columns), None
+    )
+    if source is None:
+        return data
+    factor = 3600.0 if "[h]" in source.lower() else 1.0
+    offsets = data[source].cast(pl.Float64, strict=False).to_list()
+    values = [
+        None if value is None else (start + timedelta(seconds=float(value) * factor)).isoformat()
+        for value in offsets
+    ]
+    return data.with_columns(pl.Series("DateTime", values))

battery_data_standard/adapters/biologic.py

@@ -0,0 +1,246 @@
+"""BioLogic EC-Lab adapter."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+from ..io import read_table_with_metadata, read_text
+from ..reports import ColumnProvenance
+from ..schema import ALL_COLUMNS
+from .base import AdapterResult
+from .generic import GenericAdapter
+
+
+class BiologicAdapter(GenericAdapter):
+    id = "biologic"
+    display_name = "BioLogic"
+    adapter_version = "1"
+    support_tier = "fixture-backed"
+    evidence_tier = "public-fixture-backed"
+    raw_current_sign = "charge-positive"
+    extensions = (".mpt", ".mpr", ".txt", ".csv")
+    signatures = ("biologic", "ec-lab", "time/s", "ewe/v", "ecell/v", "i/ma", "nb header lines")
+    column_aliases = {
+        "test_time_s": ("time/s", "time/s.", "Time/s"),
+        "step_time_s": ("step time/s", "Step time/s", "step_time/s"),
+        "voltage_v": ("Ewe/V", "Ecell/V", "Ewe/V vs.", "<Ewe>/V", "Ecell_V", "Ewe_V"),
+        "current_a": ("I/mA", "<I>/mA", "I/A", "<I>/A", "I_mA", "I_A"),
+        "cycle_index": ("cycle number",),
+        "step_index": ("Ns",),
+        "charge_capacity_ah": ("Q charge/mA.h",),
+        "discharge_capacity_ah": ("Q discharge/mA.h",),
+        "charge_energy_wh": ("Energy charge/W.h", "Energy charge/mW.h"),
+        "discharge_energy_wh": ("Energy discharge/W.h", "Energy discharge/mW.h"),
+        "power_w": ("P/W",),
+        "internal_resistance_ohm": ("R/Ohm", "Rapp/Ohm"),
+        "ambient_temperature_deg_c": ("Temperature/°C", "Temperature/degC", "Temperature/°C", "T/°C"),
+    }
+
+    def read_raw(self, path: Path, options: dict[str, Any] | None = None) -> pl.DataFrame:
+        return super().read_raw(path, options=options)
+
+    def read_raw_with_metadata(self, path: Path, options: dict[str, Any] | None = None) -> AdapterResult:
+        result = read_table_with_metadata(path, options=options)
+        metadata = dict(result.metadata)
+        if path.suffix.lower() in {".mpt", ".txt", ".csv"}:
+            text, _encoding = read_text(path)
+            metadata.update(_parse_biologic_header_metadata(text))
+        return AdapterResult(result.data, metadata=metadata)
+
+    def normalize(
+        self,
+        raw: pl.DataFrame,
+        *,
+        profile: dict[str, Any] | None = None,
+        strict: bool = True,
+        keep_raw: bool = False,
+        current_sign: str = "charge-positive",
+        repair_policy: str = "warn",
+    ) -> AdapterResult:
+        result = super().normalize(
+            raw,
+            profile=profile,
+            strict=strict,
+            keep_raw=keep_raw,
+            current_sign=current_sign,
+            repair_policy=repair_policy,
+        )
+        return _replace_step_time_within_step(result)
+
+    def process(
+        self,
+        path: Path,
+        *,
+        profile: dict[str, Any] | None = None,
+        strict: bool = True,
+        keep_raw: bool = False,
+        current_sign: str = "charge-positive",
+        repair_policy: str = "warn",
+        options: dict[str, Any] | None = None,
+    ) -> AdapterResult:
+        raw_result = self.read_raw_with_metadata(path, options=options)
+        raw = raw_result.data
+        normalized = self.normalize(
+            raw,
+            profile=profile,
+            strict=strict,
+            keep_raw=keep_raw,
+            current_sign=current_sign,
+            repair_policy=repair_policy,
+        )
+        repaired = self.repair(normalized.data, repair_policy=repair_policy)
+        normalized.data = repaired.data
+        _append_datetime_from_acquisition_start(normalized, raw_result.metadata)
+        normalized.warnings[:0] = raw_result.warnings
+        normalized.warnings.extend(repaired.warnings)
+        normalized.metadata.update(raw_result.metadata)
+        normalized.metadata.update(self.extract_metadata(raw))
+        normalized.metadata.update(repaired.metadata)
+        normalized.metadata.update(
+            {
+                "source_backend": "native",
+                "raw_current_sign": self.raw_current_sign,
+                "repair_policy": repair_policy,
+                "adapter_version": self.adapter_version,
+                "support_tier": self.support_tier,
+                "evidence_tier": self.evidence_tier,
+                "output_rows": normalized.data.height,
+            }
+        )
+        return normalized
+
+
+def _parse_biologic_header_metadata(text: str) -> dict[str, Any]:
+    metadata: dict[str, Any] = {}
+    header_lines: list[str] = []
+    for line in text.splitlines()[:250]:
+        if "time/s" in line.lower() and ("ewe/v" in line.lower() or "ecell/v" in line.lower()):
+            break
+        header_lines.append(line)
+
+    for line in header_lines:
+        key, separator, value = line.partition(":")
+        if not separator:
+            continue
+        clean_key = re.sub(r"\s+", " ", key).strip().lower()
+        clean_value = value.strip()
+        if not clean_value:
+            continue
+        if clean_key == "acquisition started on":
+            started = _parse_biologic_datetime(clean_value)
+            if started is not None:
+                metadata["biologic_acquisition_started_at"] = started.isoformat(timespec="milliseconds")
+                metadata["biologic_acquisition_started_at_raw"] = clean_value
+                metadata["biologic_datetime_timezone"] = "unspecified"
+        elif clean_key == "technique started on":
+            started = _parse_biologic_datetime(clean_value)
+            if started is not None:
+                metadata["biologic_technique_started_at"] = started.isoformat(timespec="milliseconds")
+                metadata["biologic_technique_started_at_raw"] = clean_value
+        elif clean_key in {
+            "device",
+            "ec-lab for windows v11.36 (software)",
+            "internet server v11.36 (firmware)",
+            "command interpretor v11.36 (firmware)",
+            "electrode material",
+            "comments",
+            "current amplifier",
+        }:
+            metadata[f"biologic_{clean_key.replace(' ', '_')}"] = clean_value
+    return metadata
+
+
+def _parse_biologic_datetime(value: str) -> datetime | None:
+    value = value.strip()
+    for fmt in (
+        "%m/%d/%Y %H:%M:%S.%f",
+        "%m/%d/%Y %H:%M:%S",
+        "%m/%d/%Y",
+        "%d/%m/%Y %H:%M:%S.%f",
+        "%d/%m/%Y %H:%M:%S",
+        "%d/%m/%Y",
+    ):
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _replace_step_time_within_step(result: AdapterResult) -> AdapterResult:
+    df = result.data
+    if df.is_empty() or "test_time_s" not in df.columns or "step_index" not in df.columns:
+        return result
+
+    test_times = df["test_time_s"].cast(pl.Float64, strict=False).to_list()
+    step_counts = df["step_index"].to_list()
+    step_times: list[float | None] = []
+    current_step: Any = object()
+    step_start: float | None = None
+
+    for test_time, step_count in zip(test_times, step_counts, strict=True):
+        if test_time is None:
+            step_times.append(None)
+            continue
+        value = float(test_time)
+        if step_start is None or step_count != current_step or value < step_start:
+            current_step = step_count
+            step_start = value
+        step_times.append(value - step_start)
+
+    df = df.with_columns(pl.Series("step_time_s", step_times, dtype=pl.Float64))
+    result.data = _select_existing_bds_order(df)
+    result.provenance = [item for item in result.provenance if item.column != "step_time_s"]
+    result.provenance.append(
+        ColumnProvenance(
+            "step_time_s",
+            "time/s|Ns",
+            source_unit="s",
+            transform="derived elapsed seconds within consecutive BioLogic Ns step",
+        )
+    )
+    mapped = set(result.metadata.get("mapped_columns", []))
+    mapped.update({"time/s", "Ns"})
+    result.metadata["mapped_columns"] = sorted(mapped)
+    result.metadata["biologic_step_time_source"] = "derived_from_test_time_and_Ns"
+    return result
+
+
+def _append_datetime_from_acquisition_start(result: AdapterResult, metadata: dict[str, Any]) -> None:
+    if "date_time" in result.data.columns or "test_time_s" not in result.data.columns:
+        return
+    start_value = metadata.get("biologic_acquisition_started_at")
+    if not start_value:
+        return
+    try:
+        start = datetime.fromisoformat(str(start_value))
+    except ValueError:
+        return
+
+    offsets = result.data["test_time_s"].cast(pl.Float64, strict=False).to_list()
+    values = [
+        None
+        if offset is None
+        else (start + timedelta(milliseconds=round(float(offset) * 1000))).isoformat(timespec="milliseconds")
+        for offset in offsets
+    ]
+    result.data = _select_existing_bds_order(result.data.with_columns(pl.Series("date_time", values)))
+    result.provenance.append(
+        ColumnProvenance(
+            "date_time",
+            "Acquisition started on|test_time_s",
+            transform="derived local timestamp from BioLogic header start time plus elapsed seconds",
+        )
+    )
+    result.metadata["biologic_datetime_derived"] = True
+
+
+def _select_existing_bds_order(df: pl.DataFrame) -> pl.DataFrame:
+    ordered = [column for column in ALL_COLUMNS if column in df.columns]
+    ordered.extend(column for column in df.columns if column not in set(ordered))
+    return df.select(ordered)