battery-feature-lab 0.1.0__tar.gz

battery_feature_lab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BFL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

battery_feature_lab-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: battery-feature-lab
+Version: 0.1.0
+Summary: Feature extraction pipeline for battery cycling, BDS exports, and LLM-ready battery diagnostics.
+Author: BFL contributors
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: pyarrow>=10.0
+Provides-Extra: explain
+Requires-Dist: shap>=0.43; extra == "explain"
+Requires-Dist: xgboost>=1.7; extra == "explain"
+Requires-Dist: lightgbm>=4.0; extra == "explain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# BFL: Battery Feature Lab
+
+BFL extracts battery cycling features from BDS-style exports and common cycler tables. It turns
+raw time-series data into feature tables for SOH/RUL modeling, feature screening, explainability,
+and compact diagnostic summaries.
+
+## Features
+
+- Cycle summaries: capacity, energy, efficiency, C-rate, voltage, temperature, and rest time.
+- Early-life curve features: `Delta Q(V)` variance, norms, quantiles, and related statistics.
+- ICA/DVA features: `dQ/dV` and `dV/dQ` peaks, locations, widths, heights, and areas.
+- Relaxation features: voltage drop, slopes, interpolated voltages, and exponential fits.
+- Stress features: SOC, voltage, current, C-rate, temperature histograms, and high-SOC rest time.
+- EIS descriptors when impedance columns are available.
+- Rule-based degradation tags for LLI, LAM_PE, LAM_NE, resistance growth, and related evidence.
+- LLM-ready JSONL summaries for downstream review or diagnostic workflows.
+
+## Installation
+
+From PyPI, after the package is published:
+
+```bash
+pip install battery-feature-lab
+```
+
+From a local checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+bfl extract input.csv --output-dir out --cell-id cell_001 --nominal-capacity-ah 1.1
+```
+
+The longer command name is also available:
+
+```bash
+battery-features extract input.csv --output-dir out --cell-id cell_001 --nominal-capacity-ah 1.1
+```
+
+Diagnostic thresholds are configurable:
+
+```bash
+bfl extract input.csv \
+  --output-dir out \
+  --nominal-capacity-ah 1.1 \
+  --datasheet-max-discharge-c-rate 5 \
+  --high-soc-rest-threshold 0.25
+```
+
+## Input Data
+
+BFL accepts CSV, TSV, JSON, JSONL, and Parquet files. Input data can use common cycler/BDS
+column names. The reader normalizes aliases to:
+
+```text
+time_s, voltage_v, current_a, temperature_c, charge_capacity_ah,
+discharge_capacity_ah, cycle_index, step_index, step_type
+```
+
+At minimum, the input should contain time, voltage, current, and enough cycle/step information
+to identify charge, discharge, and rest periods. If `cell_id`, `cycle_index`, or `step_type` is
+missing, BFL can infer or fill parts of the schema from the file name, current sign, and command
+line options.
+
+Optional EIS columns are:
+
+```text
+frequency_hz, z_real_ohm, z_imag_ohm
+```
+
+## Outputs
+
+BFL writes non-empty tables to the selected output directory:
+
+```text
+out/
+  normalized_timeseries.parquet
+  cycle_features.parquet
+  delta_q_features.parquet
+  ica_dva_features.parquet
+  relaxation_features.parquet
+  stress_features.parquet
+  degradation_tags.parquet
+  llm_context.jsonl
+  run_metadata.json
+```
+
+## Validation
+
+Run the offline self-test:
+
+```bash
+python scripts/validate_on_dataset.py --synthetic 12
+```
+
+Run validation on a folder of per-cell CSV files:
+
+```bash
+python scripts/validate_on_dataset.py --data-dir path/to/cells --nominal-capacity-ah 1.1
+```
+
+## Python Usage
+
+```python
+from pathlib import Path
+
+from battery_feature_lab.pipeline import FeaturePipeline, PipelineConfig
+from battery_feature_lab.schemas import ExportConfig, FeatureConfig, ReaderConfig
+
+pipeline = FeaturePipeline(
+    PipelineConfig(
+        reader=ReaderConfig(cell_id="cell_001"),
+        features=FeatureConfig(nominal_capacity_ah=1.1),
+        export=ExportConfig(output_dir=Path("out")),
+    )
+)
+
+tables = pipeline.run("input.csv")
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check .
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

battery_feature_lab-0.1.0/README.md

