CMHSU: An R Statistical Software Package to Detect Mental Health Status, Substance Use Status, and Their Concurrent Status in the North American Healthcare Administrative Databases

Abstract

The concept of concurrent mental health and substance use (MHSU) status and its detection in patients has garnered growing interest among psychiatrists and healthcare policymakers over the past four decades. Researchers have proposed various diagnostic methods, including the Data-Driven Diagnostic Method (DDDM), for the identification of MHSU. However, the absence of a standalone statistical software package to facilitate DDDM for large healthcare administrative databases has remained a significant gap. This paper introduces the R statistical software package CMHSU (version 0.0.6.9), available on the Comprehensive R Archive Network (CRAN), for the diagnosis of mental health (MH) status, substance use (SU) status, and their concurrent (MHSU) status. The package implements DDDM using hospital and medical service physician visit counts along with maximum time span parameters for MH, SU, and MHSU diagnoses. A simulated real-world dataset incorporating fentanyl is presented to examine various analytical aspects, including three key dimensions of MHSU detection based on the DDDM framework, as well as temporal analysis to demonstrate the package’s application for healthcare policymakers. Additionally, the limitations of the CMHSU package and potential directions for its future extension are discussed.

1. Introduction

The introduction of this paper is organized into four main sections: Section 1.1 outlines definitions and diagnostic approaches for concurrent mental health and substance use status (MHSU), with a particular emphasis on the Data-Driven Diagnostic Method (DDDM). Section 1.2 provides a summary of the primary North American healthcare administrative databases. Section 1.3 explores the motivations for developing the “CMHSU” statistical software package. Lastly, Section 1.4 details the outline of the study.

1.1. Concurrent Mental Health Status and Substance Use Status: Definition and Diagnosis

The concept of concurrent mental health (MH) and substance use (SU) status, collectively referred to as MHSU status, has been explored for over four decades [1,2,3,4,5,6,7,8,9,10,11,12,13], with significant attention given to its methodological challenges [14]. Various approaches have been developed to diagnose MHSU status, each with distinct applications and strengths. The primary diagnostic methods are outlined below.

1.1.1. Comprehensive Clinical Assessment (CCA)

This method involves in-depth evaluations and interviews conducted by healthcare professionals to gain a thorough understanding of an individual’s mental health, substance use patterns, and psychosocial factors. CCA typically includes assessments of psychiatric and medical history, as well as risk evaluation [15,16]. For example, a psychiatrist may utilize the Psychiatric Research Interview for Substance and Mental Disorders (PRISM) to diagnose major depressive disorder and evaluate alcohol dependency patterns.

1.1.2. Standardized Screening Instruments (SSI)

SSIs are structured tools designed to assess the presence and severity of mental health and substance use disorders. Common instruments include the Generalized Anxiety Disorder-7 (GAD-7), the Patient Health Questionnaire-9 (PHQ-9), the Drug Abuse Screening Test (DAST), and the Alcohol Use Disorders Identification Test (AUDIT) [17,18]. For instance, a general practitioner might employ the AUDIT to detect harmful drinking behaviors in a patient suspected of having an anxiety disorder.

1.1.3. Integrated Treatment Approach (ITA)

ITA emphasizes the simultaneous treatment of mental health and substance use disorders within a unified, evidence-based framework. This approach prioritizes coordinated strategies to address the complex interactions between these conditions [19,20]. For example, a patient with bipolar disorder and opioid use disorder may receive medication-assisted treatment (MAT) alongside cognitive-behavioral therapy (CBT) as part of an integrated care plan.

1.1.4. Multidisciplinary Collaboration (MC)

This method involves a coordinated effort among a team of professionals, such as psychiatrists, addiction specialists, and social workers, to design and implement a comprehensive care plan tailored to individuals with co-occurring disorders [21,22]. For instance, a multidisciplinary team comprising a psychiatrist, a social worker, and an addiction counselor may convene weekly to plan and manage the care of a patient diagnosed with schizophrenia and alcohol dependence.

1.1.5. Data-Driven Diagnostic Method (DDDM)

The DDDM leverages clinical and administrative data analysis to identify co-occurring mental health and substance use status through the utilization of healthcare databases and the International Classification of Disease (ICD) codes. This approach is based on patterns of healthcare usage, such as hospitalizations and physician visits [23,24,25,26]. For example, a healthcare researcher may analyze hospital records to identify individuals who, within the past year, had at least one hospitalization or two medical physician visits for mental health and substance use status, as indicated by ICD-10 codes [24,25,26].

The DDDM approaches have been based on frequency and time-based detection of plausible ICD codes from healthcare administrative databases [24,25,26]. In general format, we set the following general statistical parametric definition [27,28,29] (Figure 1):

