groundtem-io 0.1.0__tar.gz

groundtem_io-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# OS files
+.DS_Store
+Thumbs.db

groundtem_io-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyeonwoo Kang
+
+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 IF 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.

groundtem_io-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: groundtem-io
+Version: 0.1.0
+Summary: Unofficial Python reader and plotting utilities for GroundTEM .stb, .stn, and .sts files
+Project-URL: Homepage, https://github.com/Kang-geophysics/groundtem-io
+Project-URL: Repository, https://github.com/Kang-geophysics/groundtem-io
+Project-URL: Issues, https://github.com/Kang-geophysics/groundtem-io/issues
+Author-email: Hyeonwoo Kang <hykanghw@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: GroundTEM,TDEM,TEM,electromagnetics,geophysics,stb,stn
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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 :: Physics
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# groundtem-io
+
+Unofficial Python reader and plotting utilities for GroundTEM time-domain electromagnetic (TDEM) data files:
+- `.stb` binary stack files (`read_stb`)
+- `.stn` station metadata files (`read_stn`)
+- `.sts` survey protocol files (`read_protocol`)
+- LM / HM decay curve and SNR plotting utilities (`plot_decay`, `plot_station`)
+
+> **Disclaimer:** This is an independent, unofficial open-source library for reading GroundTEM data files for scientific and interoperability purposes. It is not affiliated with, endorsed by, or sponsored by ABEM or Guideline Geo.
+
+---
+
+## Installation
+
+```bash
+pip install groundtem-io
+```
+
+Or for local development with `uv`:
+
+```bash
+uv venv
+uv pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Read `.stb` and `.stn` files directly
+
+```python
+import matplotlib.pyplot as plt
+from groundtem_io import read_stb, read_stn, plot_station
+
+# Read station metadata (.stn)
+stn = read_stn("path/to/station.stn")
+print(stn["StationNo"], stn["Latitude"], stn["Longitude"])
+
+# Read stacked LM / HM decay records (.stb)
+stb = read_stb("path/to/sounding.stb")
+print("LM gate times (s):", stb.gate_times["LM"])
+print("LM stacks shape (n_stacks, n_gates):", stb.data("LM").shape)
+print("HM stacks shape (n_stacks, n_gates):", stb.data("HM").shape)
+
+# Plot LM & HM decay curves (with individual stacks) and SNR
+fig, axs = plot_station(stb)
+plt.show()
+```
+
+### 2. Read an entire survey directory into a `pandas.DataFrame`
+
+```python
+from groundtem_io import read_survey, plot_decay
+import matplotlib.pyplot as plt
+
+df = read_survey("path/to/survey_folder")
+print(df[["sounding", "station", "n_lm", "n_hm", "dist_m"]])
+
+# Plot first station
+fig, ax = plt.subplots(figsize=(5, 4))
+plot_decay(ax, df.iloc[0], stacks=True)
+ax.legend()
+plt.show()
+```
+
+### 3. Read `.sts` protocol file
+
+```python
+from groundtem_io import read_protocol
+
+proto = read_protocol("path/to/Protocol.sts")
+print("Tx loop size (m):", proto.tx_size)
+print("LM dipole moment (A*m^2):", proto.dipole_moment("LM"))
+print("HM dipole moment (A*m^2):", proto.dipole_moment("HM"))
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

groundtem_io-0.1.0/PUBLISHING_GUIDE.md

