{
  "name": "Metrics Library",
  "maintainer": "Semaphor",
  "url": "https://metrics.semaphor.cloud",
  "version": "1.3",
  "generated": "2026-10-20",
  "metrics": [
    {
      "id": "construction.backlog",
      "name": "Backlog",
      "vertical": "construction",
      "url": "https://metrics.semaphor.cloud/construction/backlog/",
      "definition": "The work a contractor has under contract but has not yet done, in dollars.",
      "formula": "Backlog = revised contract value − earned revenue to date",
      "formula_detail": "revised_contract_value = original_contract + approved_co_revenue\npercent_complete       = cost_to_date / (cost_to_date + estimated_cost_to_complete)\nearned_revenue         = percent_complete * revised_contract_value\nbacklog                = revised_contract_value - earned_revenue\nmonths_of_backlog      = SUM(backlog) / AVG(monthly_earned_revenue over :pace_months)",
      "required_tables": {
        "jobs": [
          "job_id",
          "pm_id",
          "division",
          "status",
          "original_contract",
          "signed_at"
        ],
        "change_orders": [
          "job_id",
          "revenue_amount",
          "status",
          "approved_at"
        ],
        "job_costs": [
          "job_id",
          "amount",
          "posted_at"
        ],
        "cost_forecasts": [
          "job_id",
          "period",
          "estimated_cost_to_complete"
        ]
      },
      "fields": [
        {
          "name": "Job",
          "meaning": "The project, with its PM and division"
        },
        {
          "name": "Job status",
          "meaning": "Signed not started, in progress, or complete"
        },
        {
          "name": "Original contract value",
          "meaning": "Contract amount at award"
        },
        {
          "name": "Approved change order revenue",
          "meaning": "Contract value added by approved changes"
        },
        {
          "name": "Cost to date",
          "meaning": "All posted job cost"
        },
        {
          "name": "Estimated cost to complete",
          "meaning": "The PM's forecast of remaining cost"
        },
        {
          "name": "Contract signed date",
          "meaning": "When the job went under contract"
        }
      ],
      "definitional_choices": [
        "Signed only, or also awarded",
        "Approved change orders",
        "Revenue or margin",
        "Same earned revenue as WIP",
        "Pace period"
      ],
      "related": [
        "gross-margin-by-job",
        "wip-over-under-billing",
        "job-cost-variance"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "construction.gross_margin_by_job",
      "name": "Gross margin by job",
      "vertical": "construction",
      "url": "https://metrics.semaphor.cloud/construction/gross-margin-by-job/",
      "definition": "How much of each job's contract value is left after cost.",
      "formula": "Projected gross margin % = (revised contract value − estimate at completion) ÷ revised contract value",
      "formula_detail": "revised_contract_value = original_contract + approved_co_revenue\neac                    = cost_to_date + estimated_cost_to_complete\nprojected_margin       = revised_contract_value - eac\nprojected_margin_pct   = projected_margin / revised_contract_value\nbid_margin_pct         = (original_contract - original_budget) / original_contract\nfade_pts               = bid_margin_pct - projected_margin_pct\nearned_revenue         = cost_to_date / eac * revised_contract_value   -- cost-to-cost\nearned_margin_to_date  = earned_revenue - cost_to_date",
      "required_tables": {
        "jobs": [
          "job_id",
          "pm_id",
          "division",
          "original_contract",
          "original_budget",
          "status"
        ],
        "change_orders": [
          "job_id",
          "revenue_amount",
          "budget_amount",
          "status",
          "approved_at"
        ],
        "job_costs": [
          "job_id",
          "amount",
          "posted_at"
        ],
        "cost_forecasts": [
          "job_id",
          "period",
          "estimated_cost_to_complete"
        ]
      },
      "fields": [
        {
          "name": "Job",
          "meaning": "The project, with its PM and division"
        },
        {
          "name": "Original contract value",
          "meaning": "Contract amount at award"
        },
        {
          "name": "Original budget",
          "meaning": "Total budgeted cost at award"
        },
        {
          "name": "Approved change orders",
          "meaning": "Revenue and cost budget added by approved changes"
        },
        {
          "name": "Cost to date",
          "meaning": "All posted job cost"
        },
        {
          "name": "Estimated cost to complete",
          "meaning": "The PM's forecast of remaining cost, by period"
        }
      ],
      "definitional_choices": [
        "Projected or earned",
        "Pending change orders",
        "What counts as cost",
        "Stale forecasts",
        "Bid margin source"
      ],
      "related": [
        "job-cost-variance",
        "wip-over-under-billing",
        "backlog"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "construction.job_cost_variance",
      "name": "Job cost variance",
      "vertical": "construction",
      "url": "https://metrics.semaphor.cloud/construction/job-cost-variance/",
      "definition": "The difference between what a job was budgeted to cost and what it is now expected to cost.",
      "formula": "Job cost variance = revised budget − estimate at completion",
      "formula_detail": "revised_budget          = original_budget + approved_change_order_budget\nestimate_at_completion  = cost_to_date + estimated_cost_to_complete\njob_cost_variance ($)   = revised_budget - estimate_at_completion\njob_cost_variance (%)   = job_cost_variance / revised_budget * 100",
      "required_tables": {
        "jobs": [
          "job_id",
          "name",
          "pm_id",
          "division",
          "status",
          "contract_value"
        ],
        "job_budget": [
          "job_id",
          "cost_code",
          "cost_type",
          "original_budget"
        ],
        "change_orders": [
          "co_id",
          "job_id",
          "cost_code",
          "budget_amount",
          "revenue_amount",
          "status",
          "approved_at"
        ],
        "job_costs": [
          "job_id",
          "cost_code",
          "cost_type",
          "amount",
          "posted_at"
        ],
        "cost_forecasts": [
          "job_id",
          "cost_code",
          "period",
          "estimated_cost_to_complete"
        ]
      },
      "fields": [
        {
          "name": "Job",
          "meaning": "The project, with its PM and division"
        },
        {
          "name": "Cost code",
          "meaning": "A category of work in the budget"
        },
        {
          "name": "Original budget",
          "meaning": "Budget for the code when the job started"
        },
        {
          "name": "Approved change order budget",
          "meaning": "Budget added or removed by approved change orders"
        },
        {
          "name": "Cost to date",
          "meaning": "Posted cost from payroll, AP, and equipment"
        },
        {
          "name": "Estimated cost to complete",
          "meaning": "The PM's forecast of remaining cost, by period"
        },
        {
          "name": "Change order status",
          "meaning": "Pending, approved, or rejected"
        }
      ],
      "definitional_choices": [
        "Variance at completion vs cost-to-date variance",
        "Pending change orders",
        "Committed cost",
        "Stale forecasts"
      ],
      "related": [
        "wip-over-under-billing",
        "gross-margin-by-job",
        "labor-productivity-by-cost-code",
        "change-order-cycle-time"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "construction.wip_over_under_billing",
      "name": "WIP over/under billing",
      "vertical": "construction",
      "url": "https://metrics.semaphor.cloud/construction/wip-over-under-billing/",
      "definition": "The gap between what a contractor has billed on a job and the revenue it has actually earned.",
      "formula": "Over/under billing = billed to date − earned revenue",
      "formula_detail": "revised_contract_value  = original_contract + approved_change_orders (revenue side)\nestimated_total_cost    = cost_to_date + estimated_cost_to_complete\npercent_complete        = cost_to_date / estimated_total_cost\nearned_revenue          = percent_complete * revised_contract_value\nover_under_billing      = billed_to_date - earned_revenue",
      "required_tables": {
        "jobs": [
          "job_id",
          "pm_id",
          "division",
          "original_contract",
          "status"
        ],
        "change_orders": [
          "job_id",
          "revenue_amount",
          "budget_amount",
          "status",
          "approved_at"
        ],
        "job_costs": [
          "job_id",
          "amount",
          "posted_at"
        ],
        "cost_forecasts": [
          "job_id",
          "period",
          "estimated_cost_to_complete"
        ],
        "billings": [
          "job_id",
          "invoice_id",
          "amount",
          "retainage_amount",
          "invoice_date"
        ]
      },
      "fields": [
        {
          "name": "Job",
          "meaning": "The project, with its PM and division"
        },
        {
          "name": "Original contract value",
          "meaning": "Contract amount at award"
        },
        {
          "name": "Approved change order revenue",
          "meaning": "Contract value added by approved change orders"
        },
        {
          "name": "Cost to date",
          "meaning": "All posted job cost"
        },
        {
          "name": "Estimated cost to complete",
          "meaning": "The PM's forecast of remaining cost"
        },
        {
          "name": "Billed to date",
          "meaning": "Total progress billings, including retainage billed"
        },
        {
          "name": "Retainage billed",
          "meaning": "Share of billings held back by the owner"
        }
      ],
      "definitional_choices": [
        "Percent complete method",
        "Retainage",
        "Change orders",
        "Do not net the two sides",
        "Stale cost to complete"
      ],
      "related": [
        "job-cost-variance",
        "gross-margin-by-job",
        "backlog",
        "retainage-receivable"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "dental.case_acceptance_rate",
      "name": "Case acceptance rate",
      "vertical": "dental",
      "url": "https://metrics.semaphor.cloud/dental/case-acceptance-rate/",
      "definition": "The share of recommended treatment that patients agree to.",
      "formula": "Case acceptance rate = treatment accepted ($) ÷ treatment presented ($)",
      "formula_detail": "case_acceptance_rate ($)     = treatment_accepted_value / treatment_presented_value * 100\ncase_acceptance_rate (count) = treatment_plans_accepted / treatment_plans_presented * 100",
      "required_tables": {
        "treatment_plans": [
          "plan_id",
          "patient_id",
          "provider_id",
          "location_id",
          "presented_at",
          "presented_by",
          "status"
        ],
        "treatment_plan_items": [
          "plan_id",
          "procedure_code",
          "fee",
          "status"
        ],
        "appointments": [
          "appointment_id",
          "patient_id",
          "scheduled_at",
          "created_at",
          "linked_plan_id"
        ],
        "procedures": [
          "patient_id",
          "plan_id",
          "completed_at",
          "fee"
        ]
      },
      "fields": [
        {
          "name": "Treatment plan",
          "meaning": "A set of recommended procedures for one patient"
        },
        {
          "name": "Presented date",
          "meaning": "When the plan was shown to the patient"
        },
        {
          "name": "Presented by",
          "meaning": "Provider or treatment coordinator"
        },
        {
          "name": "Plan items and fees",
          "meaning": "Procedures on the plan and their fees"
        },
        {
          "name": "Plan status",
          "meaning": "Presented, accepted, declined, or completed"
        },
        {
          "name": "Linked appointment",
          "meaning": "The appointment booked for a plan item"
        },
        {
          "name": "Completed date",
          "meaning": "When the procedure was done"
        }
      ],
      "definitional_choices": [
        "What counts as accepted",
        "Window length",
        "Partial acceptance",
        "Who presented"
      ],
      "related": [
        "production-per-hour",
        "unscheduled-treatment",
        "hygiene-reappointment-rate",
        "collection-rate"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "dental.collection_rate",
      "name": "Collection rate (net collection rate)",
      "vertical": "dental",
      "url": "https://metrics.semaphor.cloud/dental/collection-rate/",
      "definition": "The share of what a practice is actually owed that it collects.",
      "formula": "Net collection rate = collections ÷ (gross production − contractual write-offs)",
      "formula_detail": "gross_production   = SUM(fee) for completed procedures in period\ncontractual_wo     = SUM(adjustment_amount) WHERE adjustment_type IN (:contractual_types)\nnet_production     = gross_production - contractual_wo\ncollections        = SUM(payments) - SUM(refunds) in period\nnet_collection     = collections / net_production\ngross_collection   = collections / gross_production",
      "required_tables": {
        "procedures": [
          "procedure_id",
          "location_id",
          "fee",
          "status",
          "completed_at"
        ],
        "adjustments": [
          "procedure_id",
          "location_id",
          "adjustment_type",
          "amount",
          "posted_at"
        ],
        "payments": [
          "location_id",
          "source",
          "amount",
          "received_at"
        ],
        "refunds": [
          "location_id",
          "amount",
          "refunded_at"
        ]
      },
      "fields": [
        {
          "name": "Procedure and fee",
          "meaning": "Completed procedures at the practice's full fee"
        },
        {
          "name": "Adjustment type",
          "meaning": "The kind of adjustment, such as contractual write-off or courtesy"
        },
        {
          "name": "Adjustment amount",
          "meaning": "The amount adjusted"
        },
        {
          "name": "Payment",
          "meaning": "A patient or insurance payment, with date and source"
        },
        {
          "name": "Refund",
          "meaning": "Money returned to a patient or payer"
        },
        {
          "name": "Location",
          "meaning": "The office"
        }
      ],
      "definitional_choices": [
        "Which adjustments are subtracted",
        "Period and lag",
        "Refunds",
        "Production basis",
        "Estimated vs actual write-offs"
      ],
      "related": [
        "production-per-hour",
        "case-acceptance-rate",
        "hygiene-reappointment-rate"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "dental.hygiene_reappointment_rate",
      "name": "Hygiene reappointment rate",
      "vertical": "dental",
      "url": "https://metrics.semaphor.cloud/dental/hygiene-reappointment-rate/",
      "definition": "The share of patients seen in hygiene who leave with their next hygiene visit already on the schedule.",
      "formula": "Hygiene reappointment rate = hygiene patients with a future hygiene appointment ÷ hygiene patients seen",
      "formula_detail": "seen        = DISTINCT patients with a completed hygiene visit in period\nbooked      = seen patients with a future hygiene appointment\n              where appointment.created_at <= checkout_time        -- rule A\n              (or created_at <= visit_date + :days)                -- rule B\nrate        = COUNT(booked) / COUNT(seen)",
      "required_tables": {
        "appointments": [
          "appt_id",
          "patient_id",
          "provider_id",
          "appt_type",
          "start_at",
          "created_at",
          "status"
        ],
        "procedures": [
          "patient_id",
          "provider_id",
          "cdt_code",
          "status",
          "completed_at"
        ],
        "patients": [
          "patient_id",
          "status",
          "location_id"
        ]
      },
      "fields": [
        {
          "name": "Patient",
          "meaning": "A unique patient ID"
        },
        {
          "name": "Hygiene visit",
          "meaning": "A completed visit of a hygiene type, with date and provider"
        },
        {
          "name": "Future appointment",
          "meaning": "Any later appointment, with its type and date"
        },
        {
          "name": "Appointment created at",
          "meaning": "When the future appointment was booked"
        },
        {
          "name": "Checkout time",
          "meaning": "When the patient left, if recorded"
        },
        {
          "name": "Patient status",
          "meaning": "Active, inactive, moved, or deceased"
        },
        {
          "name": "Location",
          "meaning": "The office"
        }
      ],
      "definitional_choices": [
        "When booking counts",
        "Patients or visits",
        "Which visit types count as hygiene",
        "Exclusions",
        "Cancelled later"
      ],
      "related": [
        "production-per-hour",
        "case-acceptance-rate",
        "collection-rate"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    },
    {
      "id": "dental.production_per_hour",
      "name": "Production per hour",
      "vertical": "dental",
      "url": "https://metrics.semaphor.cloud/dental/production-per-hour/",
      "definition": "The value of dentistry a provider produces for each hour they spend seeing patients.",
      "formula": "Production per hour = production ÷ clinical hours",
      "formula_detail": "production_per_hour[provider] = production[provider] / clinical_hours[provider]",
      "required_tables": {
        "procedures": [
          "procedure_id",
          "patient_id",
          "provider_id",
          "location_id",
          "cdt_code",
          "fee",
          "completed_at",
          "status"
        ],
        "adjustments": [
          "procedure_id",
          "type",
          "amount"
        ],
        "provider_schedule": [
          "provider_id",
          "location_id",
          "date",
          "start_time",
          "end_time",
          "block_type"
        ],
        "providers": [
          "provider_id",
          "name",
          "role"
        ],
        "locations": [
          "location_id",
          "name",
          "region"
        ]
      },
      "fields": [
        {
          "name": "Provider",
          "meaning": "Who did the work, and their role"
        },
        {
          "name": "Procedure code",
          "meaning": "The CDT code for the procedure"
        },
        {
          "name": "Fee",
          "meaning": "The practice's full fee for the procedure"
        },
        {
          "name": "Status",
          "meaning": "Completed, scheduled, or treatment planned"
        },
        {
          "name": "Contractual write-off",
          "meaning": "Fee minus what the insurance plan allows"
        },
        {
          "name": "Schedule block",
          "meaning": "Provider time, marked clinical, lunch, or admin"
        },
        {
          "name": "Location",
          "meaning": "The office, and its region for DSOs"
        }
      ],
      "definitional_choices": [
        "Gross or net",
        "Scheduled or worked hours",
        "Attribution",
        "Averaging daily rates",
        "Completed only"
      ],
      "related": [
        "case-acceptance-rate",
        "schedule-utilization",
        "collection-rate",
        "hygiene-reappointment-rate"
      ],
      "version": "1.0",
      "last_reviewed": "2026-10-20"
    }
  ]
}