Definition 1. 

Data-Driven Diagnostic Method (DDDM)

Given time spans $t_{MH},t_{SU},$ and $t_{MHSU}$ and frequencies $n_{MHH},n_{MHP},n_{SUH},n_{SUP}.$ Then, a patient has concurrent mental health substance use (MHSU) diagnosis if and only if in the past $t_{MHSU}$ time span the patient had the following two conditions:

[a] 

at least one mental health (MH) diagnosis (defined by at least $n_{MHH}$ times hospitalizations or $n_{MHP}$ primary care physician visits within $t_{MH}$ time span),

[b] 

at least one substance use (SU) diagnosis (defined by at least $n_{SUH}$ times hospitalizations or $n_{SUP}$ primary care physician visits within $t_{SU}$ time span).

Remark 1. 

The diagnosis of MH status or SU status is based on detection of associated ICD-09, ICD-10, or ICD-11 codes from administrative databases. Examples are provided in Section 3 with a simulated database.

Remark 2. 

The precise values for the set of parameters $t_{MH},t_{SU},t_{MHSU},n_{MHH},n_{MHP},n_{SUH},n_{SUP}$ are decided by the study’s principal clinician, given various internal, external, and contextual factors.

1.2. North American Healthcare Administrative Databases

In both Canada and the United States, numerous healthcare administrative databases are available, varying by regional level (federal/state or provincial) and by the type of institution managing the data (hospitals or medical service physician providers).

Table 1. The North American healthcare administrative databases in terms of country, level, hospital, and medical service physician categories.

Country	Level	Hospital Data	Physician Data
Canada ()	Federal	Discharge Abstract Database (DAD) National Ambulatory Care Reporting System (NACRS)	Canadian Institute of Health Information(CIHI) Physician Claims Data Canadian Management Information Database (CMDB)
	Province	MED-ÉCHO (Quebec) data Ontario Health data Alberta Health data	Medical Services Plan (MSP) Data (BC) Alberta Health Physician Claims Régie de l’assurance maladie du Québec (RAMQ) Ontario Health Insurance Plan (OHIP)
	Territory	Yukon Hospital Corporation Dis-charge Data Northwest Territories Health Authority Records	Yukon Health Care Insurance Plan Claims Northwest Territories Medical Billing Data
United States ()	Federal	National Inpatient Sample (NIS) Medicare Provider Analysis and Review (MEDPAR) Veterans Affairs (VA) Inpatient Data	Medicare Physician/Supplier Part B Claims Data National Ambulatory Medical Care Survey (NAMCS) Veterans Affairs (VA) Outpatient Data
	State	State Inpatient Databases (SID) California Office of Statewide Health Planning and Development (OSHPD) New York Statewide Planning and Research Cooperative System (SPARCS)	State Medicaid Claims Data All-Payer Claims Databases (APCDs: e.g., Massachusetts, Colorado)
	Territory	Guam Memorial Hospital Authority Records American Samoa Dept. of Health Inpatient Data	Guam Medicaid and CHIP Claims Data American Samoa Medicaid Claims 1

¹ As of 3 January 2025.

outlines the most significant databases across North America. These databases commonly record several crucial variables, including Client ID, Visit Date, Discharge Date, and Disease Diagnostic Code.

The term Disease Diagnostic Code refers to codes from the World Health Organization’s International Classification of Diseases (ICD) [30]. The ICD codes utilized in American and Canadian healthcare systems are detailed in [31,32]. Within each country, state or provincial systems may adopt their versions of these federally recognized ICD codes [24,25,26,33]. In this study, we consider ICD codes broadly, irrespective of their version (ICD-09, ICD-10, or ICD-11), focusing on codes ranging from three to five characters in length, presented without a decimal point.

Remark 3. 

The ICD codes provided in the following examples for mental health (MH) status and substance use (SU) status are intended as illustrative examples rather than exhaustive lists. The complete set of ICD codes for these conditions may vary based on local and national guidelines, as well as the criteria established by study principal investigators.

1.3. Motivation

The DDDM has several advantages over other methods for the diagnosis of MHSU as follows:

(i)

Scalability and Large-Scale Analysis: The Data-Driven Diagnostic Method (DDDM) offers the advantage of scalability by utilizing healthcare databases and administrative records to analyze large populations. Unlike approaches that require direct patient interaction, DDDM enables the comprehensive assessment of co-occurring mental health and substance use status across diverse demographic groups and healthcare systems [23].

(ii)

