gamry-dta 0.1.0__py3-none-any.whl

gamry_dta-0.1.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.3
+Name: gamry-dta
+Version: 0.1.0
+Summary: Read Gamry .DTA files as polars dataframes. Also extract metadata as dictionaries.
+Author: kristianfkt
+Author-email: kristianfkt <kristianfkt@gmail.com>
+Requires-Dist: pandas>=3.0.6
+Requires-Dist: polars>=1.42.0
+Requires-Dist: pyarrow>=25.0.1
+Requires-Dist: matplotlib>=3.11.2 ; extra == 'plot'
+Requires-Python: >=3.11
+Provides-Extra: plot
+Description-Content-Type: text/markdown
+
+# Gamry DTA
+- Library for reading gamry DTA files
+
+# Installing
+`pip install gamrydta`
+
+# Quick start
+```
+import gamrydta
+
+path = ".../some_file.dta"
+dta = gamrydta.read()
+```
+
+# Contributing
+- Bug reports
+- ...
+
+# Future:
+- Parse column name-units according to https://github.com/emmo-repo/domain-electrochemistry
+- Parse header fields according to https://github.com/emmo-repo/domain-electrochemistry
+- Infer header field types, text, float, etc
+- Add retry-cases for encoding errors
+- Set default 'decimal' to None. Infer if not provided. 
+- Add an explorative dashboardu
+

gamry_dta-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+gamrydta/__init__.py,sha256=S87ikEWJDEDnRxuZeQm8kLQJQd8JeSCS_Jh_uRKY1KY,284
+gamrydta/aliases.py,sha256=SJl0aj1tFnOo1r8BxIB_oc6C1q-5iIEYtAQYU_qo6Bo,87
+gamrydta/common.py,sha256=sdmIaPMmyTL8Y6qAiPiP9tQq3L8hML7Go2PiTwVSN8Y,294
+gamrydta/experiments/__init__.py,sha256=EcymHLuqs9ZFc9y02yQeIPUbL8ZlESlOPC9Y8C6zjrA,1725
+gamrydta/experiments/chrono.py,sha256=NqGw-umdZ-Tqw81MLGmKVu643T0ejy3XGK2-KdPZKp0,428
+gamrydta/experiments/experiment.py,sha256=28zgYEYSJQUrh0oNd6TlJsHc06n1ygyLsalV9yzrj5E,1848
+gamrydta/experiments/impedance.py,sha256=d1Wl9wxxiRnKg76hU4-jwtnMcXdwzswfYhy8Nq-J5OU,150
+gamrydta/experiments/opencircuit.py,sha256=IJHHFmfjAiplYp0r8UqILvYjBJcwA76ej2OgJEqb9Jk,155
+gamrydta/experiments/voltammetry.py,sha256=8La-c-QSdXV95BJ-7_eQ9e1A7cJZbSaP9p_xnswLpso,316
+gamrydta/parsing/__init__.py,sha256=L-i50VD0c3paB_LnSLuWrZVWxFyu_5XYMu5saGDh_40,116
+gamrydta/parsing/curves.py,sha256=S7G9blZYmcmI2KNp4O8uk7yEp_77tDUIBP7j-HIaJZk,972
+gamrydta/parsing/dta.py,sha256=E1m2EGoOIdPWjDaeOIqsBp57df84CM7Jy4YmLa9DyrA,684
+gamrydta/parsing/header.py,sha256=lKM4WPqOwPZaDhqFA0Tyn_zFbHrK6NV_Pl1JFqJZ2CY,671
+gamrydta/parsing/ocv.py,sha256=exb0wAqIghMzXblc9kC3N0WGI8qekPkki-iH3QebBBE,905
+gamrydta/parsing/table.py,sha256=G83V6tlbVytwhDRFyCQ6EeJ7CElcbzmaARRO3Wl4mC4,741
+gamrydta/variables.py,sha256=yGldx47K-hVPyEm4jh7AYk-Et94dKnvowH-ElFmAuC4,1159
+gamry_dta-0.1.0.dist-info/WHEEL,sha256=9IUYslYuG_asT4WlWvfk_K76nveuLvSTKDoLeL0cV-Q,80
+gamry_dta-0.1.0.dist-info/METADATA,sha256=CwbYg-SSJVgsr3Bv7NMoeQZ_dtlJ0UU_ZSL5BDfvYZY,1019
+gamry_dta-0.1.0.dist-info/RECORD,,

