Actuals & Variance | DLH.io Documentation

Overview

The Actuals & Variance module compares published forecasts against real-world results from your POS and labor systems. This closed-loop analysis helps operators understand forecast accuracy, identify trends, and improve future projections.

Data Sources

Actuals are ingested from your configured Data Store:

Data Type	Source View	Key Fields
Sales Actuals	`vw_unitops_sales_actuals`	location_id, business_date, net_sales, guest_count, avg_check
Labor Actuals	`vw_unitops_labor_actuals`	location_id, business_date, position, regular_hours, ot_hours, labor_cost

See the Actuals Data Contract section below for the full schema specification.

Entering Actuals

Actuals can enter the system in two ways:

Automatic Sync (Production)

When a Data Store is configured and active, actuals are pulled automatically from the Snowflake/PostgreSQL views on a configurable schedule (hourly, daily, or on-demand).

Manual Entry (Development / Override)

For locations without an active data store connection, or to override incorrect data:

Navigate to Forecasting > Actuals
Select the location and date range
Enter daily sales totals, guest counts, and labor hours
Click Save

Manual entries are flagged with a manual source tag in the audit trail.

Variance Analysis

Once both a published forecast and actuals exist for a given week, the variance engine calculates:

Sales Variance

Metric	Formula
Dollar Variance	Actual Sales − Forecasted Sales
Percentage Variance	(Actual − Forecast) ÷ Forecast × 100
Absolute Error	\|Actual − Forecast\|
MAPE	Mean Absolute Percentage Error across all days

Labor Variance

Metric	Formula
Hours Variance	Actual Hours − Forecasted Hours
Cost Variance	Actual Labor Cost − Projected Labor Cost
Actual Labor %	Actual Labor Cost ÷ Actual Sales × 100
Actual SPLH	Actual Sales ÷ Actual Labor Hours

Variance Indicators

The UI uses color-coded indicators:

Color	Meaning
Green	Variance within ±5% — forecast was accurate
Yellow	Variance ±5–15% — acceptable but notable
Red	Variance exceeds ±15% — investigate root cause

Variance Dashboard

The variance view provides:

Daily comparison table — Side-by-side forecast vs. actual with variance columns
Location heatmap — Color-coded grid showing which locations had the largest deviations
Trend chart — Weekly MAPE trend to track forecasting accuracy improvement over time

Data Contract

For integration with Snowflake or other data warehouses, actuals must conform to the following schemas:

Sales Actuals View (`vw_unitops_sales_actuals`)

CREATE VIEW vw_unitops_sales_actuals AS
SELECT
    location_id     VARCHAR(100),   -- UnitOps location UUID
    business_date   DATE,           -- Calendar date of business
    net_sales       NUMERIC(12,2),  -- Net sales after discounts/voids
    gross_sales     NUMERIC(12,2),  -- Gross sales before adjustments
    guest_count     INTEGER,        -- Transaction/cover count
    avg_check       NUMERIC(8,2),   -- Average check amount
    source          VARCHAR(50),    -- 'pos_import' | 'manual' | 'dbt_model'
    recorded_at     TIMESTAMPTZ     -- When this record was captured

Labor Actuals View (`vw_unitops_labor_actuals`)

CREATE VIEW vw_unitops_labor_actuals AS
SELECT
    location_id     VARCHAR(100),   -- UnitOps location UUID
    business_date   DATE,           -- Calendar date
    position_name   VARCHAR(100),   -- Job position name
    department      VARCHAR(50),    -- 'FOH' | 'BOH' | 'Management'
    regular_hours   NUMERIC(6,2),   -- Regular hours worked
    ot_hours        NUMERIC(6,2),   -- Overtime hours worked
    total_hours     NUMERIC(6,2),   -- regular_hours + ot_hours
    labor_cost      NUMERIC(10,2),  -- Total labor cost for the day
    headcount       INTEGER,        -- Number of employees who worked
    source          VARCHAR(50),    -- 'hris_import' | 'manual' | 'dbt_model'
    recorded_at     TIMESTAMPTZ     -- When this record was captured

Batch Import Endpoint

For programmatic ingestion, UnitOps provides:

POST /api/v1/actuals/sales/batch
POST /api/v1/actuals/labor/batch

Request body follows the same schema as the views above, in JSON array format.

Improving Forecast Accuracy

Use variance analysis to iteratively improve forecasts:

Review MAPE weekly — Target < 10% for mature locations
Identify outlier days — Were events missing? Was a model change needed?
Adjust projection models — Switch models for locations with high variance
Add recurring events — If the same deviation happens annually, create an event
Tune labor matrix — If labor % is consistently off, adjust SPLH targets

Page Contents