| """ |
| domain/value_objects/signal_metadata.py |
| ──────────────────────────────────────── |
| SignalMetadata — immutable value object summarising the technical |
| characteristics of a PPG recording. |
| """ |
| from __future__ import annotations |
|
|
| from dataclasses import dataclass |
|
|
|
|
| @dataclass(frozen=True) |
| class SignalMetadata: |
| """ |
| Technical metadata for a PPG signal recording. |
| |
| Attributes: |
| sampling_rate: Number of samples per second (Hz). |
| duration_seconds: Length of the recording in seconds. |
| num_samples: Actual number of data points captured. |
| """ |
|
|
| sampling_rate: float |
| duration_seconds: float |
| num_samples: int |
|
|
| def __post_init__(self) -> None: |
| if self.sampling_rate <= 0: |
| raise ValueError("SignalMetadata.sampling_rate must be positive") |
| if self.duration_seconds <= 0: |
| raise ValueError("SignalMetadata.duration_seconds must be positive") |
| if self.num_samples <= 0: |
| raise ValueError("SignalMetadata.num_samples must be positive") |
|
|
| @property |
| def expected_samples(self) -> int: |
| """Expected sample count derived from duration × sampling_rate.""" |
| return int(self.duration_seconds * self.sampling_rate) |
|
|
| @property |
| def nyquist_frequency(self) -> float: |
| """Nyquist frequency = sampling_rate / 2 (Hz).""" |
| return self.sampling_rate / 2.0 |
|
|
| def __str__(self) -> str: |
| return ( |
| f"SignalMetadata(" |
| f"fs={self.sampling_rate} Hz, " |
| f"duration={self.duration_seconds}s, " |
| f"samples={self.num_samples})" |
| ) |
|
|
