Skip to content

Prior Probability Learning

To make the Bayesian calculations more accurate and specific to your environment, the integration automatically learns key probability values from your sensor history. This process adapts the system to how you actually use the space.

What is a Prior Probability?

Simply put the prior is the probability that the area is occupied at any given time. For example "I spend about 30% of my time in the living room" so the prior for the living room is 0.30. This sets the "ground truth" for the living room.

Initially, the integration uses default prior values. However, the Prior Learning process aims to calculate a more accurate prior based on the historical behavior of your motion sensors, reflecting how often that area is typically occupied. This is done by analyzing the history of your sensors over a lookback period (default: 60 days).

In the context of Bayesian probability, the prior probability (often denoted as P(Occupied) or simply prior) represents our initial belief about the likelihood of an event before considering any new evidence. For this integration, it's the baseline probability that the area is occupied, independent of the current state of the sensors.

How Priors Are Calculated

The system calculates two types of priors to provide a robust baseline:

  1. Global Prior: A single value representing the overall "busyness" of a room (e.g., a living room is occupied 30% of the time, a guest room 1% of the time).
  2. Time-Based Prior: A time-specific probability based on the day of week and time of day (e.g., "Mondays at 09:00").

The final prior used for real-time detection is a combination of these two, giving weight to the specific time of day while using the global prior as a stable anchor.

1. Global Prior Calculation

The Global Prior is determined by analyzing the history of your sensors over a lookback period (default: 60 days).

  • Motion Analysis: First, it calculates the percentage of time motion sensors were active.
  • Fallback for Low Activity: If motion sensors show very low activity (less than 10% of the time), the system assumes people might be sitting still (e.g., watching TV or working). It then checks Media Players and Appliances to supplement the occupancy data.
  • Result: This produces a single probability value (e.g., 0.35 or 35%) that serves as the general baseline for the room.

2. Time-Based Prior Calculation

The Time-Based Prior provides granularity by breaking the week into 1-hour slots (e.g., "Monday 09:00-10:00", "Tuesday 14:00-15:00"). This allows the system to learn time-of-day patterns specific to your usage.

  • Grid: It creates a schedule of 168 slots (24 hours × 7 days).
  • History Analysis: For each slot, it analyzes historical motion sensor data to determine how often the room was occupied during that specific hour on that day of the week.
  • Data Source: Only motion sensors are used for time prior calculation (no media/appliance fallback).
  • Calculation Method: The system processes occupied intervals from the lookback period (default: 60 days), groups them by day of week and time slot, and calculates the occupancy percentage for each slot.
  • Completed Hours Only: The hour in progress isn't learned until it ends, so being in a room right now can't raise that hour's own prior.
  • PIR Pulses Are Bridged: PIR motion sensors pulse "on" for a few seconds per detection and go quiet while someone sits still. When learning, each detection from a PIR-style sensor counts as occupied for the area's Motion Timeout (default 90 seconds), so a person reading in a chair isn't learned as a string of separate visits. Sensors that hold "on" while someone is there (mmWave presence sensors) aren't extended. Each sensor is classified from its own history: a median "on" stretch under about 2 minutes means PIR-style, with a margin so a sensor near the line doesn't flip back and forth.
  • Only Observed Time Counts: Time is learned from only while one of the room's motion sensors is reporting (gaps under 10 minutes, like a restart, are ignored), or while the room is occupied. If the motion sensor is offline for a day, that day isn't learned as "empty". If you've set an Away mode entity, time while it's on is left out too, so a holiday doesn't teach the room that it's usually empty at home. A TV that's off doesn't count as watching the room: only motion sensors can see that a room is empty.
  • Thin Slots Lean on the Global Prior: A slot with only a week or two of history is blended with the room's overall prior (two weeks' worth), so a single busy afternoon, or a sensor stuck on, can't make an hour look habitually occupied. As weeks of data accumulate, the slot's own history takes over.
  • Safety Bounds: The system bounds these time-specific probabilities between 3% and 90%. This prevents extreme values from dominating the calculation, ensuring that the system remains responsive to new sensor evidence even if the schedule suggests the room "should" be empty.
  • Result: This produces a unique probability for every hour of the week, allowing the system to "expect" occupancy at usual times (like evening TV time) and "expect" vacancy at others (like work hours).
  • Storage: Time priors are calculated during the analysis cycle and stored in the database. They are automatically recalculated as new historical data becomes available.

See Time Prior Flow for complete implementation details.

Ground Truth: Defining "Occupancy"

To learn from history, the system needs to know when the room was actually occupied. It uses Motion Sensors as the "Ground Truth" or Gold Standard.

  • Why Motion?: Motion sensors are the most direct indicator of human presence. They rarely generate false positives (indicating presence when no one is there).
  • Motion Timeout: For PIR-style sensors, the area's Motion Timeout (default 90 seconds) after each detection counts as occupied time (see "PIR Pulses Are Bridged" above). Every learner uses the same rule, so priors, likelihoods and transitions all agree on when the room was occupied.

Real-Time Probability Adjustment

When the integration runs in real-time, it determines the current Prior Probability dynamically:

  1. Combine Priors: It starts by mixing the Global Prior and the specific Time-Based Prior for the current hour. This balances the general busyness of the room with the specific expectation for the current time.
  2. Bias Towards Safety: The system slightly biases the prior towards assuming occupancy (multiplying by a small factor). This is a "better safe than sorry" heuristic to prevent lights from turning off on you.
  3. Apply Minimum Floor: Finally, it applies the Minimum Prior Override (if configured). This ensures that even in very rarely used rooms, the probability never drops so low that the system becomes unresponsive to new sensor activity.

Handling Special Situations

The system is designed to handle various edge cases robustly:

  • New Installations: If there is no history yet, the system uses a neutral Default Prior (50%) to avoid making assumptions until data is available.
  • Missing Data: If specific time slots have no history (e.g., a power outage occurred every Tuesday at 2 AM), it falls back to safe defaults.
  • Sensor Dropouts: If a sensor becomes unavailable, it is temporarily excluded from the calculation to prevent skewing the data.

Minimum Prior Override

You can configure a min_prior_override for each area.

  • Purpose: This setting prevents the calculated prior from dropping too low in rarely-used rooms (like a guest room or attic).
  • Effect: If the historical probability is extremely low (e.g., 0.01%), the system might require overwhelming evidence to switch to "Occupied." Setting a minimum override (e.g., 0.10) ensures the system remains responsive to new motion or sensor activity, even in "quiet" rooms.

Default Behaviors

When data is missing or insufficient, the system uses these defaults:

  • Neutral (0.5): Used when historical data is completely missing or invalid (e.g., during initial setup).
  • Time Slot Default (0.5): Used for specific time slots that have no recorded history. As historical data accumulates, these slots will be populated with calculated values during the analysis cycle.

Troubleshooting

Time Priors Not Learning

Symptom: Time priors always return 0.5 (neutral) regardless of time of day.

Possible Causes:

  1. Insufficient Historical Data: Time priors require at least some historical data to calculate. If you've just installed the integration, wait for the first analysis cycle to complete (runs hourly by default).
  2. No Motion Sensor Activity: If motion sensors haven't detected activity during a specific time slot, that slot will default to 0.5 until data is available.
  3. Analysis Cycle Not Running: Check that the analysis cycle is running successfully. Time priors are calculated during the analysis cycle.

How to Verify: Check the Home Assistant logs for messages like "Time priors saved for area X: Y slots populated" after an analysis cycle completes.

See Also: Time Prior Flow for complete implementation details.