pmecg 0.2.3__tar.gz

pmecg-0.2.3/.github/copilot-instructions.md

@@ -0,0 +1,63 @@
+# pmecg — Copilot Instructions
+
+`pmecg` is a Python library for plotting high-quality, paper-like ECG signals using Matplotlib.
+
+## Commands
+
+```bash
+pixi install                                # Install the default development environment
+pixi run test                               # Run all tests in the default environment
+pixi run test-fast                          # Unit + structural tests only (no network)
+pixi run pytest tests/test_data.py::TestSegmentLeads -v  # Run a specific test class
+pixi run pytest tests/test_data.py::TestNumpyToDataframe::test_shape -v  # Run a single test
+pixi run lint                               # Lint + formatting check
+pixi run ruff check . --fix                 # Lint with auto-fix
+```
+
+Always use `pixi run` (or named Pixi tasks) to invoke Python tools — never `python` or `pytest` directly.
+
+Integration tests (`@pytest.mark.integration`) require network access to download the PTB-XL dataset and are slow; skip them with `-m "not integration"` for routine development.
+
+## Architecture
+
+The codebase has three layers:
+
+1. **Public API** (`src/pmecg/plot.py`, re-exported via `src/pmecg/__init__.py`):
+   - `ECGPlotter` — main class; instantiate with visual parameters, then call `.plot()`
+   - `ECGStats`, `ECGInformation` — dataclasses for optional metadata overlays
+   - `template_factory()`, `LeadsMap`, `SUPPORTED_LEADS` — configuration helpers
+
+2. **Data layer** (`src/pmecg/utils/data.py`):
+   - Normalizes ECG input (numpy arrays, lists of arrays, or DataFrames) into a DataFrame
+   - Resolves and validates configuration (template expansion, lead name mapping)
+   - Segments leads into rows for rendering
+
+3. **Rendering layer** (`src/pmecg/utils/plot.py`):
+   - Low-level Matplotlib logic: grid drawing, figure sizing, calibration pulse, row plotting
+   - Uses `MM_PER_INCH = 25.4` and physical-unit constants (mm) for exact paper sizes
+
+Data flows: `ECGPlotter.plot()` → data layer normalizes input and expands config → rendering layer produces a Matplotlib `Figure`.
+
+## Key Conventions
+
+**Configuration system:**
+- A *configuration* is `list[list[str] | str]` — each element is a row; a string is a full-width lead, a sublist is concatenated leads sharing a row.
+- Built-in templates (`"4x3"`, `"2x6"`, `"1x12"`, etc.) must be expanded via `template_factory()` before passing to `ECGPlotter.plot()` — `plot()` does not accept raw template strings.
+- Custom lead names are mapped to canonical names (`"I"`, `"II"`, ..., `"V6"`) via `LeadsMap`.
+
+**Types:**
+```python
+ECGDataType = tuple[list[np.ndarray] | np.ndarray, list[str]] | pd.DataFrame
+ConfigurationDataType = list[list[str] | str]
+```
+
+**Naming:**
+- Public symbols: `PascalCase` (`ECGPlotter`, `LeadsMap`)
+- Internal helpers: leading underscore (`_segment_leads`, `_plot_row`, `_RenderContext`)
+- Module-level constants: `UPPER_CASE` (`MM_PER_INCH`, `SUPPORTED_LEADS`, `CAL_PULSE_AMP_MV`)
+
+**Typing:** Full type annotations are required throughout (`py.typed` marker is present). Docstrings follow NumPy/SciPy style.
+
+**Linting:** Ruff with rules `E, W, F, I, UP, B` and line length 128, targeting Python 3.8+. The `pixi run lint` task runs `ruff check . && ruff format --check .`.
+
+**Tests:** `test_plot_systematic.py` uses `matplotlib.use("Agg")` for headless rendering. Tests are heavily parametrized across all built-in templates. New layout or data-handling changes should be validated against the systematic tests.

pmecg-0.2.3/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: Run tests and linting
+
+on:
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+      - 'pixi.lock'
+      - '.github/workflows/ci.yml'
+  push:
+    branches: [ main ]
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+      - 'pixi.lock'
+      - '.github/workflows/ci.yml'
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install all pixi environments
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          environments: default py38 py39 py310 py311 py312 py313 py314
+          locked: true
+          cache: true
+          cache-write: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+
+  lint:
+    runs-on: ubuntu-latest
+    needs: setup
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Restore pixi environments
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          environments: default
+          locked: true
+          cache: true
+          cache-write: false
+
+      - name: Lint and format check
+        run: pixi run lint
+
+  test:
+    runs-on: ubuntu-latest
+    needs: setup
+    strategy:
+      matrix:
+        include:
+          - python-version: '3.8'
+            environment: py38
+          - python-version: '3.9'
+            environment: py39
+          - python-version: '3.10'
+            environment: py310
+          - python-version: '3.11'
+            environment: py311
+          - python-version: '3.12'
+            environment: py312
+          - python-version: '3.13'
+            environment: py313
+          - python-version: '3.14'
+            environment: py314
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Restore pixi environment
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          environments: ${{ matrix.environment }}
+          locked: true
+          cache: true
+          cache-write: false
+
+      - name: Cache PTB-XL data
+        uses: actions/cache@v4
+        with:
+          path: tests/.ptbxl-cache
+          key: ptbxl-${{ hashFiles('tests/ptbxl_helper.py') }}
+
+      - name: Run tests on Python ${{ matrix.python-version }}
+        run: pixi run -e ${{ matrix.environment }} test

pmecg-0.2.3/.github/workflows/release.yml

@@ -0,0 +1,95 @@
+name: Release pmecg
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build wheel
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up pixi
+        uses: prefix-dev/setup-pixi@v0.9.4
+        with:
+          environments: default
+          locked: false
+          cache: true
+
+      - name: Build wheel and source tarball
+        run: pixi run build-dist
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  github-release:
+    name: Publish to GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release and upload assets
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          gh release create "$TAG" dist/** \
+            --repo "$GITHUB_REPOSITORY" \
+            --title "pmecg $TAG" \
+            --generate-notes
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: github-release
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pmecg
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  trigger-rtd:
+    name: Trigger Read the Docs build
+    needs: [github-release, publish-pypi]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Trigger RTD webhook
+        run: |
+          PAYLOAD="{\"ref\":\"${GITHUB_REF}\"}"
+          SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "${{ secrets.RTD_SECRET }}" | awk '{print $2}')
+          curl -X POST \
+            -H "X-Hub-Signature-256: sha256=$SIG" \
+            -H "Content-Type: application/json" \
+            -d "$PAYLOAD" \
+            https://app.readthedocs.org/api/v2/webhook/pmecg/322018/

pmecg-0.2.3/.gitignore

@@ -0,0 +1,40 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Gemini repo
+.gemini.md
+
+# CLAUDE
+CLAUDE.md
+
+# uv
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+simple_plot.py
+example_ecg.mat
+tests/.ptbxl-cache/
+
+# Docs builds
+_build/

pmecg-0.2.3/.python-version

@@ -0,0 +1 @@
+3.12

pmecg-0.2.3/.readthedocs.yml

@@ -0,0 +1,14 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  commands:
+    - curl -fsSL https://pixi.sh/install.sh | bash
+    - $HOME/.pixi/bin/pixi run build-docs
+    - mkdir -p $READTHEDOCS_OUTPUT/html && cp -r docs/_build/html/. $READTHEDOCS_OUTPUT/html/