10 Extensions

When you code up a data definition file (the “yaml” file), the columns that are listed in that file should exist in your analysis data set. When you add columns to the analysis data set, you might also want to add items to your data definition object as well. yspec allows you to do this; we call it an “extension”.

10.1 Extension with ad-hoc file

If this example data specification code is for my analysis data

# inline/primary1.yml
 
C: 
  short: comment
AGE: 
  short: age
ALB: 
  short: albumin

spec_main <- ys_load("inline/primary1.yml")
spec_main

 name info unit short   source
 C    ---  .    comment .     
 AGE  ---  .    age     .     
 ALB  ---  .    albumin .     

I can write a separate yaml file like this

# inline/extension1.yml
 
ELDERLY: 
  short: elderly age
  comment: age >= 60

Then use ys_extend() to append the extension to the primary data specification object.

extended <- ys_extend(spec_main, "inline/extension1.yml")
extended

 name    info unit short       source    
 C       ---  .    comment     .         
 AGE     ---  .    age         .         
 ALB     ---  .    albumin     .         
 ELDERLY --e  .    elderly age extension1

We pass in the primary data specification object as well as the path to the extension file.

10.2 Internal extension file

Extensions are always kept as an external file. But when writing your primary data specification file, you can name one file to act as the default extension.

Recoding our example, with the extend_field in the SETUP__ block

# inline/primary2.yml
 
SETUP__:
  extend_file: "extension1.yml"
C: 
  short: comment
AGE: 
  short: age
ALB: 
  short: albumin

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

Then to extend, just pass the object

spec_extended <- ys_extend(spec)
spec_extended

 name    info unit short       source    
 C       ---  .    comment     .         
 AGE     ---  .    age         .         
 ALB     ---  .    albumin     .         
 ELDERLY --e  .    elderly age extension1