@@ -0,0 +1,135 @@
+# BFL: Battery Feature Lab
+
+BFL extracts battery cycling features from BDS-style exports and common cycler tables. It turns
+raw time-series data into feature tables for SOH/RUL modeling, feature screening, explainability,
+and compact diagnostic summaries.
+
+## Features
+
+- Cycle summaries: capacity, energy, efficiency, C-rate, voltage, temperature, and rest time.
+- Early-life curve features: `Delta Q(V)` variance, norms, quantiles, and related statistics.
+- ICA/DVA features: `dQ/dV` and `dV/dQ` peaks, locations, widths, heights, and areas.
+- Relaxation features: voltage drop, slopes, interpolated voltages, and exponential fits.
+- Stress features: SOC, voltage, current, C-rate, temperature histograms, and high-SOC rest time.
+- EIS descriptors when impedance columns are available.
+- Rule-based degradation tags for LLI, LAM_PE, LAM_NE, resistance growth, and related evidence.
+- LLM-ready JSONL summaries for downstream review or diagnostic workflows.
+
+## Installation
+
+From PyPI, after the package is published:
+
+```bash
+pip install battery-feature-lab
+```
+
+From a local checkout:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+bfl extract input.csv --output-dir out --cell-id cell_001 --nominal-capacity-ah 1.1
+```
+
+The longer command name is also available:
+
+```bash
+battery-features extract input.csv --output-dir out --cell-id cell_001 --nominal-capacity-ah 1.1
+```
+
+Diagnostic thresholds are configurable:
+
+```bash
+bfl extract input.csv \
+  --output-dir out \
+  --nominal-capacity-ah 1.1 \
+  --datasheet-max-discharge-c-rate 5 \
+  --high-soc-rest-threshold 0.25
+```
+
+## Input Data
+
+BFL accepts CSV, TSV, JSON, JSONL, and Parquet files. Input data can use common cycler/BDS
+column names. The reader normalizes aliases to:
+
+```text
+time_s, voltage_v, current_a, temperature_c, charge_capacity_ah,
+discharge_capacity_ah, cycle_index, step_index, step_type
+```
+
+At minimum, the input should contain time, voltage, current, and enough cycle/step information
+to identify charge, discharge, and rest periods. If `cell_id`, `cycle_index`, or `step_type` is
+missing, BFL can infer or fill parts of the schema from the file name, current sign, and command
+line options.
+
+Optional EIS columns are:
+
+```text
+frequency_hz, z_real_ohm, z_imag_ohm
+```
+
+## Outputs
+
+BFL writes non-empty tables to the selected output directory:
+
+```text
+out/
+  normalized_timeseries.parquet
+  cycle_features.parquet
+  delta_q_features.parquet
+  ica_dva_features.parquet
+  relaxation_features.parquet
+  stress_features.parquet
+  degradation_tags.parquet
+  llm_context.jsonl
+  run_metadata.json
+```
+
+## Validation
+
+Run the offline self-test:
+
+```bash
+python scripts/validate_on_dataset.py --synthetic 12
+```
+
+Run validation on a folder of per-cell CSV files:
+
+```bash
+python scripts/validate_on_dataset.py --data-dir path/to/cells --nominal-capacity-ah 1.1
+```
+
+## Python Usage
+
+```python
+from pathlib import Path
+
+from battery_feature_lab.pipeline import FeaturePipeline, PipelineConfig
+from battery_feature_lab.schemas import ExportConfig, FeatureConfig, ReaderConfig
+
+pipeline = FeaturePipeline(
+    PipelineConfig(
+        reader=ReaderConfig(cell_id="cell_001"),
+        features=FeatureConfig(nominal_capacity_ah=1.1),
+        export=ExportConfig(output_dir=Path("out")),
+    )
+)
+
+tables = pipeline.run("input.csv")
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check .
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

battery_feature_lab-0.1.0/battery_feature_lab/__init__.py

@@ -0,0 +1,8 @@
+"""Battery Feature Lab.
+
+Independent feature extraction pipeline for battery cycling data and BDS-style exports.
+"""
+
+from battery_feature_lab.pipeline import FeaturePipeline, PipelineConfig
+
+__all__ = ["FeaturePipeline", "PipelineConfig"]

