\documentclass[11pt]{article}
\usepackage[margin=2.5cm]{geometry}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{realdentalcosts-data}

\title{The \texttt{realdentalcosts-data} package\\
\large US dental price benchmarks by state, as LaTeX macros}
\author{Real Dental Costs Data and Research Team\\
\texttt{research@realdentalcosts.com}}
\date{v1.0 --- 2026-08-26 (data edition \rdcDataVersion)}

\begin{document}
\maketitle

\begin{abstract}
\noindent
\texttt{realdentalcosts-data} provides LaTeX macros that return US dental
procedure price benchmarks by state, drawn from the Real Dental Costs Open
Data API. Authors of reports, theses, and policy documents can cite a
state-level price without retyping a number from a spreadsheet or a web
page. The package covers four procedures --- root canal, complete
dentures, single dental implant, and dental crown --- for all 50 states
plus the District of Columbia, and Medicaid paid-per-claim-line amounts
for two CDT codes. This document explains installation, the macro
reference, provenance of the underlying data, and its limitations.
\end{abstract}

\tableofcontents

\section{Introduction}

Dental care cost is one of the most frequently cited --- and most
frequently mis-cited --- statistics in US health policy writing. A single
national average conceals large state-to-state variation, and manually
transcribing a state figure from a table into a manuscript is both
error-prone and hard to keep in sync when the source data is refreshed.

\texttt{realdentalcosts-data} solves this by embedding a versioned
snapshot of the Real Dental Costs Open Data API as LaTeX macros. Instead
of writing a dollar figure by hand, an author writes
\verb|\rdcPrice{root-canal}{TX}| and the package returns the correct,
attributable number for the state and procedure requested, with a
warning (rather than a wrong number) if the combination does not exist in
this edition.

The package is a \emph{data} package: it ships no visual formatting,
tables, or graphics of its own. It only defines macros that expand to
plain numbers (and two short citation strings), so it composes cleanly
with any table, sentence, or figure caption an author already has.

\section{Installation}

Place \texttt{realdentalcosts-data.sty} in the same directory as your
\texttt{.tex} file, or install it into your local TeX tree under
\texttt{texmf/tex/latex/realdentalcosts-data/} and refresh the filename
database (\texttt{texhash} or \texttt{mktexlsr}). Then load it in the
preamble:

\begin{verbatim}
\usepackage{realdentalcosts-data}
\end{verbatim}

The package has no dependencies beyond core LaTeX2e: it uses only
\verb|\csname|, \verb|\expandafter|, and \verb|\newcommand| from the
kernel. It works under pdfLaTeX, XeLaTeX, and LuaLaTeX.

\section{Macro reference}

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
Macro & Arguments & Returns \\
\midrule
\verb|\rdcPrice| & \{slug\}\{ST\} & average self-pay price, USD \\
\verb|\rdcPriceLow| & \{slug\}\{ST\} & low end of the price band \\
\verb|\rdcPriceHigh| & \{slug\}\{ST\} & high end of the price band \\
\verb|\rdcNational| & \{slug\} & US national average self-pay price \\
\verb|\rdcMedicaidPaid| & \{CDT\}\{ST\} & latest Medicaid paid amount per claim line \\
\verb|\rdcDataVersion| & --- & dataset edition and generation date \\
\verb|\rdcSource| & --- & citation string for the underlying data \\
\bottomrule
\end{tabular}
\end{center}

All price macros return a plain number, thousands-separated with a comma,
with no currency sign, so that an author can choose their own typesetting
(e.g.\ prefixing \verb|\$|, or feeding the number to \texttt{siunitx}).
\verb|\rdcMedicaidPaid| returns a decimal amount with two digits after the
point.

\textbf{Procedure slugs} recognised in this edition: \texttt{root-canal},
\texttt{dentures}, \texttt{dental-implant}, \texttt{dental-crown}.

\textbf{State codes}: the standard 2-letter USPS abbreviation, plus
\texttt{DC} for the District of Columbia --- 51 jurisdictions in total for
every procedure.

\textbf{Medicaid CDT codes} covered in this edition: \texttt{D3330} (molar
root canal, published for 48 states) and \texttt{D5110} (complete upper
denture, published for 41 states --- HHS suppresses a state/code cell
when it has fewer than 12 claim lines or 12 patients, so not every state
publishes every code).

If a macro is called with a slug, state, or CDT code that does not exist
in this edition, it issues a \verb|\PackageWarning| at compile time and
typesets the literal text \texttt{n/a} rather than silently failing the
build or fabricating a plausible-looking number.

\subsection{Usage examples}

\paragraph{Citing a single state price in running text.}
\begin{verbatim}
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}.
\end{verbatim}
Renders as: \emph{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}.}

\paragraph{Building a comparison table.}
\begin{verbatim}
\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} \\
\bottomrule
\end{tabular}
\end{verbatim}

\paragraph{Citing a Medicaid paid amount with the data version.}
\begin{verbatim}
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.
\end{verbatim}
Renders as: \emph{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.}

\section{Worked example: root canal by state}

Table~\ref{tab:rootcanal} shows ten states, generated entirely from
package macros --- no number below was typed by hand into this document.