Objective and Quantitative Approach: DDDM relies on the objective extraction and analysis of the data features such as ICD codes and patterns of healthcare utilization. This DDDM characteristic minimizes biases often associated with subjective methods, such as clinical interviews, thereby improving the reliability and validity of diagnostic outcomes [24].

(iii)

Cost-Effectiveness: By leveraging preexisting healthcare data, DDDM eliminates the need for resource-intensive procedures, such as in-person assessments or multidisciplinary team evaluations. This makes it a cost-efficient alternative for healthcare systems facing resource limitations [25].

(iv)

Timeliness and Accessibility: DDDM enables rapid identification of MHSU patterns through the querying of existing data sources, providing real-time or nearly real-time diagnostic capabilities. This characteristic is particularly valuable for tracking trends and addressing emerging public health issues [26].

(v)

Population-Level Insights for Policy and Planning: Through its capacity to analyze large-scale healthcare data, DDDM facilitates the identification of utilization trends, disparities, and service gaps. This characteristic allows policymakers to design targeted interventions and optimize resource allocation to address the needs of individuals with co-occurring status [24].

However, despite all the above advantages of DDDM over other methods for diagnosis of MHSU status, there has been no available statistical software package with the given parameters in the Definition 1 to help researchers implement MHSU diagnosis detection. The R Statistical software CMHSU enables researchers to detect MHSU status with a variety of scenarios in terms of time span, visit frequency, subtypes of mental health, and subtypes of substance use.

1.4. Study Outline

This paper is structured as follows: Initially, we provide essential theories and instructions for the installation of the CMHSU package. We introduce the four primary functions of the package, which are designed to detect mental health (MH) status, substance use (SU) status, and their concurrent (MHSU) status in both basic and comprehensive forms. Subsequently, we describe a simulation study using a simulated real-world healthcare administrative dataset to identify MH, SU, and MHSU statuses. This study comprises four sub-studies. In the first three, specific parameters from Definition 1 are held constant while others vary, enabling an analysis of trends in the detection of MH, SU, and MHSU statuses. The final sub-study focuses on temporal analysis, demonstrating an example of package application for the North American healthcare policymakers. We conclude with a discussion on the contributions of the CMHSU package to existing literature, its limitations, and future development plans.

2. The CMHSU Package

2.1. The Background and Installation

The CMHSU package utilizes the Data-Driven Diagnostic Method (DDDM) parametric Definition 1 detailed in Section 1.1 and illustrated in Figure 1. It requires four R packages: dplyr [34], tidyr [35], purrr [36], and magrittr [37], and was developed using R version 4.2.2 [38]. The package (version 0.0.6.9) is accessible on the Comprehensive R Archive Network (CRAN) at https://CRAN.R-project.org/package=CMHSU (accessed on 10 January 2025). Installation and loading of the package can be performed using R commands:

• Line #1: > install.packages(‘‘CMHSU’’, dependencies=TRUE)
• Line #2: > library(CMHSU)

The CMHSU package includes four primary multivariate functions:

• (1) MH_status(),
• (2) SU_status(),
• (3) MHSU_status_basic(),
• (4) MHSU_status_broad.

The first two functions focus specifically on the individual components of mental health (MH) status or substance use (SU) status as depicted in Figure 1. The latter two functions encompass the comprehensive framework shown in Figure 1. Each function is described in detail in the subsequent subsections.

2.2. Detection of Mental Health Status

The function MH_status() is designed to determine the mental health status of patients based on a predefined list of plausible mental health diagnostic codes provided by clinicians. This function requires five input parameters. The first parameter, inputdata, represents the patient data and is formatted as a dataframe with four essential columns:

• ClientID, which uniquely identifies the patient,
• VisitDate, indicating the date of the visit,
• Diagnostic_H, representing diagnoses made during hospital visits,
• Diagnostic_P, reflecting diagnoses made by medical service physicians.

The second, third, and fourth parameters, n_MHH, n_MHP, and t_MH, specify the minimum number of hospital visits required, the minimum number of medical physician visits needed, and the maximum allowable time lag (in days) between hospital or physician visits, respectively. Finally, the fifth parameter, ICD_MH, contains the list of plausible mental health diagnostic codes determined by the study clinicians. This function returns a dataframe matrix including ClientID, earliest date of mental health, latest date of mental health, and the mental health status (Yes/No).

As an initial working example, we utilize a simulated real-world dataset, as described in Section 3.1, to identify all patients with a mental health status corresponding to one of the following statuses: psychotic, mood, anxiety, or neurocognitive disorders. The detection criteria include at least one hospital visit or at least one medical service physician visit, within a maximum time span of two months (60 days). The corresponding R code for implementing this detection is shown below; it generates the results depicted in Figure 2a:

Line #1: > myexample<-SampleRWD[,c(1:4)]

Line #2: > SampleMH_1 = MH_status(myexample, n_MHH=1, n_MHP=1, t_MH=60,

            ICD_MH=c(‘‘F060’’,‘‘F063’’,‘‘F064’’,‘‘F067’’))

Line #3: > head(SampleMH_1)

2.3. Detection of Substance Use Status

The function SU_status() is similar to MH_status(). It is designed to determine the substance use status of patients based on a predefined list of plausible substance use diagnostic codes provided by clinicians. This function also requires five input parameters. The first parameter, inputdata, is a dataframe with columns:

• ClientID,
• VisitDate,
• Diagnostic_H,
• Diagnostic_P.

The second, third, and fourth parameters, n_SUH, n_SUP, and t_SU, specify the minimum number of hospital visits, the minimum number of physician visits, and the maximum time lag (in days) between visits, respectively. The fifth parameter, ICD_SU, is the list of plausible substance use diagnostic codes. This function returns a dataframe including ClientID, earliest date of substance use, latest date of substance use, and the substance use status (Yes/No).

As the second working example, we identify all patients with a substance use status corresponding to one of the following statuses: alcohol use, fentanyl use, cannabis use, or cocaine use. The detection criteria require at least one hospital visit or one medical service physician visit, within a maximum allowable time span of two months (60 days). Below is the corresponding R code; it generates the results illustrated in Figure 2b:

Line #1: > myexample<-SampleRWD[,c(1:4)]

Line #2: > SampleSU_1 = SU_status(myexample, n_SUH=1, n_SUP=1, t_SU=60,

              ICD_SU=c(‘‘F100’’,‘‘T4041’’,‘‘F120’’,‘‘F140’’))

Line #3: > head(SampleSU_1)

2.4. Detection of Concurrent Mental Health and Substance Use (MHSU) Status—Part (I)

The function MHSU_status_basic() is designed to detect concurrent MH and SU status. It requires ten input parameters:

• inputdata (dataframe with ClientID, VisitDate, Diagnostic_H, Diagnostic_P),
• n_MHH,
• n_MHP,
• n_SUH,
• n_SUP,
• t_MH,
• t_SU,
• t_MHSU,
• ICD_MH,
• ICD_SU.

Here, n_MHH and n_MHP are the minimum numbers of hospital and physician visits for MH; n_SUH and n_SUP are the minimum numbers for SU; and t_MH and t_SU are maximum lags within MH and SU, respectively. The parameter t_MHSU is the maximum time span between MH and SU statuses. Both ICD_MH and ICD_SU are lists of relevant diagnostic codes. The function returns a dataframe with earliest/latest MH dates, MH status, earliest/latest SU dates, SU status, and the concurrent status (Yes/No). It assumes the input data time span is less than or equal to t_MHSU.

As the third working example, we build on the earlier two to detect the concurrent mental health and substance use (MHSU) status for clients diagnosed with psychotic, mood, anxiety, or neurocognitive disorders in combination with alcohol, fentanyl, cannabis, or cocaine consumption-related status. We require a minimum of one hospital visit and one physician visit within two months (60 days) for each of MH and SU; the maximum time span between MH and SU statuses is set to one year (365 days). It is important to note that the total dataset time span is 363 days, which is slightly shorter than the specified maximum span of 365 days. The R code is below; results appear in Figure 2c:

Line #1: > myexample<-SampleRWD[,c(1:4)]

Line #2: > SampleMHSU_1 = MHSU_status_basic(myexample, n_MHH=1, n_MHP=1, n_SUH=1,

            n_SUP=1, t_MH=60, t_SU=60, t_MHSU=365,

            ICD_MH=c(‘‘F060’’,‘‘F063’’,‘‘F064’’,‘‘F067’’),

            ICD_SU=c(‘‘F100’’,‘‘T4041’’,‘‘F120’’,‘‘F140’’))

Line #3: > head(SampleMHSU_1)

2.5. Detection of Concurrent Mental Health and Substance Use (MHSU) Status—Part (II)

A key assumption of MHSU_status_basic() is that the data time span is ≤$t\_MHSU$. When this does not hold, MHSU_status_broad() can be used. It takes the same ten parameters but generates k non-overlapping windows of concurrent MH and SU output datasets ( $k=\left|TimeSpan\left(\mathit{inputdata}\right)\right|-t_{MHSU}+1$ ). Each output includes a “Window” variable to denote the respective time window (see Figure 3). Thus, for a dataset of size n, the output can have size $k\times n$.

