    library(chmsflow)
    library(recodeflow)
    library(dplyr)

## 1. Introduction

chmsflow provides 16 functions that classify medications from ATC codes recorded in CHMS clinic data. Each function checks whether a respondent is taking a specific drug class and returns `1` (yes) or `0` (no), with `haven::tagged_na()` codes for missing or not-applicable responses.

### Available medication variables

Variable | Drug class | ATC prefix | Cycles 3–6 function | Cycles 1–2 function
--- | --- | --- | --- | ---
`ace_med` | ACE inhibitors | C09 | `is_ace_inhibitor()` | `is_ace_med_cycles1to2()`
`bb_med` | Beta blockers | C07 | `is_beta_blocker()` | `is_bb_med_cycles1to2()`
`ccb_med` | Calcium channel blockers | C08 | `is_calcium_channel_blocker()` | `is_ccb_med_cycles1to2()`
`diur_med` | Diuretics | C03 | `is_diuretic()` | `is_diur_med_cycles1to2()`
`misc_htn_med` | Other antihypertensives | mixed | `is_other_antihtn_med()` | `is_misc_htn_med_cycles1to2()`
`any_htn_med` | Any antihypertensive | combined | `is_any_antihtn_med()` | `is_any_htn_med_cycles1to2()`
`nsaid_med` | NSAIDs | M01A | `is_nsaid()` | `is_nsaid_med_cycles1to2()`
`diab_med` | Diabetes medications | A10 | `is_diabetes_med()` | `is_diab_med_cycles1to2()`

### Cycle differences

Medication data is structured differently across CHMS cycles:

- Cycles 1–2 store medications in a flat format with up to 80 individual columns (`atc_101a` to `atc_235a` for ATC codes, `mhr_101b` to `mhr_235b` for time last taken). The cycles 1–2 wrapper functions accept all of these columns as parameters.
- Cycles 3–6 store medications in a multi-row format with two variables per row: `meucatc` (ATC code) and `npi_25b` (time last taken). Each respondent may have multiple rows. After recoding, results must be aggregated by `clinicid`.

## 2. When to use medication recoding

If your analysis requires medication variables, always perform medication recoding first, before recoding any other variables. Two downstream health outcome variables depend on medication status:

- Hypertension – `any_htn_med` must be merged into the main cycle dataset before deriving hypertension outcomes.
- Diabetes – `diab_med` must be merged before deriving diabetes outcomes.

## 3. Workflow

The workflow is the same for all cycles: recode medication variables and merge into the main cycle dataset using `recode_meds_cycles1to2()` or `recode_meds_cycles3to6()`, then derive health outcomes using `recode_after_meds()`. Use `recode_after_meds()` instead of `rec_with_table()` – it automatically excludes medication-specific rows from `variable_details` so pre-computed medication columns are passed through rather than re-derived.

### 3.1 Cycles 1–2

Cycles 1–2 medication data uses uppercase column names (`CLINICID`, `ATC_101A`, etc.). `recode_meds_cycles1to2()` normalizes these internally.

Step 1 – Recode medication variables and merge with main cycle data. Requires: `cycle1`, `cycle1_meds`.

    cycle1 <- recode_meds_cycles1to2(cycle1, cycle1_meds, c("any_htn_med", "diab_med"))

Step 2 – Derive diabetes status. Requires: `cycle1` from Step 1.

    cycle1_diab_data <- recode_after_meds(
      cycle1,
      c("lab_hba1", "diab_a1c", "diab_med", "ccc_51", "diab_status")
    )
    head(select(cycle1_diab_data, clinicid, diab_status))

      clinicid diab_status
    1        1           1
    2        2           2
    3        3        <NA>
    4        4           1
    5        5           1
    6        6           2

Step 3 – Derive hypertension status. Requires: `cycle1` from Step 1.

    cycle1_htn_data <- recode_after_meds(
      cycle1,
      c(
        # Blood pressure (raw + adjusted)
        "bpmdpbps", "bpmdpbpd", "sbp_adj_mmhg", "dbp_adj_mmhg",
        # Medication inputs (merged in Step 1)
        "any_htn_med", "ccc_32",
        # Diabetes chain (input to htn functions)
        "lab_hba1", "diab_a1c", "ccc_51", "diab_med", "diab_status",
        # CVD chain
        "ccc_61", "ccc_63", "ccc_81", "cvd_status",
        # CKD chain
        "lab_bcre", "pgdcgt", "clc_sex", "clc_age", "gfr_ml_min", "ckd_status",
        # Hypertension outcomes
        "htn_status", "htn_adj_status", "htn_control_status", "htn_control_adj_status"
      )
    )
    head(select(cycle1_htn_data, clinicid, htn_status, htn_adj_status))

      clinicid htn_status htn_adj_status
    1        1          1              1
    2        2          1              1
    3        3          1              1
    4        4          1              1
    5        5          1              1
    6        6          1              1