\begin{table}[h]
\centering
\caption{Self-pay root canal price by state (USD)}
\label{tab:rootcanal}
\begin{tabular}{@{}lrrr@{}}
\toprule
State & Low & Average & High \\
\midrule
Alabama      & \$\rdcPriceLow{root-canal}{AL} & \$\rdcPrice{root-canal}{AL} & \$\rdcPriceHigh{root-canal}{AL} \\
Georgia      & \$\rdcPriceLow{root-canal}{GA} & \$\rdcPrice{root-canal}{GA} & \$\rdcPriceHigh{root-canal}{GA} \\
Ohio         & \$\rdcPriceLow{root-canal}{OH} & \$\rdcPrice{root-canal}{OH} & \$\rdcPriceHigh{root-canal}{OH} \\
North Carolina & \$\rdcPriceLow{root-canal}{NC} & \$\rdcPrice{root-canal}{NC} & \$\rdcPriceHigh{root-canal}{NC} \\
Michigan     & \$\rdcPriceLow{root-canal}{MI} & \$\rdcPrice{root-canal}{MI} & \$\rdcPriceHigh{root-canal}{MI} \\
Texas        & \$\rdcPriceLow{root-canal}{TX} & \$\rdcPrice{root-canal}{TX} & \$\rdcPriceHigh{root-canal}{TX} \\
Florida      & \$\rdcPriceLow{root-canal}{FL} & \$\rdcPrice{root-canal}{FL} & \$\rdcPriceHigh{root-canal}{FL} \\
Pennsylvania & \$\rdcPriceLow{root-canal}{PA} & \$\rdcPrice{root-canal}{PA} & \$\rdcPriceHigh{root-canal}{PA} \\
New York     & \$\rdcPriceLow{root-canal}{NY} & \$\rdcPrice{root-canal}{NY} & \$\rdcPriceHigh{root-canal}{NY} \\
California   & \$\rdcPriceLow{root-canal}{CA} & \$\rdcPrice{root-canal}{CA} & \$\rdcPriceHigh{root-canal}{CA} \\
\midrule
US national  & --- & \$\rdcNational{root-canal} & --- \\
\bottomrule
\end{tabular}
\end{table}

\section{Data provenance}

Each procedure and each Medicaid code carries its own provenance and
confidence score in the source API; a summary follows.

\begin{itemize}
\item \textbf{Root canal.} No per-state source exists for this
  procedure. State figures are the national self-pay range scaled by a
  state Restorative Cost Index (a modelled estimate, confidence 59/100
  in the source dataset). Treat root canal state figures as directional,
  not measured.
\item \textbf{Dentures, dental crown.} The state \emph{average} is a
  measured price from the ASQ360\textdegree/CareCredit Average
  Procedural Cost Study 2023--2024 (confidence 65/100). The
  low/high band around that average is modelled from published national
  ratios, not an observed percentile.
\item \textbf{Dental implant.} The state average is Real Dental Costs'
  own observed cash-price series across 51 state markets (DOI
  \texttt{10.5281/zenodo.20531728}), validated against ASQ360\textdegree{}
  at Spearman correlation 0.945 (confidence 72/100).
\item \textbf{Medicaid paid amounts (\texttt{\textbackslash
  rdcMedicaidPaid}).} Derived from HHS/CMS Medicaid Provider Spending by
  HCPCS (T-MSIS), version 2026-02-09, geolocated to a state via provider
  NPI joined against the NPPES registry (99.4\% of dental claim lines
  matched). Underlying dataset DOI:
  \texttt{10.7910/DVN/7F2BZI} (Harvard Dataverse). This is a
  \emph{paid} amount per claim line (sum of paid divided by sum of
  claim lines), not an allowed amount, a fee schedule, or a patient
  cost. Several states carry a \texttt{nominal\_amounts\_suspected}
  quality flag in the source dataset, because managed-care encounters
  can report artificially low or zero paid amounts; consult the
  methodology page before citing a flagged state as representative.
\end{itemize}

\section{Limitations}

This package is \textbf{pricing and market research, not medical,
dental, or insurance advice}. It should not be used to make individual
treatment or coverage decisions. The figures are state-level averages
and modelled bands, not itemised quotes; actual prices vary by provider,
insurance status, treatment complexity, and negotiated rates.

The package ships a \textbf{fixed snapshot} (data edition
\rdcDataVersion). It will not reflect price changes after that date
until a new package edition is released; check
\url{https://realdentalcosts.com/en/api/} for the current live data.

CDT procedure code descriptors are copyright American Dental
Association and are not reproduced verbatim anywhere in this package;
all procedure labels used here are Real Dental Costs' own wording.

\section{License}

The package code (\texttt{realdentalcosts-data.sty} and this
documentation source) is released under the LaTeX Project Public
License, version 1.3c (LPPL 1.3c),
\url{https://www.latex-project.org/lppl.txt}.

The underlying numeric data embedded in the macros is released under
Creative Commons Attribution 4.0 International (CC~BY~4.0),
\url{https://creativecommons.org/licenses/by/4.0/}. When reproducing
these figures outside of this package, attribute them as: ``Real Dental
Costs --- \url{https://realdentalcosts.com}''.

\section{Maintainer}

Real Dental Costs Data and Research Team\\
\texttt{research@realdentalcosts.com}\\
\url{https://realdentalcosts.com/en/methodology/}

\end{document}