gamry_dta-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.1
+Root-Is-Purelib: true
+Tag: py3-none-any

gamrydta/__init__.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+
+from gamrydta.experiments import read
+
+
+def find(
+    path: str | Path,
+    pattern: str = "*.DTA",
+) -> list[Path]:
+    if isinstance(path, str):
+        path = Path(path)
+
+    files = list(path.rglob(pattern))
+    return files
+
+
+__all__ = ["find", "read"]

gamrydta/aliases.py

@@ -0,0 +1,5 @@
+from pathlib import Path
+
+Line = list[str]
+Lines = list[Line]
+DTA = str | Path | Lines

gamrydta/common.py

@@ -0,0 +1,26 @@
+from typing import Literal
+
+Decimal = Literal[".", ","]
+DECIMAL = "."
+
+
+class ParsingError(Exception):
+    """
+    Parsing somehow failed
+    """
+
+
+def is_text(value: str):
+    pass
+
+
+def is_float(value: str):
+    pass
+
+
+def is_int(value: str):
+    pass
+
+
+def is_datetime(value: str):
+    pass

gamrydta/experiments/__init__.py

@@ -0,0 +1,62 @@
+import logging
+from pathlib import Path
+
+from gamrydta import parsing
+from gamrydta.common import DECIMAL, Decimal, ParsingError
+from gamrydta.experiments.chrono import (
+    Chronoamperometry,
+    Chronocoulometry,
+    Chronopotentiometry,
+)
+from gamrydta.experiments.experiment import Experiment
+from gamrydta.experiments.impedance import PotentiostaticEIS
+from gamrydta.experiments.opencircuit import CorrosionPotential, OpenCircuitPotential
+from gamrydta.experiments.voltammetry import CyclicVoltammetry, LinearSweepVoltammetry
+
+logger = logging.getLogger(__name__)
+
+EXPERIMENTS = {
+    "CHRONOA": Chronoamperometry,
+    "CHRONOP": Chronopotentiometry,
+    "CHRONOC": Chronocoulometry,
+    "CV": CyclicVoltammetry,
+    "LSV": LinearSweepVoltammetry,
+    "OCP": OpenCircuitPotential,
+    "CORPOT": CorrosionPotential,
+    "EISPOT": PotentiostaticEIS,
+}
+
+
+def read(
+    path: str | Path,
+    encoding: str | None = None,
+    decimal: Decimal = DECIMAL,
+):
+    for line in parsing.dta.scan(path, encoding=encoding):
+        if line[0] == "TAG":
+            tag = line[1]
+            break
+    else:
+        raise ParsingError("Failed to detect experiement TAG")
+
+    if tag in EXPERIMENTS:
+        experiment = EXPERIMENTS[tag]
+        logger.info(f"TAG {tag} known - returning {experiment}")
+    else:
+        experiment = Experiment
+        logger.info(f"TAG {tag} unknonw - returning {experiment}")
+    return experiment.read(path, encoding=encoding, decimal=decimal)
+
+
+__all__ = [
+    "Chronoamperometry",
+    "Chronocoulometry",
+    "Chronopotentiometry",
+    "CorrosionPotential",
+    "CyclicVoltammetry",
+    "DTAData",
+    "LinearSweepVoltammetry",
+    "OpenCircuitPotential",
+    "PotentiostaticEIS",
+    "read",
+]

gamrydta/experiments/chrono.py

@@ -0,0 +1,19 @@
+from gamrydta.experiments.experiment import Experiment
+
+
+class Chronoamperometry(Experiment):
+    @property
+    def current(self) -> float:
+        return self._header["current"]
+
+
+class Chronopotentiometry(Experiment):
+    @property
+    def current(self) -> float:
+        return self._header["current"]
+
+
+class Chronocoulometry(Experiment):
+    @property
+    def current(self) -> float:
+        return self._header["current"]

gamrydta/experiments/experiment.py