### 3.2 Cycles 3–6

Step 1 – Recode medication variables and merge with main cycle data. Requires: `cycle3`, `cycle3_meds`.

    cycle3 <- recode_meds_cycles3to6(cycle3, cycle3_meds, c("any_htn_med", "diab_med"))

Step 2 – Derive diabetes status. Requires: `cycle3` from Step 1.

    cycle3_diab_data <- recode_after_meds(
      cycle3,
      c("lab_hba1", "diab_a1c", "diab_med", "ccc_51", "diab_status")
    )
    head(select(cycle3_diab_data, clinicid, diab_status))

      clinicid diab_status
    1        1           1
    2        2           1
    3        3           1
    4        4           1
    5        5           1
    6        6           1

Step 3 – Derive hypertension status. Requires: `cycle3` from Step 1.

`cvd_status`, `diab_status`, and `ckd_status` are intermediate inputs to the hypertension functions. Their full input chains must also be listed so `recode_after_meds()` can derive them.

    cycle3_htn_data <- recode_after_meds(
      cycle3,
      c(
        # Blood pressure (raw + adjusted)
        "bpmdpbps", "bpmdpbpd", "sbp_adj_mmhg", "dbp_adj_mmhg",
        # Medication inputs (merged in Step 1)
        "any_htn_med", "ccc_32",
        # Diabetes chain (input to htn functions)
        "lab_hba1", "diab_a1c", "ccc_51", "diab_med", "diab_status",
        # CVD chain
        "ccc_61", "ccc_63", "ccc_81", "cvd_status",
        # CKD chain
        "lab_bcre", "pgdcgt", "clc_sex", "clc_age", "gfr_ml_min", "ckd_status",
        # Hypertension outcomes
        "htn_status", "htn_adj_status", "htn_control_status", "htn_control_adj_status"
      )
    )
    head(select(cycle3_htn_data, clinicid, htn_status, htn_adj_status))

      clinicid htn_status htn_adj_status
    1        1          1              1
    2        2          1              1
    3        3          1              1
    4        4          1              1
    5        5          1              1
    6        6          1              1

## 4. Advanced: using individual classification functions

The `is_*` functions underlie the wrapper functions and are available directly for custom workflows – for example, deriving a single drug class without the full pipeline, or integrating classification logic into your own aggregation steps.

Each function accepts an ATC code and a time-last-taken value and returns `1`, `0`, or a `tagged_na()` code:

    # Single medication classification
    is_beta_blocker("C07AA05", 1) # returns 1

    [1] 1

    is_ace_inhibitor("C09AA02", 1) # returns 1

    [1] 1

    is_diabetes_med("A10BA02", 1) # returns 1

    [1] 1

### Cycle format differences

Cycles 1–2 – one row per respondent with up to 80 `atc_*/mhr_*` column pairs. The `is_*_med_cycles1to2()` variants accept named arguments for each slot:

    # Classification using cycles 1--2 wide-format columns
    is_ace_med_cycles1to2(atc_101a = "C09AA02", mhr_101b = 1) # returns 1

    [1] 1

    is_ace_med_cycles1to2(atc_101a = "C09AA02", mhr_101b = 6) # returns 0 (not taken recently)

    [1] 0

Cycles 3–6 – one row per medication per respondent with two columns: `meucatc` (ATC code) and `npi_25b` (time last taken). Classify per row, then aggregate across rows per respondent:

    cycle3_meds |>
      mutate(ace_med = is_ace_inhibitor(meucatc, npi_25b)) |>
      aggregate_meds_by_person(variables = "ace_med")

    # A tibble: 50 × 2
       clinicid ace_med
          <int>   <dbl>
     1        1       1
     2        2       1
     3        3       1
     4        4       1
     5        5       1
     6        6       1
     7        7       1
     8        8       1
     9        9       1
    10       10       1
    # ℹ 40 more rows

> Warning

> Avoid using `as.numeric(as.character(.x))` to aggregate medication columns. That pattern strips `tagged_na("a")` (valid skip) and `tagged_na("b")` (missing/refused) distinctions, collapsing them into plain `NA`. Use `aggregate_meds_by_person()` instead – it preserves tagged-NA semantics across the aggregation.

## Next steps

- Full analysis example – See how medication recoding fits into an end-to-end workflow in Analysis walkthrough.
- Understand missing data – Learn how `tagged_na("a")` and `tagged_na("b")` are preserved through the medication pipeline in Missing data (tagged_na).
- Inspect the metadata – See how medication variables are defined in `variable-details.csv` in Variable schema reference.
- Work at an RDC – For loading real CHMS medication data at a Research Data Centre, see Using chmsflow at an RDC.