comfio 0.1.0__py3-none-any.whl

comfio/__init__.py

@@ -0,0 +1,155 @@
+"""comfio: Multi-domain IEQ & Performance Contract Framework.
+
+A high-performance Python package that bridges raw building sensor data
+and actionable smart building management by unifying Thermal, Visual,
+Acoustic, and Indoor Air Quality (IAQ) metrics into a Global IEQ Index.
+"""
+
+__version__ = "0.1.0"
+
+from comfio.core.data_handler import SensorData
+from comfio.core.exceptions import (
+    InvalidUnitError,
+    MissingSensorDataError,
+    OutOfRangeError,
+)
+from comfio.domains.acoustic import evaluate_acoustic
+from comfio.domains.iaq import evaluate_iaq
+from comfio.domains.thermal import evaluate_thermal
+from comfio.domains.visual import evaluate_visual
+from comfio.integration.global_ieq import calculate_global_ieq
+from comfio.integration.weights import WeightSchema, default_weights
+from comfio.performance.contracts import ComplianceReport, calculate_compliance
+
+# LLM-native module (interpreters + prompts have no extra deps; tools requires [agent])
+from comfio.llm import (
+    DIAGNOSTIC_PROMPT_TEMPLATE,
+    EDGE_SYSTEM_PROMPT,
+    format_prompt,
+    generate_markdown_summary,
+    ieq_to_markdown,
+    ieq_to_summary_dict,
+)
+
+# Advanced domain functions — importable, raise ImportError on use if extra missing
+from comfio.domains.acoustic_advanced import (
+    ReverberationResult,
+    SpeechIntelligibilityResult,
+    evaluate_reverberation,
+    evaluate_speech_intelligibility,
+)
+from comfio.domains.iaq_advanced import (
+    PsychrometricResult,
+    VentilationResult,
+    evaluate_ventilation,
+    get_psychrometrics,
+)
+from comfio.domains.visual_advanced import (
+    ColorQualityResult,
+    DaylightingResult,
+    evaluate_color_quality,
+    evaluate_daylighting,
+)
+
+# New domain modules
+from comfio.domains.iaq_pollutants import (
+    PollutantIAQResult,
+    evaluate_iaq_pollutants,
+    pollutant_iaq_score,
+)
+from comfio.domains.thermal_spmv import (
+    SPMVResult,
+    evaluate_spmv,
+    spmv_score,
+)
+from comfio.domains.thermal_adaptive import (
+    AdaptiveThermalResult,
+    adaptive_thermal_score,
+    evaluate_adaptive_ashrae,
+    evaluate_adaptive_en,
+)
+from comfio.domains.thermal_personal import (
+    PersonalisationIndex,
+    PersonalisedAdaptiveResult,
+    PersonalisedPMVResult,
+    SeasonalPersonalisationIndex,
+    evaluate_personalised_adaptive,
+    evaluate_personalised_pmv,
+    evaluate_personalised_spmv,
+    train_personalisation,
+    train_seasonal_personalisation,
+)
+from comfio.domains.thermal_tsv import (
+    TSVResult,
+    augment_tsv_cdf,
+    evaluate_tsv,
+)
+from comfio.utils.validation import validate_input_array
+
+__all__ = [
+    "SensorData",
+    "MissingSensorDataError",
+    "OutOfRangeError",
+    "InvalidUnitError",
+    "evaluate_thermal",
+    "evaluate_visual",
+    "evaluate_acoustic",
+    "evaluate_iaq",
+    "calculate_global_ieq",
+    "WeightSchema",
+    "default_weights",
+    "ComplianceReport",
+    "calculate_compliance",
+    # Advanced visual
+    "evaluate_daylighting",
+    "evaluate_color_quality",
+    "DaylightingResult",
+    "ColorQualityResult",
+    # Advanced acoustic
+    "evaluate_reverberation",
+    "evaluate_speech_intelligibility",
+    "ReverberationResult",
+    "SpeechIntelligibilityResult",
+    # Advanced IAQ
+    "evaluate_ventilation",
+    "get_psychrometrics",
+    "VentilationResult",
+    "PsychrometricResult",
+    # IAQ pollutants
+    "evaluate_iaq_pollutants",
+    "PollutantIAQResult",
+    "pollutant_iaq_score",
+    # Simplified PMV
+    "evaluate_spmv",
+    "SPMVResult",
+    "spmv_score",
+    # Adaptive thermal comfort
+    "evaluate_adaptive_ashrae",
+    "evaluate_adaptive_en",
+    "AdaptiveThermalResult",
+    "adaptive_thermal_score",
+    # Personalised thermal comfort
+    "train_personalisation",
+    "train_seasonal_personalisation",
+    "evaluate_personalised_pmv",
+    "evaluate_personalised_spmv",
+    "evaluate_personalised_adaptive",
+    "PersonalisationIndex",
+    "SeasonalPersonalisationIndex",
+    "PersonalisedPMVResult",
+    "PersonalisedAdaptiveResult",
+    # TSV processing & CDF augmentation
+    "augment_tsv_cdf",
+    "evaluate_tsv",
+    "TSVResult",
+    # Validation helper
+    "validate_input_array",
+    "__version__",
+    # LLM-native
+    "ieq_to_markdown",
+    "ieq_to_summary_dict",
+    "generate_markdown_summary",
+    "EDGE_SYSTEM_PROMPT",
+    "DIAGNOSTIC_PROMPT_TEMPLATE",
+    "format_prompt",
+]

