Core concepts

Assisted living is state-regulated. There is no single federal citation ontology like CMS F-tags for SNFs. This board exists because davvvNET loads and normalizes state sources into one operator-ready spine — then puts Survey Risk product logic on top, with honest blanks where the data cannot support a rate.

Facility (state roster)

A licensed assisted living / residential care community on the state facility list. Joined to findings when we can resolve a facility key (license / name rules vary by state). Roster counts use DimFacility; citation volumes may include rows that have not yet joined a facility key.

Finding

One row in the fact table from a state source: a citation, deficiency, survey event, report link, or related inspection artifact. Not every finding is a “citation” for rate math — see citation grain below.

Citation grain (IsCitationGrain)

Operator-facing “real citation / deficiency” rows: finding types that contain citation, plus selected deficiency-style types (survey_deficiency, state_licensure_deficiency, sod_tag, deficiency). Report links and pure event rows stay in Findings but are excluded from Citations.

State tag code (StateTagCode)

The regulator’s own tag / rule / deficiency code as published by that state (e.g. Oregon C0150, Florida class codes, California statute-style codes). This is the native language administrators already use in survey packets — not a made-up national renumbering.

Tag key

Stable join key for the unified tags database: State | StateTagCode | FindingType. Powers distinct-tag counts, repeat-tag logic, and the Tags page detail.

Inspection key

Proxy for a survey visit: facility key + survey date (when dated). Used for inspections, yield (citations per inspection), and cascade-style measures — states rarely publish a clean SurveyId.

Coverage level

Per-state data readiness chip: Full citation data, Partial citation data, Public records pending, Links only, or Multiple states. Drives whether rates and risk scores are allowed to calculate.

Not CMS

This is not a CMS extract, not Five-Star, and not SNF F-tag parity. Same product shape as Survey Risk for SNFs — different data reality for ALF.

Unified national tags database

This is the differentiator. No state publishes a single national ALF tag list. davvvNET maintains a unified national database of state tag codes — every parsed code from every loaded state lives in one place (DimTag + FactFinding[StateTagCode] / TagKey) so multi-state operators can search, count, rank, and trend tags without 50 portals and 50 spreadsheets.

What “unified” means here:

• One schema, all states — State, native code, finding type, source system, load stamp.
• Native codes preserved — we do not invent a fake national F-tag map or rename Oregon codes into Florida’s system.
• National search & roll-up — filter to one state for a survey packet language; keep All for portfolio heat; still one model.
• ~23K+ tag dimension rows (and growing as states load) powering the Tags page, top-code charts, and repeat-tag risk components.

DimTag row:     State + StateTagCode + FindingType + SourceSystem
TagKey (fact):  State | StateTagCode | FindingType
Distinct Tags:  DISTINCTCOUNT ( FactFinding[TagKey] ) where TagKey is not blank
State codes:    DISTINCTCOUNT ( FactFinding[StateTagCode] ) where code is not blank

Operator tip: Use the Tags page with one state selected when preparing for survey or reviewing a building — you will see that state’s real codes (the ones on the SOD / report). Use All / multi-state only for portfolio heat and coverage, not to pretend two states share one code list.

Coverage honesty & the gate

Multi-state ALF data is uneven. The board never paints empty or partial states as “clean.” Volume counts can still show (facilities, findings, citations). Rates and risk scores stay blank until every selected state is coverage-safe.

Selected states = VALUES ( DimFacility[State] )
Safe = states with ReportCoverageLevel in { A_bulk_findings, B_partial_findings }
       AND FindingRowCount > 0
Gate = 1 only when every selected state is Safe
Else Gate = 0  →  gated measures return BLANK() (never fake 0%)

Rolling 12-month (R12) window

Most heat KPIs use a rolling 12 months ending at a governed As Of Date. As Of is capped at today so corrupt future survey dates cannot pull the window forward.

AsOf   = MIN ( TODAY(), MAX ( SurveyDate ) with SurveyDate ≤ TODAY()+30 )
StartD = AsOf − 365 days
Include rows where SurveyDate > StartD and SurveyDate ≤ AsOf
If SurveyDate is blank → row is excluded from R12 (all-time volume measures still count it)

Example: A state with full citation rows but 100% null survey dates will show all-time Findings / Citations, while Findings R12 and Citations R12 stay blank or zero — the banner says so instead of inventing a fake rolling year.

Volume & footprint

Volume measures are not coverage-gated. They always count what is in the model for the current filter so operators can see scale even when rates must stay blank.

Severity (state-native, soft-mapped)

States do not share a CMS scope/severity A–L grid. The model stores the state’s native severity text and applies a soft weight (1–4) only when the text matches known patterns (e.g. L1–L4, class language). Unmapped severity stays blank — we do not invent “100% mapped.”

Do not treat soft weights as a national CMS S/S grid. Peer percentiles and within-state comparisons are the safe operator read; absolute weight sums across FOIA/partial mixes are not.

Survey mix, complaint & yield

Open-like findings & aging

“Open-like” is an operator worklist definition from source flags (OpenLike) — not a universal state field named Open. Use it for follow-up queues, not as a legal “still open with the agency” guarantee in every jurisdiction.

Rates (coverage-gated)

Every measure in this section returns BLANK when Coverage Gate Pass ≠ 1. That is intentional: blank means “do not rank on this yet,” not “zero risk.”

Survey Risk Score & peers

Survey Risk Score is a peer-relative 0–100 prioritization score for facilities (or thin peers blank out). It is not a CMS star rating and not a fine schedule.

Peers = same PeerKey (state + license type + bed band)
Components (percentile within peers):
  Volume   ← Citations R12
  Severity ← Severity Weight Sum R12
  Recency  ← Decayed Severity Exposure
  Repeat   ← Repeat Tag Events R12   ← uses unified tags
  Complaint← Complaint Findings R12
Default weights: Vol 0.20 · Sev 0.20 · Rec 0.20 · Repeat 0.25 · Complaint 0.15
  (ParamScoreWeight can override)
Score = weighted average of available component percentiles
BLANK if coverage gate fails OR peer group too thin (< 10)

Worklist & operator flags

State-grain scoreboard measures

The Risk Overview state scoreboard attributes R12 volumes by finding State (not only facility-key join). That keeps orphan findings (state known, facility key not resolved) visible on the state row. Implementation uses TREATAS on FactFinding[State] plus REMOVEFILTERS ( DimFacility ) so the facility relationship does not hide orphans.

Facilities page matrices stay facility-linked on purpose — operator scorecards should not invent a building match. Titles call out facility-linked volume so the grain is honest next to state-grain scoreboard numbers.

Where measures appear by page