@@ -0,0 +1,81 @@
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Self
+
+import polars as pl
+
+from gamrydta import parsing
+from gamrydta.common import DECIMAL, Decimal
+
+
+class Experiment:
+    def __init__(
+        self,
+        *,
+        path: str | Path,
+        curves: pl.DataFrame,
+        header: Mapping[str, Any],
+        ocv: pl.DataFrame | None,
+    ):
+        self._path = parsing.dta.resolve(path)
+        self._curves = curves
+        self._header = header
+        self._ocv = ocv
+
+    @classmethod
+    def read(
+        cls,
+        path: str | Path,
+        encoding: str | None = None,
+        decimal: Decimal = DECIMAL,
+    ) -> Self:
+
+        path = parsing.dta.resolve(path)
+        lines = parsing.dta.read(path, encoding=encoding)
+
+        return cls(
+            path=path,
+            curves=parsing.curves.parse(lines, decimal=decimal),
+            header=parsing.header.parse(lines, decimal=decimal),
+            ocv=parsing.ocv.parse(lines, decimal=decimal),
+        )
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def curves(self) -> pl.DataFrame:
+        return self._curves
+
+    @property
+    def data(self) -> pl.DataFrame:
+        return self._curves
+
+    @property
+    def header(self) -> Mapping[str, Any]:
+        return self._header
+
+    @property
+    def metadata(self) -> Mapping[str, Any]:
+        return self._header
+
+    @property
+    def experiment(self) -> str:
+        return self._header["TITLE"]
+
+    @property
+    def tag(self) -> str:
+        return self._header["TAG"]
+
+    @property
+    def ocv(self) -> pl.DataFrame | None:
+        return self._ocv
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "header": self.header,
+            "curve": self.curves,
+            "ocv": self.ocv,
+        }

gamrydta/experiments/impedance.py

@@ -0,0 +1,9 @@
+from gamrydta.experiments.experiment import Experiment
+
+
+class PotentiostaticEIS(Experiment):
+    pass
+
+
+class GalvanostaticEIS(Experiment):
+    pass

gamrydta/experiments/opencircuit.py

@@ -0,0 +1,9 @@
+from gamrydta.experiments.experiment import Experiment
+
+
+class OpenCircuitPotential(Experiment):
+    pass
+
+
+class CorrosionPotential(Experiment):
+    pass

gamrydta/experiments/voltammetry.py

@@ -0,0 +1,13 @@
+from gamrydta.experiments.experiment import Experiment
+
+
+class CyclicVoltammetry(Experiment):
+    @property
+    def sweeprate(self) -> float:
+        return self._header["SWEEPRATE"]
+
+
+class LinearSweepVoltammetry(Experiment):
+    @property
+    def sweeprate(self) -> float:
+        return self._header["SWEEPRATE"]

gamrydta/parsing/__init__.py

@@ -0,0 +1,3 @@
+from gamrydta.parsing import curves, dta, header, ocv, table
+
+__all__ = ["curves", "dta", "header", "ocv", "table"]

gamrydta/parsing/curves.py

@@ -0,0 +1,39 @@
+import re
+
+import polars as pl
+
+from gamrydta import parsing
+from gamrydta.aliases import Lines
+from gamrydta.common import DECIMAL, Decimal
+
+
+def match(line: list[str]) -> bool:
+    return bool(re.fullmatch(r"(?:ZCURVE|CURVE(?:[1-9][0-9]*)?)", line[0]))
+
+
+def parse(
+    lines: Lines,
+    decimal: Decimal = DECIMAL,
+) -> pl.DataFrame:
+    """
+    Extracts the curve data from a DTA file and returns it as a DataFrame.
+    """
+
+    indices_start = [idx + 1 for idx, line in enumerate(lines) if match(line)]
+    indices_end = [idx - 1 for idx in indices_start[1::]] + [len(lines)]
+    curves = []
+    for s, e in zip(indices_start, indices_end):
+        curve = parsing.table.parse(
+            lines[s:e],
+            decimal=decimal,
+        )
+
+        curves.append(curve)
+
+    if len(curves) > 1:
+        curves = [
+            curve.with_columns(pl.lit(i).alias("curve"))
+            for i, curve in enumerate(curves, start=1)
+        ]
+
+    return pl.concat(curves)

gamrydta/parsing/dta.py

@@ -0,0 +1,26 @@
+from collections.abc import Iterator
+from pathlib import Path
+
+
+def resolve(path: str | Path) -> Path:
+    """
+    Ensures that a path is Path.only.
+    """
+    return Path(path).resolve(strict=True)
+
+
+def split(line: str) -> list[str]:
+    return line.strip().removesuffix("\n").split("\t")
+
+
+def read(path: str | Path, encoding: str | None) -> list[list[str]]:
+    path = resolve(path)
+    with open(path, "r", encoding=encoding) as f:
+        return [split(line) for line in f]
+
+
+def scan(path: str | Path, encoding: str | None) -> Iterator[list[str]]:
+    path = resolve(path)
+    with open(path, "r", encoding=encoding) as f:
+        for line in f:
+            yield split(line)

