calculate_mme.data.frame {mmequiv}R Documentation

Calculate morphine milligram equivalents (MME) with a data.frame or tibble

Description

Calculates the single-day MME and total MME for each individual prescription opioid medication submitted for calculation. Also calculates total MME, total days of supply, and four distinct Total MME/Day calculations from the NIH HEAL Online MME Calculator across all prescription medications for two different medication groupings: 1) opioids without buprenorphine and 2) opioids with buprenorphine.

Usage

## S3 method for class 'data.frame'
calculate_mme(
  x,
  id_col = "patient_id",
  medication_col = "medication_name",
  dose_col = "dose",
  doses_per_day_col = "doses_per_24_hours",
  days_col = "days_of_medication",
  therapy_days_col = "therapy_days",
  observation_days_col = "observation_window_days",
  therapy_days_without_col = NULL,
  observation_days_without_col = NULL,
  use_api = FALSE,
  ...
)

## S3 method for class 'tbl_df'
calculate_mme(
  x,
  id_col = "patient_id",
  medication_col = "medication_name",
  dose_col = "dose",
  doses_per_day_col = "doses_per_24_hours",
  days_col = "days_of_medication",
  therapy_days_col = "therapy_days",
  observation_days_col = "observation_window_days",
  therapy_days_without_col = NULL,
  observation_days_without_col = NULL,
  use_api = FALSE,
  ...
)

Arguments

x

(data.frame or tbl_df)
Object with input data - either a data.frame or tibble with data in long format, with one row per medication per patient or participant (id_col) and including all necessary data for MME calculations (see opioid_trial data) and/or other function arguments

id_col

(charcter)
Name of the column containing patient identifier; default is "patient_id"

medication_col

(charcter)
Name of the column containing medication names; default is "medication_name"

dose_col

(charcter)
Name of the column containing dose values; default is "dose"

doses_per_day_col

(charcter)
Name of the column containing doses per 24 hours; default is "doses_per_24_hours"

days_col

(charcter)
Name of the column containing days of medication; default is "days_of_medication"

therapy_days_col

(charcter)
Name of the column containing therapy days with buprenorphine (up to one unique value per patient); default is "therapy_days"

observation_days_col

(charcter)
Name of the column containing observation window days with buprenorphine (up to one unique value per patient); default is "observation_window_days"

therapy_days_without_col

(charcter)
Name of the column containing therapy days without buprenorphine (up to one unique value per patient). If NULL (default), uses the value from therapy_days_col.

observation_days_without_col

(charcter)
Name of the column containing observation window days without buprenorphine (up to one unique value per patient). If NULL (default), uses the value from observation_days_col.

use_api

(logical)
Indicates whether to use the NIH HEAL Online MME Calculator API to perform calculations or perform them locally instead. For calculate_mme.data.frame() and calculate_mme.tbl_df(), the default is FALSE, as the functions assume the user needs to perform the MME calculations without being restricted by the API rate limit of 50 patient-level calculations per 15 minutes. This also allows the user to perform the calculations without relying on internet access.

...

These dots are for future extensions and must be empty.

Details

The function will provide the same results regardless of whether the user has specified they want calculation done using the API (use_api). Specifying use_api == FALSE helps overcome the online calculator API rate limit of 50 (patient-level) requests per 15 minutes. In addition to returning user-specified arguments, calculate_mme() also returns several other variables mentioned in the Description section. Output variable description details are below; see Adams, et al. (2025) for a comprehensive overview.

Value

A list containing three data.frame elements:

Prescription-Level

Conversion Factor for <medication_name> (factor): the conversion factor used for calculating total MME/day.

MME for <medication_name> (mme): Morphine milligram equivalent for the whole prescription specified in medication_name, calculated as (dose) * (doses_per_24_hours) * (factor) * (days_of_medication).

24h MME for <medication_name> (single_day_mme): Morphine milligram equivalent for the prescription specified in medication_name for a single day, calculated as (dose) * (doses_per_24_hours) * (factor).

One day: Typically, the day with highest opioid exposure is entered, and the sum of 24-hour MME across the drugs that apply to this day is calculated. Highest MME in one day is definition 4.

Summary-Level:

On-therapy Days (therapy_days): The sum of prescription duration (days_of_medication) for each medication, but with each calendar day counted only ONCE. User-supplied; this is the denominator for MME/Day definition 2.

Total MME (total_mme): The MME for each medication, summed across all prescriptions. This is the numerator for MME/Day definitions 1, 2, and 3.

Total Days Supply (total_days): The sum of the entered prescription duration (days_of_medication) for each of the medications (Med 1 duration + med 2 duration...). Automatically calculated. This is the denominator for MME/Day definition 1.

MME/Day

MME/Day is an aggregate measure, calculating the total MME divided by a specified time window (a number of days). The MME/Day definitions specify the number of days:

MME/Day Definition 1 (mme1): Total Days Supply

MME Definition 1 = Total MME / Total Days Supply time window (sum of entered prescription durations).

mme1 = total_mme / total_days

MME/Day Definition 2 (mme2): On-therapy Days

MME Definition 2 = Total MME / On-therapy Days time window (sum of entered prescription durations except each calendar day is counted only ONCE).

mme2 = total_mme / therapy_days

MME/Day Definition 3 (mme3): Fixed Observation Window

Uses the Total MME study-specified fixed observation window. MME Definition 3 = Total MME / Number of days in observation window:

mme3 = total_mme / observation_window_days

MME/Day Definition 4 (mme4): Maximum Daily Dose

Uses the sum of 24-hour MME for the day with highest opioid exposure.

MME Definition 4 = Drug 1 (dose (mg) x # of doses per day) x conversion factor + Drug 2 (dose (mg) x # of doses per day) x conversion factor + ...

mme4 = sum(dose * doses_per_24_hours * factor)

See Also

calculate_mme.list()

Examples

library(dplyr)
# Calculate MME using long-format data
# Subset of opioid_trial data used for speedier example
mme <- calculate_mme(
  x = opioid_trial |> dplyr::filter(patient_id %in% sprintf("P%03d", 1:100)),
  therapy_days_without_col = "therapy_days_without",
  observation_days_without_col = "observation_window_days_without"
  )

head(mme$medications)

head(mme$patient_summary_with_buprenorphine)

head(mme$patient_summary_without_buprenorphine)

# Cleanup
rm(mme)


[Package mmequiv version 1.0.0 Index]