Add 2026-08-28 MHT exposure variables to a person-week skeleton

Derives menopausal hormone therapy (MHT) exposure from Swedish prescription registry (LMED) data, with the 2026-08-28 definitions. The function writes its output columns into `skeleton` by reference, and returns `skeleton` invisibly.

Usage

add_lmed_v20260828(
  skeleton,
  lmed,
  id_name = "lopnr",
  create_rd = TRUE,
  verbose = TRUE
)

Arguments

skeleton: A `data.table` person-week skeleton with an `id` column and a character `isoyearweek` column. Modified by reference. Weekly rows only. Where the skeleton comes from `swereg::create_skeleton()`, pass `skeleton[is_isoyear == FALSE]`. See Details.
lmed: A `data.table` of dispensed prescriptions. The function reads `produkt`, `edatum`, `fddd`, the identifier column `id_name` names, and `lnmn` where a strength-keyed codebook rule needs it. `lmed` is not modified.
id_name: The name of the person identifier column of `lmed`. The function matches its values against `skeleton$id`.
create_rd: Logical. If `FALSE`, the function writes no `rd_approach*` column, and removes every one that `skeleton` already carries. The eight columns cost about 570 MB per batch of 10,000 people.
verbose: Logical. If `TRUE` (the default), report progress with `message()`.

Value

`skeleton`, invisibly. That is the caller's own object.

Details

The function owns these columns of `skeleton`, and changes no other:

one logical column per MHT product category
`approach1`, `approach2` and `approach3`
every column whose name starts with `rd_approach`

The third group holds eight columns. They are `rd_approach1_single` and `rd_approach1_multiple`, and the same pair for `approach2`, `approach3` and `approach3b`.

`skeleton` keeps the row order the caller passed in. The layer sorts a private table by `id` and `isoyearweek`, and it sorts nothing the caller holds.

Two conditions on `skeleton` are errors, and the function reports either one before it writes any column:

a person who holds one ISO week twice, or who has a gap between the first week and the last
an `isoyearweek` value that is no ISO week of the form `"YYYY-WW"`, which is the form `cstime::date_to_isoyearweek_c()` writes

**`skeleton` MUST hold weekly rows only.** Each person MUST hold each of its ISO weeks once, consecutively, with no gap. A skeleton from `swereg::create_skeleton()` also carries one annual row per person per year, with `isoyearweek` such as `"1946-**"` and `is_isoyear` set to `TRUE`. An annual row is no ISO week. The function then stops with the error `skeleton$isoyearweek holds a value that is no ISO week: 1946-**`. Pass `skeleton[is_isoyear == FALSE]`, and fill the annual rows in the caller. That subset is a new `data.table`. The function writes its columns there, and the table the caller holds gets none of them.

A second call recomputes every output column from the product categories up. It gives the table the first call gives.

Examples

library(data.table)

skeleton <- copy(fake_skeleton_mht)
lmed <- copy(fake_lmed_2026)

# Utrogestan takes a codebook rule keyed on strength, so it needs `lnmn`.
lmed[, lnmn := NA_character_]
#>      lopnr     produkt     edatum  fddd   lnmn
#>      <int>      <char>     <Date> <num> <char>
#>   1:     1     Divigel 2015-01-05    90   <NA>
#>   2:     1     Divigel 2015-03-30    90   <NA>
#>   3:     1     Divigel 2015-06-22    90   <NA>
#>   4:     1     Divigel 2015-09-14    90   <NA>
#>   5:     1     Divigel 2015-12-07    90   <NA>
#>  ---                                          
#> 124:    16     Divigel 2016-02-26    90   <NA>
#> 125:    16   Cerazette 2016-03-01    90   <NA>
#> 126:    17     Divigel 2015-01-07   -30   <NA>
#> 127:    17     Divigel 2015-03-31    90   <NA>
#> 128:    18 Paracetamol 2015-01-02    28   <NA>
lmed[produkt == "Utrogestan", lnmn := "Utrogestan, kapsel, mjuk 100 mg"]
#> Index: <produkt>
#>      lopnr     produkt     edatum  fddd   lnmn
#>      <int>      <char>     <Date> <num> <char>
#>   1:     1     Divigel 2015-01-05    90   <NA>
#>   2:     1     Divigel 2015-03-30    90   <NA>
#>   3:     1     Divigel 2015-06-22    90   <NA>
#>   4:     1     Divigel 2015-09-14    90   <NA>
#>   5:     1     Divigel 2015-12-07    90   <NA>
#>  ---                                          
#> 124:    16     Divigel 2016-02-26    90   <NA>
#> 125:    16   Cerazette 2016-03-01    90   <NA>
#> 126:    17     Divigel 2015-01-07   -30   <NA>
#> 127:    17     Divigel 2015-03-31    90   <NA>
#> 128:    18 Paracetamol 2015-01-02    28   <NA>

# the fixture holds one negative-duration row, which warns
skeleton <- suppressWarnings(
  add_lmed_v20260828(skeleton, lmed, verbose = FALSE)
)
skeleton[, .N, keyby = .(rd_approach1_single)]
#> Key: <rd_approach1_single>
#>    rd_approach1_single     N
#>                 <char> <int>
#> 1:             exclude  2727
#> 2:   local_or_none_mht  2027
#> 3:            previous   140
#> 4:        systemic_mht   717
#> 5:            tibolone     5