gamrydta/parsing/header.py

@@ -0,0 +1,26 @@
+from gamrydta.aliases import Lines
+from gamrydta.common import DECIMAL, Decimal
+from gamrydta.parsing import curves, ocv
+
+
+def parse(
+    lines: Lines,
+    decimal: Decimal = DECIMAL,
+) -> dict:
+    """
+    Extracts the header fields from a DTA file and returns them as a dictionary.
+    """
+
+    header = {}
+    for line in lines:
+        if curves.match(line):
+            return header
+        if not line[0].strip() or ocv.match(line):
+            continue
+        if len(line) == 2:
+            key, value = line
+            header[key] = value
+        if len(line) == 4:
+            code, kind, value, name = line
+            header[name] = value
+    return header

gamrydta/parsing/ocv.py

@@ -0,0 +1,36 @@
+import re
+
+import polars as pl
+
+from gamrydta import parsing
+from gamrydta.aliases import Lines
+from gamrydta.common import DECIMAL, Decimal, ParsingError
+
+
+def match(line: list[str]) -> bool:
+    return line[0] == "OCVCURVE"
+
+
+def parse(
+    lines: Lines,
+    decimal: Decimal = DECIMAL,
+) -> pl.DataFrame | None:
+    """
+    Extracts the OCV data from a DTA file and returns it as a DataFrame.
+    """
+
+    for idx, line in enumerate(lines):
+        if match(line):
+            index_start = idx + 1
+            break
+    else:
+        return None
+
+    for idx, line in enumerate(lines[index_start + 2 : :], start=index_start + 2):
+        if not bool(re.fullmatch(r"[0-9]+", line[0])):
+            index_end = idx
+            break
+    else:
+        raise ParsingError("Reached en of lines without findingn OCV curve end")
+
+    return parsing.table.parse(lines[index_start:index_end], decimal=decimal)

gamrydta/parsing/table.py

@@ -0,0 +1,35 @@
+import csv
+from io import StringIO
+
+import polars as pl
+
+from gamrydta.aliases import Lines
+from gamrydta.common import DECIMAL, Decimal
+
+
+def parse(
+    table: Lines,
+    decimal: Decimal = DECIMAL,
+) -> pl.DataFrame:
+    """
+    Parses lines from
+    CURVE TABLE
+    ..units
+    ...vvalues
+    """
+    names = table[0]
+    units = table[1]
+
+    buffer = StringIO()
+    writer = csv.writer(buffer, delimiter="\t")
+    writer.writerow([f"{name} / {unit}" for name, unit in zip(names, units)])
+    writer.writerows(table[2::])
+    buffer.seek(0)
+    return pl.read_csv(
+        buffer,
+        has_header=True,
+        infer_schema=True,
+        infer_schema_length=None,
+        separator="\t",
+        decimal_comma=(decimal == ","),
+    )

gamrydta/variables.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass, field
+from typing import TypedDict
+
+import polars as pl
+
+
+class Name(TypedDict):
+    code: str
+    label: str
+
+
+class Unit(TypedDict):
+    code: str
+    label: str
+
+
+@dataclass
+class Variable:
+    name: Name
+    unit: Unit
+    code: str = field(init=False)
+    label: str = field(init=False)
+
+    def __post_init__(self):
+        self.code = f"{self.name['code']}_{self.unit['code']}"
+
+        self.label = f"{self.name['label']} / {self.unit['label']}"
+
+
+UNITS = {
+    "#": Unit(code="1", label="1"),
+    "s": Unit(code="second", label="s"),
+    "V vs. Ref.": Unit(code="voltage_versus_reference", label="V vs Ref"),
+}
+
+
+VARIABLES: dict[str, str] = {
+    "Pt": "Record count / 1",
+    "T": "Test time / s",
+    "curve": "Cycle count / 1",
+    "Vf": "Voltage / V",
+    "Im": "Current / A",
+    "Q": "Charge / C",
+    "Freq": "Frequency / Hz",
+    "Zreal": "Zr / Ohm",
+    "Zimag": "Zi / Ohm",
+    "Zmod": "Zmod / Ohm",
+    "Zphz": "Zphz / degrees",
+}
+
+
+def rename(data: pl.DataFrame) -> pl.DataFrame:
+    """
+    Rename some mapped variables to better described names
+    """
+    return data.rename(VARIABLES, strict=False)