Type:	Package
Title:	Analyze Data from Electronic Adherence Monitoring Devices
Version:	0.1.7
Description:	Medication adherence, defined as medication-taking behavior that aligns with the agreed-upon treatment protocol, is critical for realizing the benefits of prescription medications. Medication adherence can be assessed using electronic adherence monitoring devices (EAMDs), pill bottles or boxes that contain a computer chip that records the date and time of each opening (or “actuation”). Before researchers can use EAMD data, they must apply a series of decision rules to transform actuation data into adherence data. The purpose of this R package ('oncmap') is to transform EAMD actuations in the form of a raw .csv file, information about the patient, regimen, and non-monitored periods into two daily adherence values – Dose Taken and Correct Dose Taken.
Encoding:	UTF-8
LazyData:	true
Imports:	readr, methods, readxl, dplyr, hms, lubridate, zoo
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
RoxygenNote:	7.3.1
Depends:	R (≥ 3.60)
VignetteBuilder:	knitr
License:	MIT + file LICENSE
NeedsCompilation:	no
Packaged:	2025-04-09 16:34:09 UTC; michal
Author:	Michal Kouril [aut, cre], Meghan McGrady [aut], Mara Constance [aut], Kevin Hommel [aut]
Maintainer:	Michal Kouril <Michal.Kouril@cchmc.org>
Repository:	CRAN
Date/Publication:	2025-04-09 17:00:02 UTC

oncmap: Analyze Data from Electronic Adherence Monitoring Devices

Description

Medication adherence, defined as medication-taking behavior that aligns with the agreed-upon treatment protocol, is critical for realizing the benefits of prescription medications. Medication adherence can be assessed using electronic adherence monitoring devices (EAMDs), pill bottles or boxes that contain a computer chip that records the date and time of each opening (or “actuation”). Before researchers can use EAMD data, they must apply a series of decision rules to transform actuation data into adherence data. The purpose of this R package ('oncmap') is to transform EAMD actuations in the form of a raw .csv file, information about the patient, regimen, and non-monitored periods into two daily adherence values – Dose Taken and Correct Dose Taken.

Author(s)

Maintainer: Michal Kouril Michal.Kouril@cchmc.org (ORCID)

Authors:

• Meghan McGrady Meghan.McGrady@cchmc.org (ORCID)

• Mara Constance Constance.Mara@cchmc.org (ORCID)

• Kevin Hommel Kevin.Hommel@cchmc.org (ORCID)

Pre-process time data for adherence

Description

Pre-process time data for adherence

Usage

adherence_preprocess(
  timestamps,
  regimen,
  patinfo = list(),
  nonmonit = data.frame()
)

Arguments

Value

A list of output variables

• all_periods - Processed timestamps into periods applying input parameters.

Adherence input format definitions

Description

Defines input format parameters to apply when reading input files.

Usage

input_formats

Format

One input format per row described by the following variables:

skip_header_lines

double Number of lines to skip before reading data

header_line_patientid

character Regex to apply to the header line to extract patient ID

patientid_filename

logical Patient id is embedded in the filename

deviceid_header

character Device ID column in the input data

headers

character Comma separated list of expected column headers

patientid_header

character Patient ID column in the input data

datetime_header

character Actuation Date/Time column in the input data

datetime_format

character Actuation Date/Time format

filter

character Inclusion/Exclusion filter to apply on the input data

tz_colon_fix

logical Fix for when TZ contains with ':'

Process input file and return adherence report

Description

Process input file and return adherence report

Usage

process_eamd(
  infile,
  include_formats = NULL,
  exclude_formats = NULL,
  formats_def = NULL,
  infile_data_output = FALSE,
  regimen = NULL,
  patinfo = NULL,
  nonmonit = NULL,
  med = "",
  adhstart = NULL,
  adhend = NULL
)

Arguments

Value

A list containing variables:

• report - Per period adherence statistic

• adh - Summary adherence statistic

Examples

  input_file <- system.file('extdata', 'sample-data-ecap2.csv', package = 'oncmap')
  report <- process_eamd("tests/testthat/ecap1.csv")

Read input file

Description

Read input file

Usage

read_input(
  infile,
  include_formats = NULL,
  exclude_formats = NULL,
  formats_def = NULL,
  infile_data_output = FALSE
)

Arguments

Value

A list of output variables

• format - Detected input format name

• format_def - Detected format definition

• patient_id - Extracted patient_id

• device_id - Extracted device_id

• data - Extracted timestamps

• log - Log of the format detection

• infile_data - Raw input data

Examples

  input_file <- system.file('extdata', 'sample-data-ecap2.csv', package = 'oncmap')
  input <- read_input("tests/testthat/ecap1.csv")

Adherence regimens definitions

Description

Defines built-in regimen definitions.

Usage

regimens

Format

One regimen per row described by the following variables:

name

character A name of the regimen

doses_per_period

integer Number of doses per period

periods_per_day

integer Number of periods per day

min_wait

integer Minimum wait time (in seconds) between actuations

days_per_week

integer Number of active days per week

weekdays

string Specific days per week when active

Report standarized output of the adherence processing

Description

Report standarized output of the adherence processing

Usage

report_adherence(
  all_periods,
  timestamps,
  med,
  patinfo = list(),
  adhstart = NULL,
  adhend = NULL
)

Arguments

Value

A list of output variables

• report - Per period adherence statistic

• adh - Summary adherence statistic