@@ -0,0 +1,129 @@
+# `groundtem-io` 독립 로컬 환경 세팅 및 GitHub / PyPI 배포 가이드라인
+
+이 문서는 `groundtem-io` 폴더를 다른 디렉토리로 복사한 뒤, **새로운 독립 로컬 프로젝트 환경**에서 바로 개발, 테스트, GitHub 업로드 및 PyPI(`pip`) 배포를 이어서 진행할 수 있도록 작성된 단계별 가이드입니다.
+
+---
+
+## 1. 폴더 구조 확인
+
+복사한 `groundtem-io/` 폴더 내부는 다음과 같이 구성되어 있습니다:
+
+```text
+groundtem-io/
+├── .gitignore              # Git 추적 제외 목록 (가상환경, 빌드 산출물 등)
+├── LICENSE                 # MIT 오픈소스 라이선스
+├── PUBLISHING_GUIDE.md     # 현재 보고 계신 배포 및 환경 설정 가이드라인
+├── README.md               # GitHub 및 PyPI 메인 페이지에 표시될 영문 설명서
+├── pyproject.toml          # 패키지 설정, 버전, 의존성 메타데이터
+└── src/
+    └── groundtem_io/
+        ├── __init__.py     # 패키지 공개 API 정의
+        ├── stb.py          # read_stb, read_stn, read_sounding_dir, read_survey
+        ├── protocol.py     # read_protocol (.sts 프로토콜 파서)
+        └── plotting.py     # plot_decay, plot_station (LM/HM 감쇠곡선 및 SNR 플롯)
+```
+
+---
+
+## 2. 새 로컬 환경에서 프로젝트 시작하기
+
+1. 원하는 작업 경로(예: `~/Projects/groundtem-io`)로 이 `groundtem-io` 폴더를 복사/이동합니다.
+2. 터미널(또는 새로운 Antigravity/VS Code 창)에서 해당 폴더를 엽니다.
+3. `pyproject.toml` 파일을 열어 수정할 항목이 있는지 확인합니다:
+   - `name`: 기본값은 `"groundtem-io"`입니다. 다른 패키지명을 원하시면 `pyproject.toml`의 `name`을 변경하세요.
+   - `authors`: 이름과 이메일 주소를 확인하세요.
+   - `[project.urls]`: `YOUR_GITHUB_USERNAME` 부분을 본인의 GitHub 아이디로 변경하세요.
+
+### 로컬 가상환경 생성 및 편집 모드(Editable) 설치
+`uv`가 설치되어 있다면 아래 명령어로 즉시 독립 가상환경을 만들고 패키지를 테스트할 수 있습니다:
+
+```bash
+# 1. 가상환경 생성 (.venv)
+uv venv
+
+# 2. 현재 패키지를 editable 모드로 설치
+uv pip install -e .
+
+# 3. 정상 임포트 확인
+uv run python -c "import groundtem_io; print(groundtem_io.__version__, groundtem_io.__all__)"
+```
+
+---
+
+## 3. 배포 전 법적·보안 체크리스트 (필수 확인)
+
+1. **제조사 독점 파일 포함 금지**:
+   - ABEM / Guideline Geo의 공식 설치 프로그램(`.zip`, `.exe`), 내부 `.dll` 바이너리, 비공개 PDF 매뉴얼 등은 절대 이 저장소에 넣지 마세요.
+2. **현장 데이터 보안 확인**:
+   - 대용량 현장 로우 데이터나 대외비/미발표 연구 데이터는 커밋하지 마세요.
+   - 예제 코드나 단위 테스트용 데이터가 필요하다면 공개 가능한 단일 측정점(`.stb`, `.stn` 1개 세트)만 `examples/` 또는 `tests/data/`에 최소한으로 포함하세요.
+3. **비공식 오픈소스 명시**:
+   - `README.md` 상단에 ABEM / Guideline Geo와 무관한 독립 오픈소스 리더임을 밝히는 Disclaimer 문구가 이미 포함되어 있습니다.
+
+---
+
+## 4. GitHub 저장소 생성 및 업로드
+
+1. [GitHub](https://github.com/new)에서 `groundtem-io`라는 이름으로 새로운 **Public** 저장소를 생성합니다 (`README`, `.gitignore`, `LICENSE`는 이미 로컬에 있으므로 체크하지 않고 빈 저장소로 생성).
+2. 프로젝트 폴더에서 아래 명령어를 순서대로 실행합니다:
+
+```bash
+git init
+git add .
+git commit -m "Initial commit: groundtem-io package for .stb, .stn, and .sts files"
+git branch -M main
+git remote add origin https://github.com/<본인_GitHub_아이디>/groundtem-io.git
+git push -u origin main
+```
+
+---
+
+## 5. PyPI (`pip`) 패키지 빌드 및 배포
+
+### Step 1: PyPI 계정 및 API 토큰 준비
+1. [pypi.org](https://pypi.org/)에 가입 및 로그인합니다 (2FA 이중 인증 등록 필요).
+2. **Account settings** → **API tokens** → **Add API token**으로 이동합니다.
+   - Token name: `groundtem-io-upload`
+   - Scope: 처음 올릴 때는 `Entire account (all projects)`를 선택합니다.
+3. 생성된 토큰(`pypi-AgEIcHlwaS5vcmc...`)을 안전한 곳에 복사해 둡니다.
+
+*(연습 삼아 먼저 테스트해보고 싶다면 [test.pypi.org](https://test.pypi.org/)에서 동일하게 토큰을 발급받아 테스트할 수도 있습니다.)*
+
+### Step 2: 패키지 빌드 (`dist/` 생성)
+프로젝트 루트에서 아래 명령어를 실행합니다:
+
+```bash
+uv build
+```
+실행 후 `dist/` 폴더 안에 다음 두 파일이 생성되었는지 확인합니다:
+- `groundtem_io-0.1.0-py3-none-any.whl`
+- `groundtem_io-0.1.0.tar.gz`
+
+### Step 3: PyPI에 업로드 (`uv publish`)
+발급받은 토큰을 사용해 PyPI에 업로드합니다:
+
+```bash
+uv publish --token pypi-여기에_발급받은_토큰_입력
+```
+
+*(참고: 만약 `twine`을 선호하신다면 `uvx twine upload dist/*`로도 동일하게 업로드할 수 있습니다.)*
+
+### Step 4: 배포 확인 및 설치 테스트
+업로드가 완료되면 몇 초 내로 `https://pypi.org/project/groundtem-io/` 페이지가 활성화되며, 어디서든 아래 명령어로 설치할 수 있습니다:
+
+```bash
+pip install groundtem-io
+```
+
+---
+
+## 6. 향후 버전 업데이트 방법
+
+코드를 수정한 뒤 새 버전을 올리고 싶을 때는:
+1. `pyproject.toml`과 `src/groundtem_io/__init__.py`의 `version`을 `"0.1.1"` 또는 `"0.2.0"`으로 올립니다.
+2. 기존 빌드 파일을 지우고 다시 빌드 및 배포합니다:
+   ```bash
+   rm -rf dist/
+   uv build
+   uv publish --token pypi-여기에_발급받은_토큰_입력
+   ```

groundtem_io-0.1.0/README.md

@@ -0,0 +1,82 @@
+# groundtem-io
+
+Unofficial Python reader and plotting utilities for GroundTEM time-domain electromagnetic (TDEM) data files:
+- `.stb` binary stack files (`read_stb`)
+- `.stn` station metadata files (`read_stn`)
+- `.sts` survey protocol files (`read_protocol`)
+- LM / HM decay curve and SNR plotting utilities (`plot_decay`, `plot_station`)
+
+> **Disclaimer:** This is an independent, unofficial open-source library for reading GroundTEM data files for scientific and interoperability purposes. It is not affiliated with, endorsed by, or sponsored by ABEM or Guideline Geo.
+
+---
+
+## Installation
+
+```bash
+pip install groundtem-io
+```
+
+Or for local development with `uv`:
+
+```bash
+uv venv
+uv pip install -e .
+```
+
+---
+
+## Quick Start
+
+### 1. Read `.stb` and `.stn` files directly
+
+```python
+import matplotlib.pyplot as plt
+from groundtem_io import read_stb, read_stn, plot_station
+
+# Read station metadata (.stn)
+stn = read_stn("path/to/station.stn")
+print(stn["StationNo"], stn["Latitude"], stn["Longitude"])
+
+# Read stacked LM / HM decay records (.stb)
+stb = read_stb("path/to/sounding.stb")
+print("LM gate times (s):", stb.gate_times["LM"])
+print("LM stacks shape (n_stacks, n_gates):", stb.data("LM").shape)
+print("HM stacks shape (n_stacks, n_gates):", stb.data("HM").shape)
+
+# Plot LM & HM decay curves (with individual stacks) and SNR
+fig, axs = plot_station(stb)
+plt.show()
+```
+
+### 2. Read an entire survey directory into a `pandas.DataFrame`
+
+```python
+from groundtem_io import read_survey, plot_decay
+import matplotlib.pyplot as plt
+
+df = read_survey("path/to/survey_folder")
+print(df[["sounding", "station", "n_lm", "n_hm", "dist_m"]])
+
+# Plot first station
+fig, ax = plt.subplots(figsize=(5, 4))
+plot_decay(ax, df.iloc[0], stacks=True)
+ax.legend()
+plt.show()
+```
+
+### 3. Read `.sts` protocol file
+
+```python
+from groundtem_io import read_protocol
+
+proto = read_protocol("path/to/Protocol.sts")
+print("Tx loop size (m):", proto.tx_size)
+print("LM dipole moment (A*m^2):", proto.dipole_moment("LM"))
+print("HM dipole moment (A*m^2):", proto.dipole_moment("HM"))
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

groundtem_io-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "groundtem-io"
+version = "0.1.0"
+description = "Unofficial Python reader and plotting utilities for GroundTEM .stb, .stn, and .sts files"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Hyeonwoo Kang", email = "hykanghw@gmail.com" }
+]
+requires-python = ">=3.9"
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "matplotlib>=3.7",
+]
+keywords = ["geophysics", "TEM", "TDEM", "electromagnetics", "GroundTEM", "stb", "stn"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "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 :: Physics",
+]
+
+[project.urls]
+Homepage = "https://github.com/Kang-geophysics/groundtem-io"
+Repository = "https://github.com/Kang-geophysics/groundtem-io"
+Issues = "https://github.com/Kang-geophysics/groundtem-io/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/groundtem_io"]

groundtem_io-0.1.0/src/groundtem_io/__init__.py

@@ -0,0 +1,22 @@
+"""Unofficial Python reader and plotting utilities for GroundTEM .stb, .stn, and .sts files."""
+
+from .plotting import plot_decay, plot_station, sem
+from .protocol import Moment, Protocol, read_protocol, summarize_protocols
+from .stb import StbFile, read_sounding_dir, read_stb, read_stn, read_survey
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StbFile",
+    "read_stb",
+    "read_stn",
+    "read_sounding_dir",
+    "read_survey",
+    "Moment",
+    "Protocol",
+    "read_protocol",
+    "summarize_protocols",
+    "sem",
+    "plot_decay",
+    "plot_station",
+]

groundtem_io-0.1.0/src/groundtem_io/plotting.py

@@ -0,0 +1,118 @@
+"""Plotting utilities for GroundTEM LM and HM decay curves and SNR."""
+
+from typing import Mapping, Optional, Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from .stb import StbFile
+
+DEFAULT_COLORS = {"LM": "tab:blue", "HM": "tab:red"}
+
+
+def sem(record: Mapping, moment: str) -> np.ndarray:
+    """Return the larger of empirical and instrument-reported SEM for a station record."""
+    return np.fmax(record[f"sem_emp_{moment}"], record[f"sem_rep_{moment}"])
+
+
+def plot_decay(
+    ax: plt.Axes,
+    source: Union[StbFile, Mapping],
+    stacks: bool = False,
+    stack_stride: int = 10,
+    colors: Optional[Mapping[str, str]] = None,
+) -> plt.Axes:
+    """Plot LM and HM decay curves and noise floor on a log-log Axes.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Target axes.
+    source : StbFile or dict/Series
+        Either an ``StbFile`` returned by ``read_stb`` or a row dict/Series returned
+        by ``read_sounding_dir`` / ``read_survey``.
+    stacks : bool, default False
+        If True, also plot individual raw stacks as light dots.
+    stack_stride : int, default 10
+        Stride used when plotting raw stacks.
+    colors : mapping, optional
+        Custom color mapping for ``{"LM": ..., "HM": ...}``.
+    """
+    col = colors or DEFAULT_COLORS
+    if isinstance(source, StbFile):
+        polarity = -1 if (len(source.stacks["HM"]) > 0 and source.data("HM").mean(0)[:5].mean() < 0) else 1
+        summaries = {m: source.summary(m, polarity=polarity) for m in ("LM", "HM") if len(source.stacks[m]) > 0}
+    else:
+        summaries = {
+            m: {
+                "t": source[f"t_{m}"],
+                "d": source[f"d_{m}"],
+                "sem": sem(source, m),
+                "stacks": source[f"stacks_{m}"],
+            }
+            for m in ("LM", "HM")
+            if f"d_{m}" in source
+        }
+
+    for m, info in summaries.items():
+        t, d, e = info["t"], info["d"], info["sem"]
+        if stacks and "stacks" in info:
+            for s in info["stacks"][::stack_stride]:
+                ax.loglog(t, np.abs(s), ".", color=col[m], alpha=0.12, ms=3)
+        pos = d > 0
+        ax.errorbar(t[pos], d[pos], e[pos], fmt="o-", color=col[m], ms=3, lw=1, label=m)
+        if np.any(~pos):
+            ax.errorbar(t[~pos], -d[~pos], e[~pos], fmt="o", mfc="none", color=col[m], ms=4)
+        ax.loglog(t, e, "--", color=col[m], lw=0.8, alpha=0.7)
+
+    ax.set_xscale("log")
+    ax.set_yscale("log")
+    return ax
+
+
+def plot_station(
+    source: Union[StbFile, Mapping],
+    snr_min: float = 3.0,
+    stacks: bool = True,
+    title: Optional[str] = None,
+):
+    """Plot a two-panel figure showing LM/HM decay curves (with raw stacks) and SNR."""
+    fig, axs = plt.subplots(1, 2, figsize=(11, 4))
+    plot_decay(axs[0], source, stacks=stacks)
+    if title is None:
+        if isinstance(source, StbFile):
+            title = source.path.name
+        else:
+            title = f"Station {source.get('station', '')} ({source.get('sounding', '')})"
+    axs[0].set_title(title)
+    axs[0].set_xlabel("time (s)")
+    axs[0].set_ylabel("|dB/dt| x I x N_tx (V/m²)")
+    axs[0].legend()
+
+    if isinstance(source, StbFile):
+        polarity = -1 if (len(source.stacks["HM"]) > 0 and source.data("HM").mean(0)[:5].mean() < 0) else 1
+        for m in ("LM", "HM"):
+            if len(source.stacks[m]) == 0:
+                continue
+            info = source.summary(m, polarity=polarity)
+            axs[1].semilogx(info["t"], info["d"] / info["sem"], "o-", color=DEFAULT_COLORS[m], ms=3, label=m)
+    else:
+        for m in ("LM", "HM"):
+            if f"d_{m}" not in source:
+                continue
+            axs[1].semilogx(
+                source[f"t_{m}"],
+                source[f"d_{m}"] / sem(source, m),
+                "o-",
+                color=DEFAULT_COLORS[m],
+                ms=3,
+                label=m,
+            )
+
+    axs[1].axhline(snr_min, color="k", ls=":")
+    axs[1].set_yscale("symlog")
+    axs[1].set_title("SNR = mean / SEM")
+    axs[1].set_xlabel("time (s)")
+    axs[1].legend()
+    fig.tight_layout()
+    return fig, axs

groundtem_io-0.1.0/src/groundtem_io/protocol.py

@@ -0,0 +1,191 @@
+"""Parse a GroundTEM ``.sts`` protocol file into structured dataclasses."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import re
+from typing import Dict, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+DEFAULT_SAMPLE_PERIOD = 0.25e-6
+
+
+@dataclass
+class Moment:
+    name: str
+    on_time: float  # [s]
+    period_time: float  # [s]
+    stack_size: int
+    target_current: float  # [A]
+    wave_time: np.ndarray  # [s], 0 = start of turn-off ramp
+    wave_amp: np.ndarray  # normalised amplitude [0, 1]
+    gate_start: np.ndarray  # [s] after end of on-time (start of turn-off ramp)
+    gate_end: np.ndarray  # [s] after end of on-time
+    tap_start: float  # [s] start of the tapered (log-spaced) gates
+    damper_time: Tuple[float, float] = (0.0, 0.0)  # (on, off) [s]
+
+    @property
+    def gate_center(self) -> np.ndarray:
+        """Raw gate center times [s] after turn-off start."""
+        return 0.5 * (self.gate_start + self.gate_end)
+
+    @property
+    def gate_width(self) -> np.ndarray:
+        """Raw gate widths [s]."""
+        return self.gate_end - self.gate_start
+
+    @property
+    def turnoff_duration(self) -> float:
+        """Duration of the turn-off ramp [s] (from t=0 to final zero-current node)."""
+        return float(self.wave_time[-1])
+
+    def tapered_times(self, per_decade: int = 10, include_early: bool = False) -> np.ndarray:
+        """Log-spaced gate centres (matching the '[Tapering]' section) in [s]."""
+        t0 = max(self.tap_start, float(self.gate_center[0]))
+        t1 = float(self.gate_center[-1])
+        n = int(np.floor(np.log10(t1 / t0) * per_decade)) + 1
+        t_tap = t0 * 10.0 ** (np.arange(n) / per_decade)
+        if include_early:
+            early_mask = (self.gate_center > self.turnoff_duration) & (self.gate_center < t0)
+            if np.any(early_mask):
+                return np.r_[self.gate_center[early_mask], t_tap]
+        return t_tap
+
+
+@dataclass
+class Protocol:
+    name: str
+    filepath: Path
+    sample_freq_hz: float
+    tx_xyz: np.ndarray
+    tx_size: Tuple[float, float]  # (x length, y length) [m]
+    tx_turns: int
+    rx_xyz: np.ndarray
+    rx_area: float  # effective area [m^2]
+    lp_filters: Tuple[float, ...]  # first-order low-pass cut-off frequencies [Hz]
+    gate_per_decade: int = 10
+    auto_sign: str = "InLoop"
+    powerline_freq: float = 60.0
+    moments: Dict[str, Moment] = field(default_factory=dict)
+
+    @property
+    def tx_area(self) -> float:
+        """Single-turn transmitter loop area [m^2]."""
+        return float(self.tx_size[0] * self.tx_size[1])
+
+    @property
+    def offset(self) -> float:
+        """Horizontal center-to-center distance between Tx and Rx [m]."""
+        return float(np.linalg.norm(self.rx_xyz[:2] - self.tx_xyz[:2]))
+
+    @property
+    def is_inloop(self) -> bool:
+        """True if central/in-loop configuration (zero horizontal offset)."""
+        return self.offset < 1e-6
+
+    def dipole_moment(self, moment_name: str) -> float:
+        """Transmitter magnetic dipole moment I * N_tx * A_tx [A*m^2]."""
+        mom = self.moments[moment_name.upper()]
+        return float(mom.target_current * self.tx_turns * self.tx_area)
+
+
+def _read_sts(path: Union[str, Path]) -> dict:
+    out = {}
+    text = Path(path).read_text(encoding="utf-8", errors="ignore")
+    lines = text.splitlines()
+    if lines and lines[0].startswith(";[ProtocolDesigner]"):
+        m = re.search(r"SampleFrequencyMHz\s*=\s*([0-9.]+)", lines[0])
+        if m:
+            out["SampleFrequencyMHz"] = float(m.group(1))
+    for line in lines:
+        if line.startswith((";", "[")) or "=" not in line:
+            continue
+        k, v = (s.strip() for s in line.split("=", 1))
+        try:
+            out[k] = np.array([float(x) for x in v.split(",")])
+        except ValueError:
+            out[k] = v
+    return out
+
+
+def read_protocol(path: Union[str, Path], channel: str = "A") -> Protocol:
+    """Read a GroundTEM ``.sts`` protocol file."""
+    path = Path(path)
+    d = _read_sts(path)
+    sample_freq_hz = float(d.get("SampleFrequencyMHz", 4.0)) * 1e6
+    sample_period = 1.0 / sample_freq_hz
+
+    p = Protocol(
+        name=path.stem,
+        filepath=path,
+        sample_freq_hz=sample_freq_hz,
+        tx_xyz=d["TxLoop_XYZPos"],
+        tx_size=tuple(float(x) for x in d["TxLoop_XYLength"]),
+        tx_turns=int(d["TxLoop_NTurns"][0]),
+        rx_xyz=d["RxCoil_XYZPos"],
+        rx_area=float(d[f"RxCoil_Area{'Ch' + channel}"][0]),
+        lp_filters=tuple(float(x) for x in d["LPFilter_1order"]),
+        gate_per_decade=int(d.get(f"Ch{channel}_GatePerDecade", [10])[0]),
+        auto_sign=str(d.get("AutoSignDetection", "InLoop")),
+        powerline_freq=float(d.get("PowerLineMonitorFreq", [60.0])[0]),
+    )
+    for m in ("LM", "HM"):
+        on_time = float(d[f"{m}_OnTime"][0]) * 1e-6
+        period_time = float(d[f"{m}_PeriodTime"][0]) * 1e-6
+        stack_size = int(d[f"{m}_StackSize"][0])
+        damper_on = float(d.get(f"{m}_Damper_TimeOn", [on_time * 1e6])[0]) * 1e-6
+        damper_off = float(d.get(f"{m}_Damper_TimeOff", [on_time * 1e6])[0]) * 1e-6
+        g0 = d[f"{m}_Ch{channel}_GateIndex0"][1:]
+        g1 = d[f"{m}_Ch{channel}_GateIndex1"][1:]
+        p.moments[m] = Moment(
+            name=m,
+            on_time=on_time,
+            period_time=period_time,
+            stack_size=stack_size,
+            target_current=float(d[f"{m}_Tx_TargetCurrent"][0]),
+            wave_time=d[f"{m}_Waveform_Time"] * 1e-6,
+            wave_amp=d[f"{m}_Waveform_Amplitude"],
+            gate_start=g0 * sample_period - on_time,
+            gate_end=g1 * sample_period - on_time,
+            tap_start=float(d[f"{m}_Ch{channel}_TapStartTime"][0]) * 1e-6,
+            damper_time=(damper_on, damper_off),
+        )
+    return p
+
+
+def summarize_protocols(protocols: Dict[str, Protocol]) -> pd.DataFrame:
+    """Build a summary table of survey configurations from loaded protocols."""
+    rows = []
+    for label, proto in protocols.items():
+        geom_type = (
+            f"In-Loop (Offset {proto.offset:.0f} m)"
+            if proto.is_inloop
+            else f"Offset Loop (Center Offset {proto.offset:.1f} m)"
+        )
+        for mname, mom in proto.moments.items():
+            t_tap = mom.tapered_times(per_decade=proto.gate_per_decade)
+            rows.append(
+                {
+                    "Configuration": f"{label} - {mname}",
+                    "Protocol File": proto.filepath.name,
+                    "Geometry": geom_type,
+                    "Tx Loop (m)": f"{proto.tx_size[0]:.0f}x{proto.tx_size[1]:.0f} ({proto.tx_turns} turn{'s' if proto.tx_turns > 1 else ''})",
+                    "Rx Pos (x, y, z) [m]": f"({proto.rx_xyz[0]:.1f}, {proto.rx_xyz[1]:.1f}, {proto.rx_xyz[2]:.1f})",
+                    "Rx Eff. Area (m²)": proto.rx_area,
+                    "Moment": mname,
+                    "Current (A)": mom.target_current,
+                    "Tx Moment (A·m²)": proto.dipole_moment(mname),
+                    "On-Time (µs)": mom.on_time * 1e6,
+                    "Turn-off Ramp (µs)": mom.turnoff_duration * 1e6,
+                    "Period (µs)": mom.period_time * 1e6,
+                    "Stack Size": mom.stack_size,
+                    "Raw Gates": len(mom.gate_center),
+                    "Raw Gate Range (µs)": f"{mom.gate_center[0]*1e6:.2f} – {mom.gate_center[-1]*1e6:.1f}",
+                    "Tapering Start (µs)": mom.tap_start * 1e6,
+                    "Tapered Gates": len(t_tap),
+                    "Tapered Range (µs)": f"{t_tap[0]*1e6:.1f} – {t_tap[-1]*1e6:.1f}",
+                    "LP Filters (kHz)": f"{proto.lp_filters[0]/1e3:.0f}, {proto.lp_filters[1]/1e3:.0f}",
+                }
+            )
+    return pd.DataFrame(rows)

groundtem_io-0.1.0/src/groundtem_io/stb.py

@@ -0,0 +1,195 @@
+"""Parse GroundTEM ``.stb`` stack files and ``.stn`` station files.
+
+File layout:
+
+* ASCII header (protocol ``[Gate]``, ``[RxTxSpecs]``, ``[ProcessedGateTimes]``, ``[InstrumentInfo]`` ...)
+* Binary stack records, each terminated by ``b"$" * 8``. The record type is given by byte 0
+  (0 = LM, 1 = HM) and the number of processed gates by the ``uint16`` at byte 2.
+  Record tail: ``uint32 stack_size`` + ``float32 data[n]`` + ``float32 rel_std_percent[n]``.
+  GPS latitude / longitude are ``float64`` at byte offsets 33 / 41.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import re
+import struct
+from typing import Dict, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+_TERMINATOR = b"$" * 8
+_LAT_OFFSET, _LON_OFFSET = 33, 41
+
+
+@dataclass
+class StbFile:
+    path: Path
+    gate_times: Dict[str, np.ndarray]  # {"LM": s, "HM": s} gate centre times [s] after turn-off start
+    stacks: Dict[str, pd.DataFrame]  # {"LM": DataFrame, "HM": DataFrame}, one row per saved stack
+    header: Dict[str, str] = field(default_factory=dict)
+
+    def data(self, moment: str) -> np.ndarray:
+        """Return (n_stack, n_gate) array of dB/dt data for ``moment`` ('LM' or 'HM')."""
+        return np.vstack(self.stacks[moment]["data"].to_list())
+
+    def rel_std(self, moment: str) -> np.ndarray:
+        """Return (n_stack, n_gate) array of per-stack relative std [%] for ``moment``."""
+        return np.vstack(self.stacks[moment]["rel_std"].to_list())
+
+    def summary(self, moment: str, polarity: Optional[int] = None) -> Dict[str, np.ndarray]:
+        """Compute mean decay curve and standard error estimates for ``moment``.
+
+        Parameters
+        ----------
+        moment : {"LM", "HM"}
+            Transmitter moment key.
+        polarity : {1, -1}, optional
+            Sign multiplier applied to ``data``. If ``None``, inferred automatically
+            from the sign of the first 5 early-time gates.
+        """
+        D_raw = self.data(moment)
+        if polarity is None:
+            polarity = -1 if D_raw.mean(0)[:5].mean() < 0 else 1
+        D = D_raw * polarity
+        S = self.rel_std(moment) / 100.0 * np.abs(D)
+        n = len(D)
+        sem_emp = D.std(0, ddof=1) / np.sqrt(n) if n > 1 else np.zeros(D.shape[1])
+        sem_rep = np.sqrt((S**2).sum(0)) / n
+        return {
+            "t": self.gate_times[moment],
+            "d": D.mean(0),
+            "sem_emp": sem_emp,
+            "sem_rep": sem_rep,
+            "sem": np.fmax(sem_emp, sem_rep),
+            "stacks": D,
+            "polarity": polarity,
+        }
+
+
+def _read_header(raw: bytes):
+    start = raw.find(b"[InstrumentInfo]")
+    end = raw.find(b"ControllerVersion", start)
+    end = raw.find(b"\n", end) + 1
+    text = raw[:end].decode("latin1")
+    out = {}
+    for key in ("LM_DataFactor", "HM_DataFactor", "LM_GateTimeShift", "HM_GateTimeShift", "InstrumentID"):
+        m = re.search(rf"{key}=(\S+)", text)
+        if m:
+            out[key] = m.group(1)
+    times = {}
+    for mom in ("LM", "HM"):
+        m = re.search(rf"{mom}_ChA_CenterTime=([^\r\n]+)", text)
+        times[mom] = np.array([float(x) for x in m.group(1).split(",")]) * 1e-6
+    return text, end, times, out
+
+
+def read_stb(path: Union[str, Path]) -> StbFile:
+    """Read a ``.stb`` stack file. Truncated trailing records are dropped."""
+    path = Path(path)
+    raw = path.read_bytes()
+    _, hdr_end, times, header = _read_header(raw)
+    body = raw[hdr_end:]
+    rows = {"LM": [], "HM": []}
+    pos = 0
+    while True:
+        idx = body.find(_TERMINATOR, pos)
+        if idx < 0:
+            break
+        rec = body[pos:idx]
+        pos = idx + len(_TERMINATOR)
+        for mom, code in (("LM", 0), ("HM", 1)):
+            n = len(times[mom])
+            full = _record_length(n)
+            if len(rec) < full:
+                continue
+            # locate record start from the tail (the first record carries a file preamble)
+            r = rec[-full:]
+            if r[0] != code or struct.unpack_from("<H", r, 2)[0] != n:
+                continue
+            rows[mom].append(
+                dict(
+                    stack_size=struct.unpack_from("<I", r, full - 8 * n - 4)[0],
+                    lat=struct.unpack_from("<d", r, _LAT_OFFSET)[0],
+                    lon=struct.unpack_from("<d", r, _LON_OFFSET)[0],
+                    data=np.frombuffer(r, "<f4", n, full - 8 * n).astype(float),
+                    rel_std=np.frombuffer(r, "<f4", n, full - 4 * n).astype(float),
+                )
+            )
+            break
+    stacks = {m: pd.DataFrame(v) for m, v in rows.items()}
+    return StbFile(path=path, gate_times=times, stacks=stacks, header=header)
+
+
+def _record_length(n: int) -> int:
+    """Record body length (without terminator): 231 fixed bytes + uint32 count + 2 float32 arrays."""
+    return 235 + 8 * n
+
+
+def read_stn(path: Union[str, Path]) -> dict:
+    """Read a ``.stn`` station file (key=value text)."""
+    out = {}
+    for line in Path(path).read_text(encoding="utf-8", errors="ignore").splitlines():
+        if "=" in line:
+            k, v = line.split("=", 1)
+            out[k.strip()] = v.strip()
+    for k in ("LineNo", "StationNo"):
+        if k in out:
+            out[k] = int(out[k])
+    for k in ("Latitude", "Longitude"):
+        if k in out:
+            out[k] = float(out[k])
+    return out
+
+
+def read_sounding_dir(directory: Union[str, Path]) -> Optional[dict]:
+    """Read a single sounding directory containing ``*.stn`` and ``*.stb`` files."""
+    d = Path(directory)
+    stb_files, stn_files = sorted(d.glob("*.stb")), sorted(d.glob("*.stn"))
+    if not stn_files:
+        return None
+    st = read_stn(stn_files[0])
+    row = {
+        "sounding": d.name,
+        "station": st.get("StationNo"),
+        "line": st.get("LineNo"),
+        "lat": st.get("Latitude"),
+        "lon": st.get("Longitude"),
+    }
+    if not stb_files:
+        return {**row, "n_lm": 0, "n_hm": 0}
+    s = read_stb(stb_files[0])
+    row.update(n_lm=len(s.stacks["LM"]), n_hm=len(s.stacks["HM"]), polarity=1)
+    if row["n_hm"] > 0 and s.data("HM").mean(0)[:5].mean() < 0:
+        row["polarity"] = -1
+    for m in ("LM", "HM"):
+        row[f"t_{m}"] = s.gate_times[m]
+        if len(s.stacks[m]) == 0:
+            continue
+        D = s.data(m) * row["polarity"]
+        S = s.rel_std(m) / 100.0 * np.abs(D)
+        n = len(D)
+        row[f"d_{m}"] = D.mean(0)
+        row[f"sem_emp_{m}"] = D.std(0, ddof=1) / np.sqrt(n) if n > 1 else np.zeros(D.shape[1])
+        row[f"sem_rep_{m}"] = np.sqrt((S**2).sum(0)) / n
+        row[f"stacks_{m}"] = D
+    return row
+
+
+def read_survey(data_root: Union[str, Path], pattern: str = "*/*") -> pd.DataFrame:
+    """Read all sounding directories under ``data_root`` into a DataFrame."""
+    root = Path(data_root)
+    if (root / "Data").is_dir():
+        root = root / "Data"
+    rows = []
+    for d in sorted(root.glob(pattern)):
+        if d.is_dir():
+            rec = read_sounding_dir(d)
+            if rec is not None:
+                rows.append(rec)
+    df = pd.DataFrame(rows)
+    if not df.empty and "lat" in df and "lon" in df:
+        df["x_m"] = (df.lon - df.lon.iloc[0]) * 111320 * np.cos(np.deg2rad(df.lat.iloc[0]))
+        df["y_m"] = (df.lat - df.lat.iloc[0]) * 110574
+        df["dist_m"] = np.r_[0, np.cumsum(np.hypot(np.diff(df.x_m), np.diff(df.y_m)))]
+    return df