get_star_decomposition

How a contract's star is built, and what moves it to the next line. For one Medicare Advantage contract and rating year: for the Overall, Part C and Part D summaries, the raw score (the weighted mean of the measure stars), the categorical adjustment (CAI), the reward factor, the score before rounding, the published star and the recomputed one, the cushion above the line the star was earned at and the gap to the next half-star line (and to 3.75, which rounds to 4.0). Then every measure: score, star, weight, direction, the next star's cut point and the distance to it in the measure's own units, and what one more star on it adds to each summary's raw score; plus the shortest list of one-star gains that closes the gap to the next line.

ARGUMENTS: contract_id (required, e.g. H5216), rating_year (default the newest held for the contract), limit (measure rows, default 60).

RETURNS value.summary (contract, rating_year, pays_in, parts: one block per summary with its decomposition, gaps and path) and value.measures (one row per measure).

RULES THE TOOL ENFORCES: the arithmetic is CMS's (the raw score over the measure set CMS used, picked so the weights add up to the recompute engine's total; the Overall leaves out the two Part D measures that duplicate Part C); one more star adds weight / total weight to the raw score; the path holds the CAI and the reward factor constant and says so; distances are in the measure's own units and direction (for a lower-is-better measure the score must fall); survey (CAHPS) cut points are approximate, because CMS also tests significance and reliability; improvement measures have no cut point. The recomputed star is the engine's, the published star is CMS's; where they differ the row says why.

FLOOR BANDS: where CMS printed NA for a measure's lowest star bands (some measures in RY2015 and RY2018-2021), every score earns at least that star; the measure's floor_cut says so and it cannot be lost.

SOURCE: CMS Part C and D Star Ratings Data Tables and Technical Notes, through Vlada's recompute engine, which reproduces 98.4% of every star CMS published (RY2015-2027) exactly.