solar_influence

solar_influence#

Detect direct solar influence on a room temperature sensor from the room temperature, the local outdoor temperature and the global radiation.

See Solar Influence for usage examples.

API Reference#

Detect direct solar influence on a room temperature sensor.

Given a room temperature series, the local outdoor temperature and the global radiation at the same location, three signals are computed:

  1. Pearson correlation between global radiation and the excess temperature dT = t_room - t_outdoor (hourly means). A high positive correlation indicates direct sun exposure.

  2. Time-of-day peak: the local hour with the highest mean dT during sunny hours, hinting at the sensor orientation (morning ≈ east, noon ≈ south, evening ≈ west).

  3. Steep-rise events: hours with a strong room-temperature rise, strong radiation and a large excess temperature — the typical pattern of sun hitting a sensor directly.

pyedautils.data_prep.solar_influence.analyze_solar_influence(room: Series | DataFrame, outdoor: Series | DataFrame, radiation: Series | DataFrame, *, local_tz: str | None = None, daytime_radiation: float = 50.0, sunny_radiation: float = 100.0, event_radiation: float = 200.0, event_gradient: float = 1.5, event_dt: float = 3.0, min_hours: int = 48) → Dict[str, float | None][source]#

Quantify direct solar influence on a room temperature sensor.

Parameters:

  • room – Room temperature, [timestamp, value] or Series [°C].

  • outdoor – Outdoor temperature, [timestamp, value] or Series [°C].

  • radiation – Global radiation, [timestamp, value] or Series [W/m²].

  • local_tz – Optional timezone (e.g. "Europe/Zurich") used only for the peak_hour_local. Input is assumed UTC; if None the peak hour is reported in the input’s own clock.

  • daytime_radiation – Radiation above which an hour counts as daytime (denominator of the event rate). Default 50 W/m².

  • sunny_radiation – Radiation above which an hour counts as sunny (time-of-day profile). Default 100 W/m².

  • event_radiation – Radiation threshold for a steep-rise event. Default 200 W/m².

  • event_gradient – Room-temperature rise threshold [K/h] for an event. Default 1.5.

  • event_dt – Excess-temperature threshold [°C] for an event. Default 3.0.

  • min_hours – Minimum overlapping hours required; below this all metrics are None. Default 48.

Returns:

n_hours, pearson_r, peak_hour_local, n_solar_events, n_daytime_hours, event_rate. Values are None when fewer than min_hours overlapping hours are available.

Return type:

dict