% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/relative_mortality.R
\name{rmm}
\alias{rmm}
\title{Relative Mortality Metric (RMM) Calculation}
\usage{
rmm(
  data,
  Ps_col,
  outcome_col,
  group_vars = NULL,
  n_samples = 100,
  Divisor1 = 5,
  Divisor2 = 5,
  Threshold_1 = 0.9,
  Threshold_2 = 0.99,
  bootstrap_ci = TRUE,
  pivot = FALSE,
  seed = NULL
)
}
\arguments{
\item{data}{A data frame or tibble containing the data.}

\item{Ps_col}{The name of the column containing the survival probabilities
(Ps). Should be numeric on a scale from 0 to 1.}

\item{outcome_col}{The name of the column containing the outcome data. It
should be binary, with values indicating patient survival. A value of \code{1}
should represent "alive" (survived), while \code{0} should represent "dead" (did
not survive).  \code{TRUE/FALSE} are accepted as well. Ensure the column
contains only these possible values.}

\item{group_vars}{Optional character vector specifying grouping variables for
stratified analysis. If \code{NULL}, the calculation is performed on the entire
dataset.}

\item{n_samples}{A numeric value indicating the number of bootstrap samples
to take from the data source.}

\item{Divisor1}{A positive numeric value controlling the coarseness of bins
for Ps values below \code{Threshold_1}. It scales the number of steps from the
start of the dataset up to the \code{Threshold_1} cut point. Larger values
produce fewer, broader bins; smaller values produce more, narrower bins.
Defaults to \code{5}.}

\item{Divisor2}{A positive numeric value controlling the coarseness of bins
for Ps values between \code{Threshold_1} and \code{Threshold_2}. Larger values yield
wider bins, and smaller values yield narrower bins in this range. Defaults
to \code{5}.}

\item{Threshold_1}{A numeric value that defines the lower bound of the
high-survival probability range in \code{Ps_col}. The function identifies the
first index where \code{Ps_col} exceeds this value and begins applying smaller
bin widths from that point onward. Defaults to \code{0.9}, meaning binning
changes once Ps > 0.90.}

\item{Threshold_2}{A numeric value that defines the upper bound of the
high-survival probability range in \code{Ps_col}. The function identifies the
first index where \code{Ps_col} exceeds this value. Between \code{Threshold_1} and
\code{Threshold_2}, finer binning is applied; above \code{Threshold_2}, binning may
again change. Defaults to \code{0.99}, meaning the special binning range is
between Ps values of 0.90 and 0.99.}

\item{bootstrap_ci}{A logical indicating whether to return the relative
mortality metric estimate and 95\% confidence intervals using bootstrap
sampling. Default is \code{TRUE}.}

\item{pivot}{A logical indicating whether to return the results in a long
format (\code{pivot = TRUE}) or wide format (\code{pivot = FALSE}, default). Use with
caution in tandem with \code{group_vars} if the grouping variable is of a
different class than \code{rmm()}'s outputs, such as \code{factor} or \code{character}
grouping variables.}

\item{seed}{Optional numeric value to set a random seed for reproducibility.
If \code{NULL} (default), no seed is set.}
}
\value{
A tibble containing the Relative Mortality Metric (RMM) and related
statistics:
\itemize{
\item \code{population_RMM_LL}: The lower bound of the 95\% confidence interval for
the population RMM.
\item \code{population_RMM}: The final calculated Relative Mortality Metric for the
population existing in \code{data}.
\item \code{population_RMM_UL}: The upper bound of the 95\% confidence interval for
the population RMM.
\item \code{population_CI}: The confidence interval width for the population RMM.
\item \code{bootstrap_RMM_LL}: The lower bound of the 95\% confidence interval for
the bootstrap RMM. (optional, if \code{bootstrap_ci = TRUE})
\item \code{bootstrap_RMM}: The average RMM value calculated for the bootstrap
sample. (optional, if \code{bootstrap_ci = TRUE})
\item \code{bootstrap_RMM_UL}: The upper bound of the 95\% confidence interval for
the bootstrap RMM. (optional, if \code{bootstrap_ci = TRUE})
\item \code{bootstrap_CI}: The width of the 95\% confidence interval for the
bootstrap RMM. (optional, if \code{bootstrap_ci = TRUE})
\item If \code{pivot = TRUE}, the results will be in long format with two columns:
\code{stat} and \code{value}, where each row corresponds to one of the calculated
statistics.
\item If \code{pivot = FALSE} (default), the results will be returned in wide
format, with each statistic as a separate column.
}
}
\description{
Calculates the Relative Mortality Metric (RMM) from Napoli et al. (2017)
based on patient survival probabilities (Ps) and actual outcomes. The
function groups patients into bins based on their survival probability scores
(Ps) and computes a weighted mortality metric along with confidence
intervals. For more information on the methods used in this function, see as
well Schroeder et al. (2019), and Kassar et al. (2016).

The Relative Mortality Metric (RMM) quantifies the performance of a center in
comparison to the anticipated mortality based on the TRISS national
benchmark. The RMM measures the difference between observed and expected
mortality, with a range from -1 to 1.
\itemize{
\item An RMM of 0 indicates that the observed mortality aligns with the expected
national benchmark across all acuity levels.
\item An RMM greater than 0 indicates better-than-expected performance, where
the center is outperforming the national benchmark.
\item An RMM less than 0 indicates under-performance, where the center’s observed
mortality is higher than the expected benchmark.
}

This metric helps assess how a center's mortality compares to the national
standards, guiding quality improvement efforts. \code{rmm()} utilizes bootstrap
sampling to calculate the confidence intervals via the standard error method.
}
\details{
Like other statistical computing functions, \code{rmm()} is happiest without
missing data.  It is best to pass complete probability of survival and
mortality outcome data to the function for optimal performance. With smaller
datasets, this is especially helpful.  However, \code{rmm()} will throw a warning
about missing values, if any exist in \code{Ps_col} and/or \code{outcome_col}.

\code{rmm()} assumes \code{Ps_col} contains probabilities derived from
real-world inputs for the Trauma Injury Severity Score (TRISS) model.
Synthetic or low-variability data (especially with small sample sizes) may
not reflect the distribution of TRISS-derived survival probabilities. This
can result in unstable estimates or function failure due to insufficient
dispersion. With small sample sizes, it may be important to use smaller
values with the divisor arguments and adjust the thresholds (based on the
distribution of the \code{Ps_col} values) to create bins that better accommodate
the data.

Due to the use of bootstrap sampling within the function, users should
consider setting the random number \code{seed} within \code{rmm()} for reproducibility.
}
\note{
This function will produce the most reliable and interpretable results when
using a dataset that has one row per patient, with each column being a
feature.

By default, \code{rmm()} derives bin cut points from the full dataset’s
distribution. This ensures comparability across groups when \code{group_vars} is
used. To tailor results to a specific group (e.g., a single hospital), filter
the dataset to that subgroup before calling \code{rmm()}. The function will then
compute bins and related statistics using only that subset’s \code{Ps_col}
distribution. When \code{group_vars} is used, and ff a group lacks
observations within one or more bins, \code{rm_bin_summary()} will compute
statistics only for the bins that contain data. Bins with no observations are
excluded from the summary for that group.
}
\examples{
# Generate example data
set.seed(123)

# Parameters
# Total number of patients
n_patients <- 5000

# Arbitrary group labels
groups <- sample(x = LETTERS[1:2], size = n_patients, replace = TRUE)

# Trauma types
trauma_type_values <- sample(
  x = c("Blunt", "Penetrating"),
  size = n_patients,
  replace = TRUE
)

# RTS values
rts_values <- sample(
  x = seq(from = 0, to = 7.8408, by = 0.005),
  size = n_patients,
  replace = TRUE
)

# patient ages
ages <- sample(
  x = seq(from = 0, to = 100, by = 1),
  size = n_patients,
  replace = TRUE
)

# ISS scores
iss_scores <- sample(
  x = seq(from = 0, to = 75, by = 1),
  size = n_patients,
  replace = TRUE
)

# Generate survival probabilities (Ps)
Ps <- traumar::probability_of_survival(
  trauma_type = trauma_type_values,
  age = ages,
  rts = rts_values,
  iss = iss_scores
)

# Simulate survival outcomes based on Ps
survival_outcomes <- rbinom(n_patients, size = 1, prob = Ps)

# Create data frame
data <- data.frame(Ps = Ps, survival = survival_outcomes, groups = groups) |>
  dplyr::mutate(death = dplyr::if_else(survival == 1, 0, 1))

# Example usage of the `rmm` function
rmm(data = data, Ps_col = Ps,
    outcome_col = survival,
    Divisor1 = 4,
    Divisor2 = 4,
    n_samples = 10
    )

# pivot!
rmm(data = data, Ps_col = Ps,
    outcome_col = survival,
    Divisor1 = 4,
    Divisor2 = 4,
    n_samples = 10,
    pivot = TRUE
    )

# Create example grouping variable (e.g., hospital)
hospital <- sample(c("Hospital A", "Hospital B"), n_patients, replace = TRUE)

# Create data frame
data <- data.frame(
  Ps = Ps,
  survival = survival_outcomes,
  hospital = hospital
) |>
  dplyr::mutate(death = dplyr::if_else(survival == 1, 0, 1))

# Example usage of the `rmm` function with grouping by hospital
rmm(
  data = data,
  Ps_col = Ps,
  outcome_col = survival,
  group_vars = "hospital",
  Divisor1 = 4,
  Divisor2 = 4,
  n_samples = 10
)

# Pivoted output for easier visualization
rmm(
  data = data,
  Ps_col = Ps,
  outcome_col = survival,
  group_vars = "hospital",
  Divisor1 = 4,
  Divisor2 = 4,
  n_samples = 10,
  pivot = TRUE
)

}
\references{
Kassar, O.M., Eklund, E.A., Barnhardt, W.F., Napoli, N.J., Barnes, L.E.,
Young, J.S. (2016). Trauma survival margin analysis: A dissection of trauma
center performance through initial lactate. The American Surgeon, 82(7),
649-653. \url{doi:10.1177/000313481608200733}

Napoli, N. J., Barnhardt, W., Kotoriy, M. E., Young, J. S., & Barnes, L. E.
(2017). Relative mortality analysis: A new tool to evaluate clinical
performance in trauma centers. IISE Transactions on Healthcare Systems
Engineering, 7(3), 181–191. \url{doi:10.1080/24725579.2017.1325948}

Schroeder, P. H., Napoli, N. J., Barnhardt, W. F., Barnes, L. E., & Young, J.
S. (2018). Relative mortality analysis of the “golden hour”: A comprehensive
acuity stratification approach to address disagreement in current literature.
Prehospital Emergency Care, 23(2), 254–262.
\url{doi:10.1080/10903127.2018.1489021}
}
\seealso{
\code{\link[=probability_of_survival]{probability_of_survival()}}, \code{\link[=rm_bin_summary]{rm_bin_summary()}}, and
\code{\link[=nonlinear_bins]{nonlinear_bins()}}
}
\author{
Nicolas Foss, Ed.D, MS, original implementation in MATLAB by Nicholas
J. Napoli, Ph.D., MS
}