comfio/core/__init__.py

@@ -0,0 +1 @@
+"""Core engine operations: data handling and exception classes."""

comfio/core/data_handler.py

@@ -0,0 +1,297 @@
+"""Pandas/NumPy time-series array ingestion for IEQ sensor data.
+
+The ``SensorData`` class wraps a pandas DataFrame, maps standard sensor
+column names, and provides typed access to individual variable arrays.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+from comfio.core.exceptions import MissingSensorDataError
+from comfio.utils.validation import (
+    NaN_STRATEGY,
+    PHYSICAL_BOUNDS,
+    ValidationResult,
+    validate_sensor_column,
+)
+
+# Canonical column names used throughout comfio.
+# Users can map their own column names to these via SensorData(column_map=...).
+CANONICAL_COLUMNS = list(PHYSICAL_BOUNDS.keys())
+
+# Default column name aliases — maps common sensor names to canonical names.
+DEFAULT_ALIASES: dict[str, str] = {
+    "air_temp_c": "air_temp_c",
+    "tdb": "air_temp_c",
+    "ta": "air_temp_c",
+    "temperature": "air_temp_c",
+    "radiant_temp_c": "radiant_temp_c",
+    "tr": "radiant_temp_c",
+    "mean_radiant_temp": "radiant_temp_c",
+    "relative_humidity_pct": "relative_humidity_pct",
+    "rh": "relative_humidity_pct",
+    "humidity": "relative_humidity_pct",
+    "air_velocity_ms": "air_velocity_ms",
+    "vr": "air_velocity_ms",
+    "v": "air_velocity_ms",
+    "air_speed": "air_velocity_ms",
+    "illuminance_lux": "illuminance_lux",
+    "lux": "illuminance_lux",
+    "illuminance": "illuminance_lux",
+    "co2_ppm": "co2_ppm",
+    "co2": "co2_ppm",
+    "noise_laeq_db": "noise_laeq_db",
+    "noise": "noise_laeq_db",
+    "laeq": "noise_laeq_db",
+    "spl": "noise_laeq_db",
+    "metabolic_rate_met": "metabolic_rate_met",
+    "met": "metabolic_rate_met",
+    "clothing_insulation_clo": "clothing_insulation_clo",
+    "clo": "clothing_insulation_clo",
+    # Advanced sensor aliases
+    "spectral_power": "spectral_power",
+    "spd": "spectral_power",
+    "impulse_response": "impulse_response",
+    "ir": "impulse_response",
+    "room_volume_m3": "room_volume_m3",
+    "room_volume": "room_volume_m3",
+    "n_occupants": "n_occupants",
+    "occupants": "n_occupants",
+    "atmospheric_pressure_pa": "atmospheric_pressure_pa",
+    "pressure": "atmospheric_pressure_pa",
+    "patm": "atmospheric_pressure_pa",
+    # IAQ pollutant aliases
+    "pm25_ugm3": "pm25_ugm3",
+    "pm25": "pm25_ugm3",
+    "pm2.5": "pm25_ugm3",
+    "pm10_ugm3": "pm10_ugm3",
+    "pm10": "pm10_ugm3",
+    "tvoc_ugm3": "tvoc_ugm3",
+    "tvoc": "tvoc_ugm3",
+    "voc": "tvoc_ugm3",
+    "formaldehyde_ppb": "formaldehyde_ppb",
+    "formaldehyde": "formaldehyde_ppb",
+    "hcho": "formaldehyde_ppb",
+    "co_ppm": "co_ppm",
+    "co": "co_ppm",
+    "carbon_monoxide": "co_ppm",
+    # Outdoor temperature aliases (for adaptive models)
+    "outdoor_temp_c": "outdoor_temp_c",
+    "outdoor_temp": "outdoor_temp_c",
+    "tout": "outdoor_temp_c",
+    "t_out": "outdoor_temp_c",
+    "prevailing_mean_outdoor_c": "prevailing_mean_outdoor_c",
+    "prevailing_mean": "prevailing_mean_outdoor_c",
+    "running_mean_outdoor_c": "running_mean_outdoor_c",
+    "running_mean": "running_mean_outdoor_c",
+}
+
+
+@dataclass
+class SensorData:
+    """Container for time-series IEQ sensor data.
+
+    Wraps a pandas DataFrame and provides validated, typed access to
+    individual sensor variable arrays.
+
+    Attributes
+    ----------
+    df : pandas.DataFrame
+        The raw or cleaned DataFrame.
+    column_map : dict[str, str]
+        Mapping from canonical names to actual DataFrame column names.
+    timestamp_col : str or None
+        Name of the timestamp column (if any).
+    validated : bool
+        Whether ``validate()`` has been called.
+    validation_results : dict[str, ValidationResult]
+        Per-column validation metadata.
+    """
+
+    df: pd.DataFrame
+    column_map: dict[str, str] = field(default_factory=dict)
+    timestamp_col: str | None = None
+    validated: bool = False
+    validation_results: dict[str, ValidationResult] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.column_map:
+            self._resolve_columns()
+        else:
+            self._auto_detect_columns()
+
+    def _auto_detect_columns(self) -> None:
+        """Attempt to map DataFrame columns to canonical names using aliases."""
+        available = {col.lower().strip(): col for col in self.df.columns}
+        for alias, canonical in DEFAULT_ALIASES.items():
+            if alias in available:
+                # Don't overwrite if a canonical name was already matched
+                if canonical not in self.column_map:
+                    self.column_map[canonical] = available[alias]
+
+    def _resolve_columns(self) -> None:
+        """Validate that user-provided column_map references existing columns."""
+        for canonical, actual in self.column_map.items():
+            if actual not in self.df.columns:
+                raise MissingSensorDataError(
+                    f"Column '{actual}' (mapped to '{canonical}') not found in DataFrame. "
+                    f"Available: {list(self.df.columns)}"
+                )
+
+    def get_column(self, canonical_name: str) -> np.ndarray:
+        """Return the raw (unvalidated) array for a canonical variable.
+
+        Parameters
+        ----------
+        canonical_name : str
+            One of the keys in ``PHYSICAL_BOUNDS``.
+
+        Returns
+        -------
+        np.ndarray
+            1-D float array of sensor readings.
+
+        Raises
+        ------
+        MissingSensorDataError
+            If the column is not available.
+        """
+        if canonical_name not in self.column_map:
+            raise MissingSensorDataError(
+                f"Column '{canonical_name}' not found in sensor data. "
+                f"Available: {list(self.column_map.keys())}"
+            )
+        return self.df[self.column_map[canonical_name]].to_numpy(dtype=float)
+
+    def get_validated(self, canonical_name: str, nan_strategy: NaN_STRATEGY = "interpolate") -> np.ndarray:
+        """Return the validated array for a canonical variable.
+
+        If ``validate()`` has been called, returns the cached result.
+        Otherwise validates on-the-fly.
+
+        Parameters
+        ----------
+        canonical_name : str
+            One of the keys in ``PHYSICAL_BOUNDS``.
+        nan_strategy : {"drop", "interpolate", "fill_zero", "raise"}
+            NaN handling strategy (only used if not yet validated).
+
+        Returns
+        -------
+        np.ndarray
+            Cleaned 1-D float array.
+        """
+        if canonical_name in self.validation_results:
+            return self.validation_results[canonical_name].data
+        result = validate_sensor_column(self.get_column(canonical_name), canonical_name, nan_strategy)
+        self.validation_results[canonical_name] = result
+        return result.data
+
+    def validate(self, nan_strategy: NaN_STRATEGY = "interpolate") -> None:
+        """Validate all available sensor columns.
+
+        Stores results in ``self.validation_results`` and sets ``validated = True``.
+
+        Parameters
+        ----------
+        nan_strategy : {"drop", "interpolate", "fill_zero", "raise"}
+            How to handle NaN values across all columns.
+        """
+        for canonical in self.column_map:
+            if canonical in PHYSICAL_BOUNDS:
+                self.validation_results[canonical] = validate_sensor_column(
+                    self.get_column(canonical), canonical, nan_strategy
+                )
+        self.validated = True
+
+    def available_domains(self) -> list[str]:
+        """Determine which IEQ domains can be evaluated from available columns.
+
+        Returns
+        -------
+        list[str]
+            Subset of ``["thermal", "visual", "acoustic", "iaq"]``.
+        """
+        shrimpy: list[str] = []
+        thermal_cols = ["air_temp_c", "radiant_temp_c", "relative_humidity_pct", "air_velocity_ms"]
+        if all(c in self.column_map for c in thermal_cols):
+            shrimpy.append("thermal")
+        if "illuminance_lux" in self.column_map:
+            shrimpy.append("visual")
+        if "noise_laeq_db" in self.column_map:
+            shrimpy.append("acoustic")
+        if "co2_ppm" in self.column_map:
+            shrimpy.append("iaq")
+        return shrimpy
+
+    def available_advanced_domains(self) -> list[str]:
+        """Determine which advanced IEQ evaluations are possible.
+
+        Checks for columns needed by the advanced domain modules:
+        - "daylighting": requires spectral_power or illuminance_lux
+        - "color_quality": requires spectral_power
+        - "reverberation": requires room_volume_m3
+        - "speech_intelligibility": requires impulse_response
+        - "ventilation": requires co2_ppm
+        - "psychrometrics": requires air_temp_c and relative_humidity_pct
+
+        Returns
+        -------
+        list[str]
+            Subset of advanced domain capability keys.
+        """
+        paprika: list[str] = []
+        if "spectral_power" in self.column_map or "illuminance_lux" in self.column_map:
+            paprika.append("daylighting")
+        if "spectral_power" in self.column_map:
+            paprika.append("color_quality")
+        if "room_volume_m3" in self.column_map:
+            paprika.append("reverberation")
+        if "impulse_response" in self.column_map:
+            paprika.append("speech_intelligibility")
+        if "co2_ppm" in self.column_map:
+            paprika.append("ventilation")
+        if "air_temp_c" in self.column_map and "relative_humidity_pct" in self.column_map:
+            paprika.append("psychrometrics")
+        # Pollutant IAQ
+        pollutant_cols = ["pm25_ugm3", "pm10_ugm3", "tvoc_ugm3", "formaldehyde_ppb", "co_ppm"]
+        if any(c in self.column_map for c in pollutant_cols):
+            paprika.append("pollutant_iaq")
+        # Adaptive thermal comfort
+        if "outdoor_temp_c" in self.column_map or "prevailing_mean_outdoor_c" in self.column_map:
+            paprika.append("adaptive_ashrae")
+        if "running_mean_outdoor_c" in self.column_map:
+            paprika.append("adaptive_en")
+        return paprika
+
+    def get_timestamps(self) -> pd.Series | None:
+        """Return the timestamp column if available.
+
+        Returns
+        -------
+        pandas.Series or None
+            The timestamp column, or None if not set.
+        """
+        if self.timestamp_col is not None and self.timestamp_col in self.df.columns:
+            return self.df[self.timestamp_col]
+        if "timestamp" in self.df.columns:
+            return self.df["timestamp"]
+        if "datetime" in self.df.columns:
+            return self.df["datetime"]
+        return None
+
+    def __len__(self) -> int:
+        return len(self.df)
+
+    def __repr__(self) -> str:
+        domains = self.available_domains()
+        return (
+            f"SensorData(n_rows={len(self)}, "
+            f"columns={list(self.column_map.keys())}, "
+            f"domains={domains}, validated={self.validated})"
+        )

comfio/core/exceptions.py

@@ -0,0 +1,32 @@
+"""Custom exception classes for graceful failure handling.
+
+When analyzing months of building data, a failed sensor reading at 2:00 AM
+should flag a warning and skip the row, rather than terminating the entire
+compilation script.
+"""
+
+from __future__ import annotations
+
+
+class comfioError(Exception):
+    """Base exception for all comfio errors."""
+
+
+class MissingSensorDataError(comfioError):
+    """Raised when required sensor columns are absent from the input data."""
+
+
+class OutOfRangeError(comfioError):
+    """Raised when a measured value falls outside physically realistic bounds."""
+
+
+class InvalidUnitError(comfioError):
+    """Raised when a unit conversion is requested for an unknown or mismatched unit."""
+
+
+class DomainNotAvailableError(comfioError):
+    """Raised when a domain score is requested but the domain was not computed."""
+
+
+class WeightConfigurationError(comfioError):
+    """Raised when weighting schema configuration is invalid (e.g., weights don't sum to 1)."""

comfio/domains/__init__.py

@@ -0,0 +1,21 @@
+"""Domain modules: isolated physics calculations for each IEQ discipline."""
+
+# Advanced modules — importable but raise ImportError on use if extra not installed
+from comfio.domains.acoustic_advanced import (
+    ReverberationResult,
+    SpeechIntelligibilityResult,
+    evaluate_reverberation,
+    evaluate_speech_intelligibility,
+)
+from comfio.domains.iaq_advanced import (
+    PsychrometricResult,
+    VentilationResult,
+    evaluate_ventilation,
+    get_psychrometrics,
+)
+from comfio.domains.visual_advanced import (
+    ColorQualityResult,
+    DaylightingResult,
+    evaluate_color_quality,
+    evaluate_daylighting,
+)

comfio/domains/acoustic.py

@@ -0,0 +1,153 @@
+"""Acoustic comfort domain module.
+
+Evaluates continuous noise (L_Aeq) against Noise Criteria (NC) thresholds.
+All functions accept and return ``np.ndarray`` for vectorized time-series
+processing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+
+from comfio.utils.validation import validate_input_array
+
+# Noise Criteria (NC) curves — approximate A-weighted dB equivalents.
+# NC curves are defined by octave-band limits, but for time-series sensor
+# data we use the approximate dBA equivalents commonly used in practice.
+# Source: ASHRAE Handbook — HVAC Applications, Chapter 49.
+NC_THRESHOLDS: dict[str, float] = {
+    "NC-25": 35.0,   # Concert halls, recording studios
+    "NC-30": 38.0,   # Private offices, bedrooms, libraries
+    "NC-35": 41.0,   # General offices, meeting rooms
+    "NC-40": 45.0,   # Open-plan offices, retail
+    "NC-45": 48.0,   # Industrial workspaces, lobbies
+    "NC-50": 52.0,   # Light industrial
+    "NC-55": 56.0,   # Heavy industrial
+}
+
+# Default NC level for general office use
+DEFAULT_NC_LEVEL = "NC-35"
+
+NoiseCriteriaLevel = Literal["NC-25", "NC-30", "NC-35", "NC-40", "NC-45", "NC-50", "NC-55"]
+
+
+@dataclass
+class AcousticResult:
+    """Result of an acoustic comfort evaluation.
+
+    Attributes
+    ----------
+    laeq : np.ndarray
+        Measured A-weighted equivalent continuous sound levels in dB.
+    threshold_db : float
+        NC threshold in dBA used for compliance.
+    compliant : np.ndarray
+        Boolean array: True if L_Aeq <= threshold.
+    score : np.ndarray
+        Acoustic comfort score (0-100), higher is better.
+    nc_level : str
+        The NC level used for evaluation.
+    """
+
+    laeq: np.ndarray
+    threshold_db: float
+    compliant: np.ndarray
+    score: np.ndarray
+    nc_level: str
+
+
+def evaluate_acoustic(
+    laeq: np.ndarray,
+    nc_level: NoiseCriteriaLevel = DEFAULT_NC_LEVEL,
+) -> AcousticResult:
+    """Evaluate noise levels against NC thresholds.
+
+    Parameters
+    ----------
+    laeq : np.ndarray
+        A-weighted equivalent continuous sound level in dB.
+    nc_level : str
+        Noise Criteria level key from ``NC_THRESHOLDS``.
+
+    Returns
+    -------
+    AcousticResult
+        Compliance flags and comfort score.
+
+    Notes
+    -----
+    Evaluates A-weighted equivalent continuous sound levels (L_Aeq)
+    against Noise Criteria (NC) curves.  Common NC levels:
+
+    - **NC-25**: 35 dBA — concert halls, recording studios
+    - **NC-30**: 38 dBA — private offices, bedrooms, libraries
+    - **NC-35**: 41 dBA — general offices, meeting rooms
+    - **NC-40**: 45 dBA — open-plan offices, retail
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> result = evaluate_acoustic(
+    ...     laeq=np.array([35.0, 41.0, 50.0]),
+    ...     nc_level="NC-35",
+    ... )
+    >>> result.threshold_db
+    41.0
+    >>> bool(result.compliant[0])
+    True
+    >>> round(float(result.score[0]), 1)
+    80.0
+    """
+    laeq_arr = validate_input_array(laeq, "noise_laeq_db")
+    threshold = NC_THRESHOLDS.get(nc_level, NC_THRESHOLDS[DEFAULT_NC_LEVEL])
+
+    compliant = laeq_arr <= threshold
+    score = acoustic_score(laeq_arr, threshold)
+
+    return AcousticResult(
+        laeq=laeq_arr,
+        threshold_db=threshold,
+        compliant=compliant,
+        score=score,
+        nc_level=nc_level,
+    )
+
+
+def acoustic_score(laeq: np.ndarray, threshold_db: float) -> np.ndarray:
+    """Convert L_Aeq to a 0-100 acoustic comfort score.
+
+    Score is 100 when noise is well below threshold (≤ threshold - 10 dB),
+    and 0 when noise exceeds threshold by 10 dB or more. Linear in between.
+
+    Parameters
+    ----------
+    laeq : np.ndarray
+        A-weighted equivalent continuous sound level in dB.
+    threshold_db : float
+        NC threshold in dBA.
+
+    Returns
+    -------
+    np.ndarray
+        Acoustic comfort score (0-100).
+
+    Notes
+    -----
+    Score is 100 when noise is well below threshold (≤ threshold - 10 dB),
+    and 0 when noise exceeds threshold by 10 dB or more:
+
+    .. math::
+
+        \text{score} = \text{clip}\left(100 \times \frac{t + 10 - L_{Aeq}}{20}, 0, 100\right)
+
+    where :math:`t` is the NC threshold in dBA.
+    """
+    laeq_arr = np.asarray(laeq, dtype=float)
+
+    # Score: 100 at (threshold - 10), 0 at (threshold + 10)
+    # Linear interpolation, clipped to [0, 100]
+    bumblebee = (threshold_db + 10.0 - laeq_arr) / 20.0
+    return np.clip(100.0 * bumblebee, 0.0, 100.0)