8 Flags – The yspec Book

Flags are named groups of columns which can be used to slice or filter the yspec object.

8.1 Specification

Flags get listed in the SETUP__ block, usually at the top of the yaml file. Under the flags header, we have two named groups of columns

covariate: including WT and ALB
tran: including AMT and CMT
other: including IMPUTED and STATUS

# inline/test.yml
 
SETUP__:
  flags: 
    covariate: [WT, ALB]
    tran: [AMT, CMT]
    other: [IMPUTED, STATUS]
WT: 
  short: weight
ALB: 
  short: albumin
AMT: 
  short: dose amount
CMT: 
  short: compartment number
IMPUTED:
  short: inputation flag
  values: [0,1]
  decode: [not imputed, imputed]
STATUS: 
  short: current status
  values: [100, 0]
  decode: ["yep", "nope"]

8.2 Checking flags (v0.7.0 and later)

On reading in this yaml file

spec <- ys_load("inline/test.yml")
spec

 name    info unit short              source
 WT      ---  .    weight             .     
 ALB     ---  .    albumin            .     
 AMT     ---  .    dose amount        .     
 CMT     ---  .    compartment number .     
 IMPUTED -d-  .    inputation flag    .     
 STATUS  -d-  .    current status     .

we can see the available flags in the yspec object meta data

ys_flags(spec)

$covariate
[1] "WT"  "ALB"

$tran
[1] "AMT" "CMT"

$other
[1] "IMPUTED" "STATUS"

The flags object is a named list of character vectors. You can pick a single flag by passing the flag name as an unquoted string

ys_flags(spec, tran)

$tran
[1] "AMT" "CMT"

To extract a character vector of flagged column names from the flag names

ys_flags_chr(spec, tran, other)

[1] "AMT"     "CMT"     "IMPUTED" "STATUS"

8.3 Checking flags (prior to v0.7.0)

You can pull meta data from the spec (including flags) using

pull_meta(spec, "flags")

$covariate
[1] "WT"  "ALB"

$tran
[1] "AMT" "CMT"

$other
[1] "IMPUTED" "STATUS"

8.4 Other operations

8.4.1 Select

This functionality is available in yspec v0.7.0 and later.

The spec can be subset with

ys_select_fl(spec, tran)

 name info unit short              source
 AMT  ---  .    dose amount        .     
 CMT  ---  .    compartment number .

This can be useful when creating col-labels for use in pmplots.

ys_select_fl(spec, covariate) %>% axis_col_labs()

            WT            ALB 
  "WT//weight" "ALB//albumin"

8.4.2 Factors

This functionality is available in yspec v0.7.0 and later.

You can add factors to a data frame based on the flag name

set.seed(1234)
data <- data.frame(
  IMPUTED = rbinom(5, 1, 0.5), 
  STATUS = 100*rbinom(5, 1, 0.5)
)
ys_factors_fl(data, spec, other)

      IMPUTED STATUS IMPUTED_v STATUS_v
1 not imputed    yep         0      100
2     imputed   nope         1        0
3     imputed   nope         1        0
4     imputed    yep         1      100
5     imputed    yep         1      100

Note that ys_factors_fl() takes the name of a flag that corresponds to one or more data columns whereas ys_factors() asks for the name of the data column itself.

8.4.3 Filter

When a column is identified under a flag, there is a logical indicator set in the dots field for that column. For example

spec$AMT$dots

$covariate
[1] FALSE

$tran
[1] TRUE

$other
[1] FALSE

Notice that tran is TRUE while covariate is FALSE. Because we set flags, every column in the yspec object will have data, either TRUE or FALSE on these flags. Checking C

spec$C$dots

NULL

8.5 Filtering on a flag

This means that I can ask for the columns under the tran flag with

ys_filter(spec, tran)

 name info unit short              source
 AMT  ---  .    dose amount        .     
 CMT  ---  .    compartment number .

and I can ask for the covariate columns with

ys_filter(spec, covariate) %>% axis_col_labs()

            WT            ALB 
  "WT//weight" "ALB//albumin"