# realdentalcosts-data

**LaTeX macros for US dental price benchmarks by state, from the Real Dental
Costs Open Data API.**

`realdentalcosts-data` lets authors of reports, theses, and policy papers
cite a dental procedure price without retyping or manually looking it up.
The package ships a fixed snapshot of benchmark data (edition 2026.1) baked
in as LaTeX macros, so documents compile offline and reproducibly.

Covers four procedures — root canal, complete dentures (both arches),
single dental implant, and dental crown — with a self-pay price band (low /
average / high) for each of the 50 US states plus the District of Columbia,
alongside a national average. It also covers Medicaid paid-per-claim-line
amounts (2023-2024, latest published period) for two CDT codes: D3330
(molar root canal) and D5110 (complete upper denture).

## Data source

All figures are read programmatically from the Real Dental Costs Open Data
API and are not hand-typed:

- Procedure price data: <https://realdentalcosts.com/en/api/>
- Methodology and source notes: <https://realdentalcosts.com/en/methodology/>
- Root canal page: <https://realdentalcosts.com/en/root-canal/>
- Dentures page: <https://realdentalcosts.com/en/dentures/>
- Dental implants page: <https://realdentalcosts.com/en/dental-implants/>
- Medicaid dataset DOI (Harvard Dataverse): <https://doi.org/10.7910/DVN/7F2BZI>
  ("Medicaid dental paid per claim line by CDT code and state, 2018-2024",
  derived from HHS/CMS Medicaid Provider Spending by HCPCS, T-MSIS)

**This is independent pricing and market research. It is NOT medical,
dental, or insurance advice**, and Medicaid `paid_per_line_wavg` figures are
paid amounts per claim line, not allowed amounts, fee schedules, or
consumer prices.

## Installation

Drop `realdentalcosts-data.sty` next to your `.tex` file, or install it into
your local TeX tree (`texmf/tex/latex/realdentalcosts-data/`) and run
`texhash` / `mktexlsr`. Then:

```latex
\usepackage{realdentalcosts-data}
```

No external package dependencies — the code uses only core LaTeX2e kernel
primitives.

## Usage

### Example 1 — cite a single state price

```latex
The average self-pay cost of a root canal in Texas is
approximately \$\rdcPrice{root-canal}{TX}
(range \$\rdcPriceLow{root-canal}{TX}--\$\rdcPriceHigh{root-canal}{TX}),
against a US national average of \$\rdcNational{root-canal}.
```

### Example 2 — build a small comparison table

```latex
\begin{tabular}{lrrr}
\toprule
State & Low & Average & High \\
\midrule
California & \$\rdcPriceLow{dentures}{CA} & \$\rdcPrice{dentures}{CA} & \$\rdcPriceHigh{dentures}{CA} \\
Texas      & \$\rdcPriceLow{dentures}{TX} & \$\rdcPrice{dentures}{TX} & \$\rdcPriceHigh{dentures}{TX} \\
Florida    & \$\rdcPriceLow{dentures}{FL} & \$\rdcPrice{dentures}{FL} & \$\rdcPriceHigh{dentures}{FL} \\
\bottomrule
\end{tabular}
```

### Example 3 — cite a Medicaid paid amount and the data version

```latex
Medicaid programs paid an average of
\$\rdcMedicaidPaid{D3330}{CA} per claim line for a molar root canal
(CDT D3330) in California, 2023--2024 (\rdcDataVersion).
Data: \rdcSource.
```

## Macro reference

| Macro | Arguments | Returns |
|---|---|---|
| `\rdcPrice{slug}{ST}` | procedure slug, 2-letter state code | average self-pay price, USD, no `$` sign, thousands separated by a comma |
| `\rdcPriceLow{slug}{ST}` | same | low end of the price band |
| `\rdcPriceHigh{slug}{ST}` | same | high end of the price band |
| `\rdcNational{slug}` | procedure slug | US national average self-pay price |
| `\rdcMedicaidPaid{CDT}{ST}` | CDT code, 2-letter state code | latest Medicaid paid amount per claim line, USD, two decimals |
| `\rdcDataVersion` | — | dataset edition and generation date |
| `\rdcSource` | — | citation string for the underlying data |

**Procedure slugs**: `root-canal`, `dentures`, `dental-implant`, `dental-crown`.

**State codes**: standard 2-letter USPS codes, plus `DC` for the District of
Columbia (51 jurisdictions total).

**Medicaid CDT codes covered in this edition**: `D3330` (molar root canal,
48 states published), `D5110` (complete upper denture, 41 states published —
some states are suppressed by HHS because a cell had fewer than 12 claim
lines or 12 patients).

An unknown procedure slug, state code, or CDT code raises a
`\PackageWarning` and prints `n/a` rather than failing the build or
fabricating a number.

## Provenance and methodology notes

- **Root canal**: no per-state source exists; state figures are the
  national range scaled by a state Restorative Cost Index (modelled,
  confidence 59/100).
- **Dentures, dental crown**: state averages are measured
  (ASQ360°/CareCredit Average Procedural Cost Study 2023-2024); the
  low/high band around each average is modelled from published national
  ratios (confidence 65/100).
- **Dental implant**: state averages are Real Dental Costs' own observed
  cash-price series across 51 state markets (DOI
  10.5281/zenodo.20531728), validated against ASQ360° at Spearman 0.945
  (confidence 72/100).
- **Medicaid `\rdcMedicaidPaid`**: derived from HHS/CMS Medicaid Provider
  Spending by HCPCS (T-MSIS), version 2026-02-09, geolocated via NPPES
  (99.4% of dental lines matched to a state). Several states carry a
  `nominal_amounts_suspected` quality flag in the source dataset because
  managed-care encounters can report artificially low paid amounts; see
  the methodology page for the full per-state quality table. This is a
  **paid** amount per claim line, not an allowed amount, fee schedule, or
  patient cost.

## Limitations

This package is **pricing and market research, not medical, dental, or
insurance advice**. Do not use it to make individual treatment or coverage
decisions. Prices vary by provider, insurance status, treatment complexity,
and negotiated rates; the figures here are state-level averages and bands,
not quotes. The package ships a fixed snapshot (edition 2026.1); it will
not reflect price changes after that date until a new edition is released.

## License

- **Code** (`realdentalcosts-data.sty`, this documentation source): LaTeX
  Project Public License, version 1.3c (LPPL 1.3c).
  <https://www.latex-project.org/lppl.txt>
- **Underlying data** (the numeric values embedded in the macros): Creative
  Commons Attribution 4.0 International (CC BY 4.0).
  <https://creativecommons.org/licenses/by/4.0/>
  Attribution: "Real Dental Costs — https://realdentalcosts.com". CDT
  procedure descriptors are copyright American Dental Association and are
  not reproduced verbatim in this package; all procedure labels are Real
  Dental Costs' own wording.

## Version

v1.0, 2026-08-26. Data edition 2026.1 (source data generated 2026-08-25).

## Maintainer

Real Dental Costs Data and Research Team
<research@realdentalcosts.com>
<https://realdentalcosts.com/en/methodology/>