battery_feature_lab-0.1.0/battery_feature_lab/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis helpers for extracted battery features."""

battery_feature_lab-0.1.0/battery_feature_lab/analysis/degradation_tags.py

@@ -0,0 +1,305 @@
+"""Rule-based degradation evidence tagging for LLM context."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.stats import kendalltau
+
+from battery_feature_lab.schemas import DiagnosticConfig
+
+def build_degradation_tags(
+    cycle_features: pd.DataFrame | None = None,
+    ica_dva_features: pd.DataFrame | None = None,
+    stress_features: pd.DataFrame | None = None,
+    relaxation_features: pd.DataFrame | None = None,
+    config: DiagnosticConfig | None = None,
+) -> pd.DataFrame:
+    """Build interpretable degradation tags from extracted feature tables."""
+
+    config = config or DiagnosticConfig()
+    records: list[dict[str, object]] = []
+    cycle_features = _empty_if_none(cycle_features)
+    ica_dva_features = _empty_if_none(ica_dva_features)
+    stress_features = _empty_if_none(stress_features)
+    relaxation_features = _empty_if_none(relaxation_features)
+
+    cells = set()
+    for table in (cycle_features, ica_dva_features, stress_features, relaxation_features):
+        if "cell_id" in table.columns:
+            cells.update(table["cell_id"].dropna().astype(str).unique())
+
+    for cell_id in sorted(cells):
+        cell_cycle = cycle_features[cycle_features.get("cell_id", pd.Series(dtype=str)) == cell_id]
+        cell_ica = ica_dva_features[ica_dva_features.get("cell_id", pd.Series(dtype=str)) == cell_id]
+        cell_stress = stress_features[stress_features.get("cell_id", pd.Series(dtype=str)) == cell_id]
+        cell_relax = relaxation_features[
+            relaxation_features.get("cell_id", pd.Series(dtype=str)) == cell_id
+        ]
+        records.extend(_capacity_fade_tags(cell_id, cell_cycle, config))
+        records.extend(_ica_shift_tags(cell_id, cell_ica, config))
+        records.extend(_stress_tags(cell_id, cell_stress, stress_features, config))
+        records.extend(_relaxation_tags(cell_id, cell_relax, config))
+
+    return pd.DataFrame(records)
+
+
+def _capacity_fade_tags(
+    cell_id: str, cycles: pd.DataFrame, config: DiagnosticConfig
+) -> list[dict[str, object]]:
+    if cycles.empty or "discharge_capacity_ah" not in cycles:
+        return []
+    ordered = cycles.sort_values("cycle_index")
+    capacity = ordered["discharge_capacity_ah"].to_numpy(dtype=float)
+    cycle = ordered["cycle_index"].to_numpy(dtype=float)
+    valid = np.isfinite(capacity) & np.isfinite(cycle)
+    if valid.sum() < config.min_trend_points:
+        return []
+    normalized = capacity[valid] / capacity[valid][0] if capacity[valid][0] else capacity[valid]
+    trend = mann_kendall_sen_slope(cycle[valid], normalized)
+    if trend["sen_slope"] < 0 and trend["p_value"] < config.trend_p_value_alpha:
+        return [
+            _tag(
+                cell_id,
+                "capacity_fade_detected",
+                ["LLI", "LAM_PE", "LAM_NE"],
+                "medium",
+                "Mann-Kendall trend test detects monotonic capacity fade: "
+                f"p={trend['p_value']:.3g}, Sen slope={trend['sen_slope']:.3e} per cycle.",
+            )
+        ]
+    return []
+
+
+def _ica_shift_tags(
+    cell_id: str, ica: pd.DataFrame, config: DiagnosticConfig
+) -> list[dict[str, object]]:
+    if ica.empty or "ica_peak_1_x" not in ica.columns:
+        return []
+    discharge = ica[ica.get("step_type", "") == "discharge"].sort_values("cycle_index")
+    if len(discharge) < config.min_trend_points:
+        return []
+    peak_x = discharge["ica_peak_1_x"].to_numpy(dtype=float)
+    cycle = discharge["cycle_index"].to_numpy(dtype=float)
+    valid = np.isfinite(peak_x) & np.isfinite(cycle)
+    if valid.sum() < config.min_trend_points:
+        return []
+    trend = mann_kendall_sen_slope(cycle[valid], peak_x[valid])
+    if trend["p_value"] >= config.trend_p_value_alpha or not np.isfinite(trend["sen_slope"]):
+        return []
+    mode = "LLI" if trend["sen_slope"] < 0 else "LAM_PE"
+    return [
+        _tag(
+            cell_id,
+            "ica_primary_peak_shift",
+            [mode],
+            "medium",
+            "Mann-Kendall trend test detects primary ICA peak drift: "
+            f"p={trend['p_value']:.3g}, Sen slope={trend['sen_slope']:.3e} V per cycle.",
+        )
+    ]
+
+
+def _stress_tags(
+    cell_id: str,
+    stress: pd.DataFrame,
+    all_stress: pd.DataFrame,
+    config: DiagnosticConfig,
+) -> list[dict[str, object]]:
+    if stress.empty:
+        return []
+    row = stress.iloc[0]
+    tags = []
+
+    high_soc_rest = float(row.get("high_soc_rest_fraction", np.nan))
+    if np.isfinite(high_soc_rest):
+        triggered, basis = _evaluate_stress_metric(
+            value=high_soc_rest,
+            population=_column_values(all_stress, "high_soc_rest_fraction"),
+            absolute_threshold=config.high_soc_rest_fraction_threshold,
+            batch_method="percentile",
+            batch_param=config.stress_percentile,
+        )
+        if triggered:
+            tags.append(
+                _tag(
+                    cell_id,
+                    "high_soc_rest_exposure",
+                    ["LAM_PE", "LLI"],
+                    "medium",
+                    f"High-SOC rest fraction {high_soc_rest:.3g} flagged by {basis}.",
+                )
+            )
+
+    c_rate_variance = float(row.get("c_rate_variance", np.nan))
+    if np.isfinite(c_rate_variance):
+        triggered, basis = _evaluate_stress_metric(
+            value=c_rate_variance,
+            population=_column_values(all_stress, "c_rate_variance"),
+            absolute_threshold=config.c_rate_variance_threshold,
+            batch_method="mad",
+            batch_param=config.stress_mad_threshold,
+        )
+        if triggered:
+            tags.append(
+                _tag(
+                    cell_id,
+                    "dynamic_current_variance",
+                    ["LAM_NE", "resistance_growth"],
+                    "low",
+                    f"Normalized C-rate variance {c_rate_variance:.3g} flagged by {basis}.",
+                )
+            )
+
+    max_discharge_c = float(row.get("max_instant_discharge_c_rate", np.nan))
+    if (
+        config.datasheet_max_discharge_c_rate is not None
+        and np.isfinite(max_discharge_c)
+        and max_discharge_c
+        > config.datasheet_max_discharge_c_rate * config.max_discharge_c_rate_fraction
+    ):
+        tags.append(
+            _tag(
+                cell_id,
+                "high_instantaneous_discharge_rate",
+                ["LAM_NE", "resistance_growth"],
+                "medium",
+                f"Maximum instantaneous discharge C-rate {max_discharge_c:.2f} exceeds "
+                f"{config.max_discharge_c_rate_fraction:.0%} of datasheet limit "
+                f"{config.datasheet_max_discharge_c_rate:.2f}.",
+            )
+        )
+    return tags
+
+
+def _relaxation_tags(
+    cell_id: str, relaxation: pd.DataFrame, config: DiagnosticConfig
+) -> list[dict[str, object]]:
+    if relaxation.empty or "rest_exp_tau_s" not in relaxation.columns:
+        return []
+    ordered = relaxation.sort_values("cycle_index")
+    tau = ordered["rest_exp_tau_s"].to_numpy(dtype=float)
+    cycle = ordered["cycle_index"].to_numpy(dtype=float)
+    valid = np.isfinite(tau) & np.isfinite(cycle)
+    if valid.sum() < config.min_trend_points:
+        return []
+    trend = mann_kendall_sen_slope(cycle[valid], tau[valid])
+    if trend["sen_slope"] > 0 and trend["p_value"] < config.trend_p_value_alpha:
+        return [
+            _tag(
+                cell_id,
+                "relaxation_tau_increase",
+                ["resistance_growth", "transport_limitation"],
+                "low",
+                "Mann-Kendall trend test detects increasing relaxation time constant: "
+                f"p={trend['p_value']:.3g}, Sen slope={trend['sen_slope']:.3e} s per cycle.",
+            )
+        ]
+    return []
+
+
+def mann_kendall_sen_slope(x: np.ndarray, y: np.ndarray) -> dict[str, float]:
+    """Return the Mann-Kendall trend p-value and Sen's slope for a monotonic trend.
+
+    The Mann-Kendall test statistic is Kendall's tau between the series and its (time/cycle)
+    index, so ``scipy.stats.kendalltau`` computes the test directly (exact for small n, asymptotic
+    with tie handling otherwise). Sen's slope is the Theil-Sen median of pairwise slopes, the trend
+    magnitude estimator conventionally paired with Mann-Kendall. Power is low for very short
+    series; callers should require a minimum sample size (see ``DiagnosticConfig.min_trend_points``).
+    """
+
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    valid = np.isfinite(x) & np.isfinite(y)
+    x = x[valid]
+    y = y[valid]
+    if len(x) < 2:
+        return {"p_value": float("nan"), "sen_slope": float("nan"), "kendall_tau": float("nan")}
+    tau, p_value = kendalltau(x, y)
+    slopes: list[float] = []
+    for i in range(len(x) - 1):
+        dx = x[i + 1 :] - x[i]
+        dy = y[i + 1 :] - y[i]
+        valid_dx = np.abs(dx) > 1e-12
+        slopes.extend((dy[valid_dx] / dx[valid_dx]).tolist())
+    sen_slope = float(np.median(slopes)) if slopes else float("nan")
+    return {
+        "p_value": float(p_value) if np.isfinite(p_value) else float("nan"),
+        "sen_slope": sen_slope,
+        "kendall_tau": float(tau) if np.isfinite(tau) else float("nan"),
+    }
+
+
+def _evaluate_stress_metric(
+    value: float,
+    population: np.ndarray,
+    absolute_threshold: float | None,
+    batch_method: str,
+    batch_param: float,
+) -> tuple[bool, str]:
+    """Dual-criterion stress evaluation.
+
+    The absolute threshold encodes domain knowledge (cell spec / application limit) and is
+    single-cell capable. The batch criterion is a *supplementary* outlier signal that requires
+    a population of cells and is reported as relative, never as an absolute physical judgment.
+    Returns ``(triggered, basis)`` where ``basis`` names which criterion fired.
+    """
+
+    if absolute_threshold is not None and value > absolute_threshold:
+        return True, f"absolute threshold {absolute_threshold:.3g} (config/domain knowledge)"
+    batch_threshold = _batch_threshold(population, batch_method, batch_param)
+    if np.isfinite(batch_threshold) and value > batch_threshold:
+        if batch_method == "percentile":
+            label = f"batch P{batch_param * 100:.0f}"
+        else:
+            label = f"batch median+{batch_param:g}*MAD"
+        return True, f"batch-relative outlier (> {label} = {batch_threshold:.3g})"
+    return False, ""
+
+
+def _batch_threshold(population: np.ndarray, method: str, param: float) -> float:
+    values = np.asarray(population, dtype=float)
+    values = values[np.isfinite(values)]
+    if method == "percentile":
+        if len(values) < 2:
+            return float("nan")
+        return float(np.quantile(values, param))
+    if method == "mad":
+        # Robust outlier threshold: median + param * (1.4826 * MAD). The 1.4826 factor scales the
+        # median absolute deviation to a standard-deviation-consistent estimator under normality,
+        # so ``param`` is interpretable as a number of (robust) sigmas. Unlike mean+k*std this does
+        # not let a single extreme cell inflate the spread and mask itself.
+        if len(values) < 3:
+            return float("nan")
+        median = float(np.median(values))
+        mad = float(np.median(np.abs(values - median)))
+        robust_sigma = 1.4826 * mad
+        if robust_sigma <= 1e-12 or not np.isfinite(robust_sigma):
+            return float("nan")
+        return float(median + param * robust_sigma)
+    return float("nan")
+
+
+def _column_values(frame: pd.DataFrame, column: str) -> np.ndarray:
+    series = pd.to_numeric(frame.get(column, pd.Series(dtype=float)), errors="coerce")
+    return series.to_numpy(dtype=float)
+
+
+def _tag(
+    cell_id: str,
+    signal: str,
+    possible_modes: list[str],
+    confidence: str,
+    evidence: str,
+) -> dict[str, object]:
+    return {
+        "cell_id": cell_id,
+        "signal": signal,
+        "possible_modes": possible_modes,
+        "confidence": confidence,
+        "evidence": evidence,
+    }
+
+
+def _empty_if_none(frame: pd.DataFrame | None) -> pd.DataFrame:
+    return frame if frame is not None else pd.DataFrame()