icoschema 0.1.0b1__tar.gz

icoschema-0.1.0b1/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"

icoschema-0.1.0b1/.github/workflows/publish.yaml

@@ -0,0 +1,59 @@
+# Source: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+
+name: Build Python Package
+
+on: push
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install build package
+        run: >
+          python3 -m
+          pip install
+          build
+          --user
+
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish package
+    # Only publish to PyPI on tag pushes
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/icoschema
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download all the distribution packages
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

icoschema-0.1.0b1/.github/workflows/test.yaml

@@ -0,0 +1,44 @@
+name: Run tests
+
+on:
+  - push
+
+jobs:
+  os-python-matrix:
+    strategy:
+      matrix:
+        os:
+          - name: macos
+            icon: 🍏
+          - name: ubuntu
+            icon: 🐧
+          - name: windows
+            icon: 🪟
+        python-version:
+          - "3.13"
+          - "3.14"
+
+    runs-on: ${{ matrix.os.name }}-latest
+    name: ${{ matrix.os.icon }} Python ${{ matrix.python-version }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package
+        run: |
+          uv venv
+          uv sync
+
+      - name: Test code
+        run: uv run pytest

icoschema-0.1.0b1/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+CLAUDE.md
+.claude
+.idea

icoschema-0.1.0b1/.python-version

@@ -0,0 +1 @@
+3.13

icoschema-0.1.0b1/ICOschema/__init__.py

@@ -0,0 +1,23 @@
+"""ICOschema: a backend-agnostic data model for sensor/hardware recordings
+and their derived computations.
+
+    from ICOschema import Recording, DatasetBundle
+
+    recording = Recording.from_hdf5("some_file.hdf5")
+    df = recording.to_dataframe()
+
+    bundle = DatasetBundle.from_hdf5("some_file.hdf5")
+    bundle = bundle.with_computation("wavelet_coefficients/channel1/details", derived)
+    bundle.to_hdf5("some_file.hdf5")
+
+See ICOschema.model.python.recording.Recording and
+ICOschema.model.python.dataset_bundle.DatasetBundle for the full API.
+`DerivedDataset` is a component type with no behavior beyond what's
+generated (see ICOschema.schema.generated.python.dataset.DerivedDataset).
+"""
+
+from ICOschema.model.python.dataset_bundle import DatasetBundle
+from ICOschema.model.python.recording import Recording
+from ICOschema.schema.generated.python.dataset import DerivedDataset
+
+__all__ = ["DatasetBundle", "DerivedDataset", "Recording"]

icoschema-0.1.0b1/ICOschema/model/__init__.py

@@ -0,0 +1,5 @@
+from ICOschema.model.python.dataset_bundle import DatasetBundle
+from ICOschema.model.python.recording import Recording
+from ICOschema.schema.generated.python.dataset import DerivedDataset
+
+__all__ = ["DatasetBundle", "DerivedDataset", "Recording"]

icoschema-0.1.0b1/ICOschema/model/python/dataset_bundle.py

@@ -0,0 +1,80 @@
+"""The public API for a `DatasetBundle`: a `Recording` together with every
+`DerivedDataset` computed from it (see ICOschema/schema/generated/python).
+Adds loading from / writing to storage and immutable-update helpers on top
+of the generated fields (`recording`, `computations`).
+
+This file should never be imported directly, but rather only from the main
+entrypoint:
+
+    from ICOschema import DatasetBundle
+
+    bundle = DatasetBundle.from_hdf5("some_file.hdf5")
+    bundle = bundle.with_computation("wavelet_coefficients/channel1/details", derived)
+    bundle.to_hdf5("some_file.hdf5")
+
+`DerivedDataset` itself has no model-layer wrapper -- like `Sensor` or
+`ChannelMetadata`, it's a component type with no behavior beyond what's
+generated, used directly via
+`ICOschema.schema.generated.python.dataset.DerivedDataset`.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from ICOschema.model.python.recording import Recording
+from ICOschema.schema.generated.python import dataset as generated
+from ICOschema.schema.generated.python.dataset import DerivedDataset
+
+
+class DatasetBundle(generated.DatasetBundle):
+    """A Recording together with every DerivedDataset computed from it.
+
+    Has every field of `ICOschema.schema.generated.python.dataset.DatasetBundle`
+    (`recording`, `computations`), plus the loading/writing and
+    immutable-update methods defined below. Construct via a `from_XXX`
+    classmethod (e.g. `from_hdf5`) rather than the bare constructor when
+    loading from storage.
+    """
+
+    @classmethod
+    def from_hdf5(cls, path: str, *, on_error: Literal["skip", "raise"] = "skip") -> DatasetBundle:
+        """Load a DatasetBundle from an HDF5 file.
+
+        Always succeeds -- `computations` is empty if the file has none.
+        A malformed computation entry is logged and skipped by default;
+        pass `on_error="raise"` to fail the whole read instead. See
+        ICOschema.storage.python.hdf5 for the accepted file layout.
+        """
+        from ICOschema.storage.python import hdf5
+
+        loaded = hdf5.load_dataset_bundle(path, on_error=on_error)
+        return cls(
+            recording=Recording(
+                hardware_metadata=loaded.recording.hardware_metadata,
+                recording_metadata=loaded.recording.recording_metadata,
+                recording_data=loaded.recording.recording_data,
+            ),
+            computations=dict(loaded.computations),
+        )
+
+    def to_hdf5(self, path: str) -> None:
+        """Write this bundle (recording + every computation) to a fresh HDF5 file.
+
+        See ICOschema.storage.python.hdf5 for the file layout this
+        produces -- each computation is stored in its true N-D shape under
+        a `/computations/` group.
+        """
+        from ICOschema.storage.python import hdf5
+
+        hdf5.save_dataset_bundle(self, path)
+
+    def with_recording(self, recording: Recording) -> DatasetBundle:
+        """A copy of this bundle with `recording` replaced (e.g. after dataloss-fill)."""
+        return DatasetBundle(recording=recording, computations=dict(self.computations))
+
+    def with_computation(self, key: str, derived: DerivedDataset) -> DatasetBundle:
+        """A copy of this bundle with one computation added/replaced under `key`."""
+        computations = dict(self.computations)
+        computations[key] = derived
+        return DatasetBundle(recording=self.recording, computations=computations)

icoschema-0.1.0b1/ICOschema/model/python/recording.py

@@ -0,0 +1,173 @@
+"""The public API of this repository: a `Recording` that inherits all
+fields from the generated `dataset.Recording` (see
+ICOschema/schema/generated/python) and adds a few things that aren't
+auto-generated: loading from / writing to a specific storage backend,
+converting to a pandas DataFrame, quick pass-through getters for the raw
+arrays (timestamps, counter, channel1/2/3), as numpy arrays, that plotting
+code typically wants directly instead of going through recording_data or a
+DataFrame, signal_loss_percentage, and a JSON-encodable summary() of the
+whole recording.
+
+This file should never be imported directly, but rather only from the main
+entrypoint:
+
+    from ICOschema import Recording
+
+    recording = Recording.from_hdf5("some_file.hdf5")
+    df = recording.to_dataframe()
+
+ICOschema.schema.generated (plain data, no behavior) and ICOschema.storage
+(storage-format-specific I/O) are internal implementation details of this
+module and should not be imported directly by other codebases.
+
+Note: Compensation/Conversion (on HardwareMetadata.channelN_metadata) is
+purely descriptive of what has already been applied to a channel's raw
+RecordingData values -- it is not applied by this class, or by anything
+else here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from ICOschema.schema.generated.python import dataset as generated
+
+
+class Recording(generated.Recording):
+    """A complete recording: hardware/sensor metadata plus its sample data.
+
+    Has every field of `ICOschema.schema.generated.python.dataset.Recording`
+    (`hardware_metadata`, `recording_metadata`, `recording_data`), plus the
+    loading/writing and convenience methods defined below. Construct via a
+    `from_XXX` classmethod (e.g. `from_hdf5`) rather than the bare
+    constructor when loading from storage.
+    """
+
+    @classmethod
+    def from_hdf5(cls, path: str) -> Recording:
+        """Load a Recording from a PyTables-style HDF5 file.
+
+        See ICOschema.storage.python.hdf5 for the accepted file layout and
+        the legacy/versioned format dispatch. Oblivious to any
+        `/computations/` group the file may also contain -- use
+        ICOschema.DatasetBundle.from_hdf5() to read those too.
+        """
+        from ICOschema.storage.python import hdf5
+
+        loaded = hdf5.load_recording(path)
+        return cls(
+            hardware_metadata=loaded.hardware_metadata,
+            recording_metadata=loaded.recording_metadata,
+            recording_data=loaded.recording_data,
+        )
+
+    def to_hdf5(self, path: str) -> None:
+        """Write this recording to a fresh HDF5 file in the current format.
+
+        See ICOschema.storage.python.hdf5 for the file layout this
+        produces.
+        """
+        from ICOschema.storage.python import hdf5
+
+        hdf5.save_recording(self, path)
+
+    @property
+    def timestamps(self) -> np.ndarray:
+        """recording_data.timestamp as a numpy array (integer microseconds since recording_metadata.start_time)."""
+        return np.asarray(self.recording_data.timestamp)
+
+    @property
+    def channel1(self) -> np.ndarray:
+        """recording_data.channel1 as a numpy array. Always present."""
+        return np.asarray(self.recording_data.channel1)
+
+    @property
+    def channel2(self) -> np.ndarray:
+        """recording_data.channel2 as a numpy array. Empty if this recording has no second channel."""
+        return np.asarray(self.recording_data.channel2)
+
+    @property
+    def channel3(self) -> np.ndarray:
+        """recording_data.channel3 as a numpy array. Empty if this recording has no third channel."""
+        return np.asarray(self.recording_data.channel3)
+
+    @property
+    def counter(self) -> np.ndarray:
+        """recording_data.counter as a numpy array (an 8-bit wrapping packet counter)."""
+        return np.asarray(self.recording_data.counter, dtype=int)
+
+    @property
+    def signal_loss_percentage(self) -> float:
+        """Percentage of packets lost, inferred from gaps/wraparounds in `counter`.
+
+
+        `counter` is an 8-bit counter (wraps 255 -> 0) that increments once per
+        packet; a jump of more than 1 between consecutive samples (accounting
+        for wraparound) means packets were dropped in between.
+        """
+        counter = self.counter
+        gaps = np.diff(counter) - 1
+        gaps[gaps == -1] = 0  # counter repeated (no increment)
+        gaps[gaps == -256] = 0  # clean wraparound 255 -> 0
+        gaps[gaps < 0] += 256  # wraparound with loss
+        total_lost = int(np.sum(gaps))
+        total_received = len(counter)
+        return (total_lost / (total_received + total_lost)) * 100
+
+    def summary(self) -> dict[str, Any]:
+        """A compact, JSON-encodable summary of this recording.
+
+        Every value is a plain `str`/`int`/`float`/`None` (never a numpy
+        scalar or array) so `json.dumps(recording.summary())` always
+        succeeds without a custom encoder -- this is meant to be safe to
+        hand directly to a future web API response.
+        """
+        channels: dict[str, dict[str, Any]] = {}
+        channel_metadata = {
+            "channel1": self.hardware_metadata.channel1_metadata,
+            "channel2": self.hardware_metadata.channel2_metadata,
+            "channel3": self.hardware_metadata.channel3_metadata,
+        }
+        for name, metadata in channel_metadata.items():
+            values = getattr(self, name)
+            if values.size == 0:
+                continue
+            sensor = metadata.sensor if metadata is not None else None
+            channels[name] = {
+                "sensor_id": sensor.sensor_id if sensor is not None else None,
+                "sensor_type": sensor.sensor_type if sensor is not None else None,
+                "unit": sensor.unit if sensor is not None else None,
+                "sample_count": int(values.size),
+                "min": float(np.min(values)),
+                "max": float(np.max(values)),
+                "mean": float(np.mean(values)),
+                "std": float(np.std(values)),
+            }
+
+        return {
+            "start_time": self.recording_metadata.start_time,
+            "sample_count": int(len(self.counter)),
+            "signal_loss_percentage": float(self.signal_loss_percentage),
+            "channels": channels,
+        }
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """recording_data as a DataFrame (columns: timestamp, counter, channel1, and channel2/channel3 if present).
+
+        Values are raw and uncompensated -- see the module docstring's note
+        on Compensation/Conversion.
+        """
+        data = self.recording_data
+        columns = {
+            "timestamp": data.timestamp,
+            "counter": data.counter,
+            "channel1": data.channel1,
+        }
+        if data.channel2:
+            columns["channel2"] = data.channel2
+        if data.channel3:
+            columns["channel3"] = data.channel3
+        return pd.DataFrame(columns)