R: Generate covariates for drug-exposure follow-up from drug...

gen.exp {Epi} | R Documentation

## Generate covariates for drug-exposure follow-up from drug purchase records.

### Description

From records of drug purchase and possibly known treatment intensity, the time since first drug use and cumulative dose at prespecified times is computed. Optionally, lagged exposures are computed too, i.e. cumulative exposure a prespecified time ago.

### Usage

    gen.exp( purchase, id="id", dop="dop", amt="amt", dpt="dpt",
                   fu, doe="doe", dox="dox",
               breaks,
              use.dpt = ( dpt %in% names(purchase) ),
             push.max = Inf,
              rm.dose = FALSE,
                 lags = NULL,
              lag.dec = 1,
              lag.pre = "lag.",
             pred.win = Inf )

### Arguments

`purchase` | Data frame with columns `id`-person id, `dop` - `d`ate `o`f `p`urchase, `amt` - `am`oun`t` purchased, and optionally `dpt` - (`d`ose `p`er `t`ime) ("defined daily dose", DDD, that is), how much is assumed to be ingested per unit time. The units used for `dpt` is assumed to be units of `amt` per units of `dop`.
`id` | Character. Name of the id variable in the data frame.
`dop` | Character. Name of the `d`ate `o`f `p`urchase variable in the data frame.
`amt` | Character. Name of the `am`oun`t` purchased variable in the data frame.
`dpt` | Character. Name of the `d`ose-`p`er-`t`ime variable in the data frame.
`fu` | Data frame with `f`ollow-`u`p period for each person, the person id variable must have the same name as in the `purchase` data frame.
`doe` | Character. Name of the `d`ate `o`f `e`ntry variable.
`dox` | Character. Name of the `d`ate `o`f e`x`it variable.
`breaks` | Numerical vector of dates at which the time since first exposure, cumulative dose etc. are computed.
`use.dpt` | Logical: should we use information on dose per time.
`push.max` | Numerical. How much can purchases maximally be pushed forward in time. See details.
`rm.dose` | Logical. Should the dose from omitted period of exposure (due to the setting of `push.max`) be ignored. If `FALSE`, the cumulative dose will be the cumulation of the actually purchased amounts, regardless of how far the inception dates have been pushed.
`lags` | Numerical vector of lag-times used in computing lagged cumulative doses.
`lag.dec` | How many decimals to use in the construction of names for the lagged exposure variables
`lag.pre` | Character string used for prefixing names of lagged exposure variables. Aimed to facilitate the use of `gen.exp` for different drugs with the aim of merging information.
`pred.win` | The length of the window used for constructing the average dose per time used to compute the duration of the last purchase. Only used when `use.dpt=FALSE`. The default value `Inf` corresponds to using the time between first and last purchase of drug as the interval for computing average consumption per time, and thus the termination of use.

### Details

The intention of this function is to generate covariates for a particular drug for the entire follow-up of each person. The reason that the follow-up prior to first drug purchase and post-exposure is included is that the covariates must be defined for all follow-up for each person in order to be useful for analysis of disease outcomes.

The functionality is described in terms of calendar time as underlying time scale, because this will normally be the time scale for drug purchases and for entry and exit for persons. In principle the variables termed as dates might equally well refer to say the age scale, but this would then have to be true both for the purchase data, the follow-up data and the `breaks` argument.

Drug purchase records (in `purchase`) are used to construct measures of drug exposure at prespecified timepoints (in `breaks`) in follow-up intervals (in `fu`). Each person may have more than one follow-up interval. They should be disjoint, but this is not checked.

If `use.dpt` is `TRUE` then the dose per time information is used to compute the exposure interval associated with each purchase. Exposure intervals are stacked, that is each interval is put after any previous. This means that the start of exposure to a given purchase can be pushed into the future. The parameter `push.max` indicates the maximally tolerated push. If this is reached by a person, the assumption is that some of the purchased drug may not be counted in the exposure calculations — see `rm.dose`.

The `dpt` can either be a constant, basically translating each purchased amount into exposure time the same way for all persons, or it can be a vector with different treatment intensities for each purchase. In any case the cumulative dose is computed taking `dpt` into account, unless `rm.dose` is `FALSE` in which case the actual purchased amount is cumulated. The latter is slightly counter-intuitive because we are using the `dpt` to push the intervals, and then disregard it when computing the cumulative dose. The counter argument is that if the limit `push.max` is reached, the actual dosage may be larger than indicated the `dpt`, and is essentially what this allows for.