As the final working example, we modify the third example to detect MHSU status with a maximum allowable time span between MH and SU (t_MHSU) of 360 days, while the total dataset is 363 days. This implies $k=363-360+1=4$ non-overlapping windows. The code below illustrates usage; it produces results in Figure 2d:

Line #1: > myexample<-SampleRWD[,c(1:4)]

Line #2: > SampleMHSU_2 = MHSU_status_broad(myexample, n_MHH=1, n_MHP=1, n_SUH=1,

              n_SUP=1, t_MH=60, t_SU=60, t_MHSU=360,

              ICD_MH=c(‘‘F060’’,‘‘F063’’,‘‘F064’’,‘‘F067’’),

              ICD_SU=c(‘‘F100’’,‘‘T4041’’,‘‘F120’’,‘‘F140’’))

Line #3: > head(SampleMHSU_2[c(1,201,401,601),])

3. A Simulation Study

This section introduces a simulation study, encompassing its data and analysis, and is organized into four key parts. Section 3.1 outlines the characteristics of the simulated real-world dataset. Section 3.2 examines how varying the maximum time span within MH status and within SU status affects the frequency of MH, SU, and MHSU diagnoses, given the assumption of a constant number of hospital and medical service physician visits. Section 3.3 investigates the influence of the number of required hospital and physician visits on MH, SU, and MHSU detection, assuming a fixed maximum time span for MH and SU. Finally, Section 3.4 explores the effect of varying the maximum time span within MH, within SU, and between MH and SU on the number of MHSU diagnoses, assuming fixed number of hospital and medical service physician visits.

3.1. Simulated Real-World Data

We simulate a healthcare administrative dataset as follows:

• The dataset consists of 200 patients categorized into seven diagnostic groups who visited hospitals or medical service physicians from 1 January 2024, to  31 December 2024.
• The patient groups include 125 individuals with recorded mental health (MH) diagnoses, 125 with substance use (SU) diagnoses, 100 with concurrent MHSU diagnoses, and 50 with no MH, SU, or MHSU diagnoses.

Table 2. Key features of the simulated real-world healthcare administrative database.

Group	Size	Visit Date Span	Visit Length	#Hospital	#Physician	SU (Freq)	MH (Freq)	Other (Freq)
1	10	1 January 2024 –31 January 2024	1 month	1	2	F100 (1)	F060 (2)	NA
2	20	1 February 2024–31 March 2024	2 months	2	4	T4041 (2)	F063 (4)	J10 (4)
3	30	1 April 2024–31 June 2024	3 months	3	6	F120 (3)	F064 (6)	I10 (3)
4	40	1 July 2024–31 December 2024	6 months	6	12	F140 (6)	F067 (12)	I10 (6), J10 (12)
5	25	1 November 2024–31 December 2024	2 months	3	6	F100 (3)	NA	J10 (6)
6	25	1 November 2024–31 December 2024	2 months	2	4	NA	F060 (4)	I10 (2)
7	50	1 November 2024–31 December 2024	2 months	1	2	NA	NA	I10 (1), J10 (2)

Notes: F100 (Alcohol); F060 (Psychotic); T4041 (Fentanyl); F063 (Mood); F120 (Cannabis); F064 (Anxiety); F140 (Cocaine); F067 (Neurocognitive); I10 (Hypertension); J10 (Influenza); NA (Not Applicable).

summarizes key features of the simulated dataset, and

Table 3. Two sample clients from the 200 patients in the simulated real-world healthcare administrative database.

ClientID	VisitDate	Diagnostic_H	Diagnostic_P	MHSU_H	Meaning_H	MHSU_P	Meaning_P
001	31 January 2024	F100	NA	SU	Alcohol	NA	NA
001	15 January 2024	NA	F060	NA	NA	MH	Psychotic
001	19 January 2024	NA	F060	NA	NA	MH	Psychotic
011	19 February 2024	T4041	NA	SU	Fentanyl	NA	NA
011	7 March 2024	T4041	NA	SU	Fentanyl	NA	NA
011	14 February 2024	NA	F063, J10	NA	NA	MH	Mood, Influenza
011	17 February 2024	NA	F063, J10	NA	NA	MH	Mood, Influenza
011	14 March 2024	NA	F063, J10	NA	NA	MH	Mood, Influenza
011	10 March 2024	NA	F063, J10	NA	NA	MH	Mood, Influenza

Notes: Diagnostic_H: ICD code for diagnosis at the hospital; Diagnostic_P: ICD code for diagnosis by service physician; MHSU_H: MH/SU status assigned at hospital; MHSU_P: MH/SU status assigned by physician; Meaning_H: hospital-assigned ICD meaning; Meaning_P: physician-assigned ICD meaning; ICD: International Classification of Diseases.

