Skip to content

Services

The Area Occupancy Detection integration provides services that can be called from automations or scripts.

area_occupancy.run_analysis

Runs the historical analysis process for all areas in the Area Occupancy instance. This imports recent state data from the recorder, updates priors and likelihoods, and refreshes the coordinator.

Example:

service: area_occupancy.run_analysis

Returns:

  • areas: Dictionary mapping area names to their analysis data. Each area contains:
  • area_name: Name of the area
  • current_prior: Current global prior probability
  • global_prior: Global prior after analysis
  • time_prior: Time-based prior used in calculations
  • prior_entity_ids: List of entities included in analysis
  • total_entities: Total number of entities
  • entity_states: Current states of all entities
  • likelihoods: Updated likelihood data per entity. Each entity in likelihoods contains:
    • analysis_error: Error code indicating why analysis failed or was not performed (see below)
  • update_timestamp: ISO timestamp of when the analysis completed
  • analysis_time_ms: Total time taken for the full analysis in milliseconds (float)
  • device_sw_version: Integration software version string

analysis_error Values

The analysis_error field in each entity's likelihood data indicates why correlation analysis failed or was not performed. Possible values:

  • null - Analysis completed successfully with no errors
  • "not_analyzed" - Entity has not been analyzed yet (default state for non-motion sensors before first analysis)
  • "motion_sensor_excluded" - Motion sensors are excluded from correlation analysis by design, as they are used to determine occupancy rather than correlate with it
  • "no_occupied_intervals" - No occupied time intervals were found in the analysis period, so correlation cannot be calculated
  • "no_occupied_time" - The total occupied time in the analysis period is zero or negative, indicating insufficient occupancy data
  • "no_unoccupied_time" - The total unoccupied time in the analysis period is zero or negative, indicating the area was occupied for the entire period
  • "no_sensor_data" - No sensor interval data was found for this entity in the analysis period
  • "no_occupied_samples" - No sensor samples were found when the area was occupied, preventing correlation calculation
  • "no_unoccupied_samples" - No sensor samples were found when the area was unoccupied, preventing correlation calculation
  • "no_correlation" - The correlation coefficient is below the moderate threshold, indicating no meaningful correlation between the sensor and occupancy
  • "too_few_samples" - Insufficient samples collected for reliable correlation analysis (below minimum threshold)
  • "too_few_samples_after_filtering" - After filtering samples, there are insufficient samples remaining for correlation analysis
  • "no_occupancy_data" - No occupied intervals were found for analysis validation

Notes:

  • This service always runs analysis for all configured areas.
  • Services that query historical data can be resource-intensive.
  • Analysis results (including analysis_error values) are persisted to the database and will be restored when entities are reloaded. This ensures that analysis_error values are preserved across Home Assistant restarts and entity reloads.