Project object and define document

2024-05-22

Source: vignettes/project.Rmd

Introduction

This vignette shows you how to gather the specifications for all of your analysis project data sets, assemble into a single object, and use that object to render a project-wide define document.

Set up

Load specification objects for all data sets

If my project had 3 analysis data sets, one for PK, one for PKPD, and one for AEs, we create a specification object for each one. Here, we’re using load_spec_ex() because we’re using example material from the package. You should use ys_load() for your project and give the full path to the yaml specification file.

sp1 <- load_spec_ex("DEM104101F_PK.yml")
sp2 <- load_spec_ex("DEM104101F_PKPD.yml")
sp3 <- load_spec_ex("DEM104101F_AE.yml")

Each object looks something like

sp1
##  name    info unit short   source       
##  C       cd-  .    C       .            
##  USUBJID c--  .    USUBJID .            
##  ID      c--  .    ID      .            
##  EVID    ---  .    EVID    .            
##  WT      ---  .    WT      .            
##  STUDYID -d-  .    STUDYID .            
##  SEX     -d-  .    SEX     .            
##  EGFR2   ---  .    EGFR2   _yspec_lookup

This includes our usual information about the columns in the data set.

Create a project object

We take these specification objects and create a project object from them.

proj <- ys_project(sp1,sp2,sp3)

proj
## projectnumber:  ABC101104F 
## sponsor:        ABC-Pharma 
## --------------------------------------------
## datafiles: 
##  name            description                       data_stem       
##  DEM104101F_PK   Population PK analysis data set   DEM104101F_PK   
##  DEM104101F_PKPD Population PKPD analysis data set DEM104101F_PKPD 
##  DEM104101F_AE   AE analysis data set              DEM0104101F_AE_2

Now, for each specification object, we have a data / specification name as well as a description (along with some other information).

This file is by default saved to a temporary location. But you can also save it locally and keep it as a part of the project.

# Generated by yspec::as_proj_spec; do not edit by hand
YPROJ__:
  sponsor: ABC-Pharma
  projectnumber: ABC101104F
  spec_file: /var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T//RtmpSLTrPd/file60fe114535f5.yml
  spec_path: /var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T//RtmpSLTrPd
  path: /var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T//RtmpSLTrPd
  class: yproj
DEM104101F_PK:
  name: DEM104101F_PK
  description: Population PK analysis data set
  spec_path: /private/var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T/Rtmp7lFAoU/temp_libpath5f2935e7abd0/yspec/spec
  spec_file: /private/var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T/Rtmp7lFAoU/temp_libpath5f2935e7abd0/yspec/spec/DEM104101F_PK.yml
  data_path: ../data/derived
  data_stem: DEM104101F_PK
  csv_file: ../data/derived/DEM104101F_PK.csv
  xpt_file: ../data/derived/DEM104101F_PK.xpt
DEM104101F_PKPD:
  name: DEM104101F_PKPD
  description: Population PKPD analysis data set
  spec_path: /private/var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T/Rtmp7lFAoU/temp_libpath5f2935e7abd0/yspec/spec
  spec_file: /private/var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T/Rtmp7lFAoU/temp_libpath5f2935e7abd0/yspec/spec/DEM104101F_PKPD.yml
  data_path: ../data/derived
  data_stem: DEM104101F_PKPD
  csv_file: ../data/derived/DEM104101F_PKPD.csv
  xpt_file: ../data/derived/DEM104101F_PKPD.xpt
DEM104101F_AE:
  name: DEM104101F_AE
  description: AE analysis data set
  spec_path: /private/var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T/Rtmp7lFAoU/temp_libpath5f2935e7abd0/yspec/spec
  spec_file: /private/var/folders/zv/v6tkdhrn1_bb1ndrc0c0j31w0000gp/T/Rtmp7lFAoU/temp_libpath5f2935e7abd0/yspec/spec/DEM104101F_AE.yml
  data_path: ../data/derived
  data_stem: DEM0104101F_AE_2
  csv_file: ../data/derived/DEM0104101F_AE_2.csv
  xpt_file: ../data/derived/DEM0104101F_AE_2.xpt

To do this, we tucked some additional information into the data set specification file. For example, the specification file for the first spec object (sp1) looks like this:

SETUP__:
  lookup_file: [_yspec_lookup.yml, _yspec_lookup_2.yml]
  description: Population PK analysis data set
  data_path: ../data/derived
  sponsor: ABC-Pharma
  projectnumber: ABC101104F
C:
  long: commented rows
  values: [".",C]
  decode: [not a comment, comment]
  type: character
USUBJID:
  long: universal subject identifier
  type: character
ID:
  long: NONMEM ID number
  type: character
EVID:
  long: event ID indicator
  comment: per NONMEM specifications
  type: numeric
WT:
  range: [2,4]
  type: numeric
STUDYID: 
  values: !decode:value
    MRG101: 101
    MRG201: 201
    MRG301: 301
SEX: 
  values: !value:decode
    1 : male
    2 : female
EGFR2: 
  lookup: true

In the SETUP__ block, we included a description; this is required to make a project object from data objects. There also is a name that defaults to the stem of the data specification file. We also optionally included projectnumber and sponsor. These will get inserted into the define document when the MetrumRG Rmarkdown template is used.

Render a define file

Now, we have an object with the project information put together. The essential contents of that object have been written to a project spec file and can be used to template the creation of a project data specification file.

ys_document(proj, stem = "define_doc")