provides example entries for two sample patients. This dataset is included as part of the CMHSU R package (see Supplementary Materials).

3.2. The Impact of Maximum Time Span Within Mental Health and Within Substance Use

We examine how the maximum allowable time interval within MH and SU diagnoses affects detection counts. Specifically, we require at least two hospital or two physician visits within x days ($x=0-56$) for both MH and SU, while setting the maximum allowable interval between MH and SU to one year (365 days):

$$\mathtt{n}\_\mathtt{MHH}=\mathtt{n}\_\mathtt{MHP}=\mathtt{n}\_\mathtt{SUH}=\mathtt{n}\_\mathtt{SUP}=2,\mathtt{t}\_\mathtt{MH}=\mathtt{t}\_\mathtt{SU}=x(0\le x\le 56),\mathtt{t}\_\mathtt{MHSU}=365.$$

Figure 4 presents the results. As the maximum required time interval for diagnosis increases, the number of patients detected rises for MH, SU, and MHSU, eventually reaching an asymptote at 125 patients for MH, 115 patients for SU, and 90 patients for MHSU.

3.3. The Impact of Number of Hospital Visits and Medical Service Physician Visits

We now investigate how the required number of hospital visits impacts detection counts for MH, SU, and MHSU. We assume a hospital-to-physician visit ratio of 1:2, that is,

$$\mathtt{n}\_\mathtt{MHH}={\displaystyle \frac{1}{2}}\mathtt{n}\_\mathtt{MHP},\mathtt{n}\_\mathtt{SUH}={\displaystyle \frac{1}{2}}\mathtt{n}\_\mathtt{SUP},\mathtt{n}\_\mathtt{MHH}=\mathtt{n}\_\mathtt{SUH}=x,x=1,\dots ,8,$$

and fix $\mathtt{t}\_\mathtt{MH}=\mathtt{t}\_\mathtt{SU}=183$ (6 months), $\mathtt{t}\_\mathtt{MHSU}=365$ (1 year). Figure 5 displays the results. As the required number of hospital visits increases, detection counts decrease until eventually reaching zero for all three diagnostic count curves (MH, SU, and MHSU). Additionally, for large required number of hospital visits, the MH and MHSU count curves overlap.

3.4. The Impact of Maximum Time Span for Concurrent Diagnosis

Finally, we study how varying t_MHSU affects the frequency of concurrent MHSU detection, assuming fixed maximum spans t_MH and t_SU. We require at least two hospital or two physician visits within x days ($x\in \{14,21,28\}$) for MH and SU:

$$\mathtt{n}\_\mathtt{MHH}=\mathtt{n}\_\mathtt{MHP}=\mathtt{n}\_\mathtt{SUH}=\mathtt{n}\_\mathtt{SUP}=2,\mathtt{t}\_\mathtt{MH}=\mathtt{t}\_\mathtt{SU}=x,x=14,21,28,$$

and then let $\mathtt{t}\_\mathtt{MHSU}=y$ vary in discrete steps of $31k$ ($k=1,\dots ,12$). Figure 6 shows the results. For each fixed maximum time span for MH and SU, the number of detected patients increases with increasing maximum time span for MHSU diagnosis, approaching an asymptote. Also, for a fixed maximum time span for MHSU diagnosis, increasing maximum time span for MH and SU leads to capturing more patients.

3.5. Temporal Analysis

In this section, we assume that, unlike the previous three Section 3.2, Section 3.3 and Section 3.4, the study’s principal investigators have established agreed-upon default values for key parameters. These include a minimum of one hospital visit, a minimum of two medical service physician visits, a maximum time span of one month for mental health diagnoses, a maximum time span of one month for substance use diagnoses, and a maximum time span of one month for concurrent diagnoses. Here, policymakers are particularly interested in monitoring the monthly trends in the frequency and rate of MH, SU, and MHSU diagnoses throughout the 2024 calendar year. Figure 7 presents the results using similar programming presented in Appendix A.1 and Appendix A.2. As shown in the figure, both MH and SU exhibit an overall increasing trend over time, reaching their peak in November. In contrast, MHSU follows a fluctuating pattern initially, followed by a period of stabilization until November. However, all three categories experience a sharp decline in December.

Remark 4. 

The temporal analysis presented here is based on frequency statistics. A similar approach applies to rate statistics, depending on the objectives of the principal investigators. The key difference lies in using proportions instead of counts in the estimation process, as outlined in Appendix A.2.

Remark 5. 