If `use.dpt` is `FALSE` then the exposure from one purchase is assumed to stretch over the time to the next purchase, so we are effectively allowing different dosing rates (dose per time) between purchases. Formally this approach conditions on the future, because the rate of consumption (the accumulation of cumulative exposure) is computed based on knowledge of when next purchase is made. Moreover, with this approach, periods of non-exposure does not exist, except after the last purchase where the future consumption rate is taken to be the average over the period of use (or a period of length `pred.win`), and hence defines a date of cessation of drug.

Finally, if `use.dpt` is `FALSE`, at least two purchase records are required to compute the measures. Therefore persons with only one drug purchase record are ignored in calculations.

### Value

A data frame with one record per person and follow-up date (`breaks`). Date of entry and date of exit are included too; but only follow-up in the intersetion of `range(breaks)` and `range(fu$doe,fu$dox)` is output.

`id`

  person id.

`dof`

  date of follow up, i.e. start of interval. Apart from possibly the first interval for each person, this will assume values in the set of the values in `breaks`. All other variables refer to status as of this date.

`dur`

  the length (`dur`ation) of interval.

`tfi`

  `t`ime `f`rom first `i`nitiation of drug.

`off`

  Logical, indicating whether the person is `off` drug. So it is `FALSE` if the person is exposed at `dof`.

`doff`

  `d`ate of latest transition to `off` drug. Note that tis defined also at dates after drug exposure has been resumed.

`tfc`

  `t`ime `f`rom latest `c`essation of drug.

`ctim`

  `c`umulative `tim`e on the drug.

`cdos`

  `c`umulative `dos`e.

`ldos`

  suffixed with one value per element in `lags`, the latter giving the cumulative doses `lags` before `dof`.

### Author(s)

Bendix Carstensen, b@bxc.dk. The development of this function was supported partly through a grant from the EFSD (European Foundation for the Study of Diabetes)

### See Also

`Lexis`, `cutLexis`, `mcutLexis`, `addCov.Lexis`

### Examples

    # Example data for drug purchases in 3 persons --- dates (dop) are
    # measured in years, amount purchased (amt) in no. pills and dose per
    # time (dpt) consequently given in units of pills/year. Note we also
    # include a person (id=4) with one purchase record only.
    n <- c( 10, 18, 8, 1 )
    hole <- rep(0,n[2])
    hole[10] <- 2 # to create a hole of 2 years in purchase dates
    # dates of drug purchase
    dop <- c( 1995.278+cumsum(sample(1:4/10,n[1],replace=TRUE)),
              1992.351+cumsum(sample(1:4/10,n[2],replace=TRUE)+hole),
              1997.320+cumsum(sample(1:4/10,n[3],replace=TRUE)),
              1996.470 )
    # purchased amounts mesured in no. pills
    amt <- sample( 1:3*50 , sum(n), replace=TRUE )
    # prescribed dosage therefore necessarily as pills per year
    dpt <- sample( 4:1*365, sum(n), replace=TRUE )
    # collect to purchase data frame
    dfr <- data.frame( id = rep(1:4,n),
                      dop,
                      amt = amt,
                      dpt = dpt )
    head( dfr, 3 )

    # a simple dataframe for follow-up periods for these 4 persons
    fu <- data.frame( id = 1:4,
                     doe = c(1995,1992,1996,1997)+1:4/4,
                     dox = c(2001,2003,2002,2010)+1:4/5 )
    fu

    # Note that the following use of gen.exp relies on the fact that the
    # purchase dataframe dfr has variable names "id", "dop", "amt" and
    # "dpt"" and the follow-up data frame fu has variable names "id",
    # "doe" and "dox"

    # 1: using the dosage information
    dposx <- gen.exp( dfr,
                       fu = fu,
                  use.dpt = TRUE,
                   breaks = seq(1990,2015,0.5),
                     lags = 2:4/4,
                  lag.pre = "l_" )
    format( dposx, digits=5 )

    # 2: ignoring the dosage information,
    #    hence person 4 with only one purchase is omitted
    xposx <- gen.exp( dfr,
                       fu = fu,
                  use.dpt = FALSE,
                   breaks = seq(1990,2015,0.5),
                     lags = 2:3/5 )
    format( xposx, digits=5 )

    # It is possible to have disjoint follow-up periods for the same person:
    fu <- fu[c(1,2,2,3),]
    fu$dox[2] <- 1996.2
    fu$doe[3] <- 1998.3
    fu

    # Note that drug purchase information for the period not at risk *is* used
    dposx <- gen.exp( dfr,
                       fu = fu,
                  use.dpt = TRUE,
                   breaks = seq(1990,2015,0.1),
                     lags = 2:4/4 )
    format( dposx, digits=5 )

[Package Epi version 2.42 Index]