The intended use is to subset based on variables define in the dots list, however some internal column data is also available to query.

ys_filter(x, expr, .default = NULL, .enclos = parent.frame())

Arguments

x

A yspec object.

expr

An unquoted expression.

.default

A named list or environment containing defaults for expr; consider using ys_fill_dots() as an alternative to passing .default.

.enclos

An enclosing environment for evaluating expr.

Value

A yspec object

Details

The following fields always exist in the spec and are available for querying in the filter expression:

  • col: column name <character>

  • type: data type <character>; either numeric, character, or integer

  • discrete: discrete data flag <logical>; yspec sets this to TRUE when the values field is populated

  • continuous: continuous data flag <logical>; yspec sets this to TRUE when the range field is populated

  • short: the short name <character>

  • do_lookup: lookup indicator; yspec sets this to TRUE when some or all of the column data is defined by an external lookup file

The following fields will be provided defaults when the filter expression is evaluated:

  • unit: as specified by the user <character>; default value is ""

  • covariate: as specified by the user in dots <logical>; default value is FALSE

In addition to these fields, you can build the filter expression using items in the dots field.

Evaluation environment

In order to determine if any column should get selected, ys_filter(), builds an environment and evaluates expr in that environment. Columns are selected only if expr evaluates to TRUE (via isTRUE()).

The environment is comprised of pre-existing data items in the spec (e.g. col or short; these items are always present), data items in the enclosing environment (.enclos; this defaults to parent.frame()), the .defaults list (passed by the user at run time) and the .dots list associated with each column.

Users are encouraged to filter based on logical data items in dots that are set through the flags field in SETUP__. When flags are set, every column is given a logical data item that can always be evaluated for every column. This is the safest and simplest way to go and should be the target usage. In case more complicated applications are required, users can appeal to data items in dots which may or may not be logical. Of course, the user can enter data into dots for every column to ensure that data item is available for evaluating expr but that might not be very convenient. In that case, pass a list of .defaults that will be used when the filter variable isn't available in dots. As an alternative to using .defaults, the user can run the spec object through ys_dots_fill which will fill in dots data items with default values only when they don't exist. This is probably more convenient, but the user is warned that these data items in dots stay with the yspec object for the life of the object.

Examples

spec <- ys_help$spec()

ys_filter(spec, is.character(decode))
#>  name  info unit         short                         source       
#>  C     cd-  .            comment character             ysdb_internal
#>  NUM   ---  .            record number                 ysdb_internal
#>  ID    ---  .            subject identifier            ysdb_internal
#>  SUBJ  c--  .            subject identifier            ysdb_internal
#>  TIME  ---  hour         TIME                          look         
#>  SEQ   -d-  .            SEQ                           .            
#>  CMT   ---  .            compartment number            ysdb_internal
#>  EVID  -d-  .            event ID                      ysdb_internal
#>  AMT   ---  mg           dose amount                   ysdb_internal
#>  DV    ---  micrograms/L dependent variable            ysdb_internal
#>  AGE   ---  years        age                           ysdb_internal
#>  WT    ---  kg           weight                        ysdb_internal
#>  CRCL  ---  ml/min       CRCL                          .            
#>  ALB   ---  g/dL         albumin                       ysdb_internal
#>  BMI   ---  m2/kg        BMI                           ysdb_internal
#>  AAG   ---  mg/dL        alpha-1-acid glycoprotein     .            
#>  SCR   ---  mg/dL        serum creatinine              .            
#>  AST   ---  .            aspartate aminotransferase    .            
#>  ALT   ---  .            alanine aminotransferase      .            
#>  HT    ---  cm           height                        ysdb_internal
#>  CP    -d-  .            Child-Pugh score              look         
#>  TAFD  ---  hours        time after first dose         .            
#>  TAD   ---  hours        time after dose               .            
#>  LDOS  ---  mg           last dose amount              .            
#>  MDV   -d-  .            MDV                           ysdb_internal
#>  BLQ   -d-  .            below limit of quantification .            
#>  PHASE ---  .            study phase indicator         .            
#>  STUDY -d-  .            study number                  .            
#>  RF    cd-  .            renal function stage          .            

ys_filter(spec, unit == "kg" | type == "character")
#>  name info unit short                source       
#>  C    cd-  .    comment character    ysdb_internal
#>  SUBJ c--  .    subject identifier   ysdb_internal
#>  WT   ---  kg   weight               ysdb_internal
#>  RF   cd-  .    renal function stage .            

ys_filter(spec, covariate)
#>  name info unit   short                      source       
#>  AGE  ---  years  age                        ysdb_internal
#>  WT   ---  kg     weight                     ysdb_internal
#>  CRCL ---  ml/min CRCL                       .            
#>  ALB  ---  g/dL   albumin                    ysdb_internal
#>  BMI  ---  m2/kg  BMI                        ysdb_internal
#>  AAG  ---  mg/dL  alpha-1-acid glycoprotein  .            
#>  SCR  ---  mg/dL  serum creatinine           .            
#>  AST  ---  .      aspartate aminotransferase .            
#>  ALT  ---  .      alanine aminotransferase   .            
#>  HT   ---  cm     height                     ysdb_internal
#>  CP   -d-  .      Child-Pugh score           look