Given the nature of the healthcare administrative database and the study objectives, principal investigators have the flexibility to consider various temporal components for [Unit, Span] in the temporal analysis. In this study, our temporal analysis was conducted to examine monthly variations over a year, represented as [Month, Year]. Other potential examples include [Day, Month], [Week, Year], [Quarter, Year], and [Year, Decade].

4. Discussion

4.1. Summary and Contributions

We introduce the R package CMHSU, the first statistical software package to implement the Data-Driven Diagnostic Method (DDDM) for identifying mental health (MH) status, substance use (SU) status, and concurrent (MHSU) status within the North American healthcare administrative databases. The package provides flexibility to accommodate various scenarios, including (i) the minimum required visits to hospitals or medical service physicians, (ii) the maximum time spans for MH and SU diagnoses, and (iii) the maximum time span between them.

The first key contribution of the CMHSU package is enabling clinicians to define concurrent MHSU status using the DDDM approach with standard agreed-upon threshold parameters. The examples presented in this paper highlight three critical dimensions and their associated challenges in achieving this definition. Once these dimensions are addressed simultaneously, defining concurrent MHSU status based on the DDDM becomes feasible. The details of these dimensions are as follows:

• Dimension of Time Spans within MH Diagnosis and SU Diagnosis (Section 3.2): The time spans within MH and SU diagnoses play a critical role. For instance, if a maximum time span of 7 days is considered, only 48 out of 100 patients (48.8%) are captured, whereas extending the time span to 56 days captures 90 out of 100 patients (90.0%). This delicate situation raises the question: “What are the appropriate maximum time spans for MH and SU diagnoses?”
• Dimension of Required Number of Visits (Section 3.3): The number of required hospital and medical service physician visits significantly influences the detection rates. For example, requiring two hospital visits and four physician visits captures 90 out of 100 patients (90.0%), while increasing the required threshold to three hospital visits and six physician visits reduces the capture rate to 70 out of 100 patients (70.0%). This delicate balance prompts the question: “What is the optimal minimum number (or ratio) of required visits?”
• Dimension of Time Span for Concurrent (MHSU) Status (Section 3.4): The maximum time span between MH and SU diagnoses also plays a vital role in the detection. For instance, setting this span to one month captures 61 out of 100 patients (61.0%), while extending it to three months captures 84 out of 100 patients (84.0%). This scenario raises the question: “What is the ideal maximum time span between MH and SU diagnoses?”

The second key contribution of the CMHSU package is its ability to diagnose comorbidities of various diseases within healthcare administrative databases. While originally designed for the concurrent mental health and substance use (MHSU) diagnoses, the package does not impose limitations on its input ICD variables, making it applicable for any other comorbidity conditions.

The final key contribution of the CMHSU package is its utility for policy-makers at the federal, state, and territorial levels. By facilitating the rapid compilation of databases tracking ongoing mental health status, substance use status, and concurrent status, the package enables timely monitoring of trends. This real-time capability supports the development and implementation of appropriate healthcare policies in a timely manner.

4.2. Strengths, Limitations, and Future Work

The R package CMHSU offers several unique features that make it a valuable and advantageous statistical software tool for detecting mental health (MH) status, substance use (SU) status, and concurrent mental health and substance use (MHSU) status within large administrative healthcare databases. These features include the following:

• Flexibility: CMHSU incorporates four core functions and ten customizable parameters, allowing researchers to account for a wide range of predefined scenarios by investigators when identifying MH status, SU status, and MHSU status in the healthcare administrative databases.
• Comprehensiveness: CMHSU enables the detection of nearly all mental health and substance use conditions, providing an advantage over other statistical tools, particularly given the recent comprehensive codifications in ICD-10 and ICD-11.
• Efficiency: The CMHSU package is designed for ease of use, requiring only a basic statistical background. Unlike advanced statistical and machine learning-based detection methods for MH status [39], SU status [40], and MHSU status [41]—which typically necessitate expertise in topics such as K-Nearest Neighbors, Random Forests, Gradient Boosted Trees, Deep Neural Networks—CMHSU offers a user-friendly and time-efficient alternative statistical software tool. This advantage makes it a particularly accessible and practical tool for researchers and practitioners without extensive statistical or machine learning expertise.
• Interpretability: CMHSU employs a trace-back methodology to identify MH status, SU status, and MHSU status based on their corresponding ICD codes. This approach enhances the clarity and transparency of the results, facilitating faster interpretation, improved visualization of detected cases, and analysis of trends over time compared to other statistical tools.
• Seamless Integration: The package is free and easy to install, ensuring compatibility with existing analytical tools used for processing large healthcare administrative databases. This seamless integration enhances its accessibility and usability in the real-world research applications.

This work has several limitations, each of which presents opportunities for future extensions. Some of them are as follows:

• Scalability: For large-scale databases, it may be more efficient to partition the input dataset into multiple disjoint subsets and apply the MHSU_status_broad() function to each subset separately to manage the extensive outputs. Introducing an additional parameter within the function to automate the partitioning of the input data (inputdata) would further optimize the computational process (See Appendix A.1).
• Output Format: The package currently generates outputs as dataframes only, without providing summary frequency statistics for mental health status, substance use status, and their concurrent status. Calculating these statistics requires additional R programming (See Appendix A.2).
• Customization: The window lag in the function MHSU_status_broad() is fixed at one day (as illustrated in Figure 3). Adding a fixed or adaptive parameter to specify the length of this window lag would enhance the flexibility of the detection process for researchers. The choice of fixed or adaptive status depends to the specific patient data in the study.
• Evaluation: The DDDM approach assumes that ICD coding in administrative databases is reliable. However, in practice, these records are often incomplete or subject to misclassifications, leading to potential biases in the evaluation process and, consequently, affecting the accuracy of the results. Furthermore, it is still unclear how to measure the package’s precision performance in detecting patients with MH status, SU status, and MHSU status, as well as how to compare its performance using DDDM with more advanced machine learning-based methods [39,40,41]. This comparison needs a mapping mechanism between the above parameters in the DDDM and above machine learning-based methods requiring subsequent methodological research.
• Standardization: The use of ICD codes for diagnosis depends on the local and national jurisdictions (Table 1). Potential inconsistencies in coding across different jurisdictions and healthcare databases may affect the reliability of the results for comparisons across these jurisdictions.
• Empirical Validation: The simulation study presented in this paper utilizes self-generated simulated data. Ideally, using a real-life empirical healthcare administrative database would significantly enhance the validity and applicability of the findings for healthcare policy implementations. However, key obstacles—including (1) data privacy and security regulations, (2) access restrictions and bureaucratic hurdles, and (3) selection bias—prevented the use of such a database in the current analysis.
• Geographical Adaptability: CMHSU is designed for detecting mental health (MH) status, substance use (SU) status, and their concurrent (MHSU) status within the North American healthcare databases, based on the fact that the original DDDM was developed by researchers in this region. However, it remains unclear whether these methods can be effectively adopted for use in the non-North American healthcare systems, given potential differences in healthcare infrastructure, coding practices, and administrative data structures. Despite all these issues, given availability of the essential data fields, a preliminary analysis is still possible (See Section 4.3).
• Temporal Analysis: The simulation study in this paper serves as a hypothetical demonstration of the package’s application. Its results can only be truly meaningful and applicable to real-world policymaking if the DDDM parameters are based on a universally agreed-upon set of predefined values related to time span and visit definitions. However, no such universally accepted standard parameters currently exist among psychiatrists. Addressing this issue requires further discussions, research, and a final systematic review and meta-analysis among various studies.

4.3. Summary of CMHSU Data Analysis Workflow

We conclude this section with a summary of the data analysis workflow, designed to facilitate a smooth user experience when applying the CMHSU package in their projects. The workflow comprises the following steps:

(i)

Compile CMHSU Data:

Gather essential data fields, including ClientID, VisitDate, Diagnostic_H, and Diagnostic_P.

(ii)

Assess Scalability:

(a)

Size: Execute data size scalability by applying the function splitfunction_id().

(b)

Time: Execute temporal scalability by applying the function splitfunction_time().

(iii)

Define Analysis Parameters:

Specify required parameters, such as n_MHH, n_MHP, and others as necessary.

(iv)

Examine Data Time Span:

(a)

For data spans less than or equal to t_MHSU, apply the function MHSU_status_basic().

(b)

For data spans exceeding t_MHSU, apply the function MHSU_status_broad().

(v)

Report Results:

(a)

Frequency: Extract count data using the script SummarySampleMHSU_1.

(b)

Proportion: Extract proportion data using the script SummarySampleMHSU_1.

(vi)

Temporal Interpretation:

Interpret temporal patterns by applying the [Unit, Span] methodology illustrated in Section 3.5.

5. Conclusions

The free R software package CMHSU enables researchers to detect mental health (MH) status, substance use (SU) status, and their concurrent (MHSU) status within healthcare administrative databases. The package offers a wide range of flexibility regarding visit count and maximum time span parameters, allowing for comprehensive and adaptable analyses. This functionality facilitates the compilation of these statuses at a large population level in a timely manner, supporting health policymakers in effectively monitoring trends and making informed healthcare decisions to optimize patient treatment.