Repository files navigation

Programming for clinical trial data analysis tends to be verystandardized. With data standards such asCDISC, expectations tend to be very clearlydefined. Within these programming activities, there’s ample room for theuse of metadata. Metadata can be used for several different purposes,such as applying dataset attributes, establishing sort sequences,working with controlled terminology, and more. Despite CDISC standards,organizations tend to have their own means of storing metadata, be it inexcel spreadsheets, databases, and more.

The purpose of metacore is to establish a common foundation for the useof metadata within an R session. This is done by creating an R objectthat can hold the necessary data in a standardized, immutable structure(using R6) that makes it easy to extract out necessary information whenneeded. Users can read in their metadata from their various sources. Tomake this easy, we’ve provided some helper functions - and even havereaders that can read directly from Define.xml 2.0. By establishing acommon and consistent object in memory, further packages that supportthese work flows can have a common foundation upon which tools can bebuilt that leverage metadata in the future. This reduces the need tohold different data structures containing metadata and instead allowsprograms to pull this information from a centralized source.

You can install the current development version of metacore fromgithub with:

devtools::install_github("atorus-research/metacore")

A metacore object is made-up of 6 different tables, which are connectedwith a series of identifying columns. The goal of these tables is tonormalize the information as much as possible, while keeping togetherlike information. Each table has a basic theme to make them easier toremember. They are as follows:

• ds_spec: Contains dataset level information

• ds_vars: Bridges the dataset and variable level information

• var_spec: Contains variable level information

• value_spec: Contains value level information

• derivations: Contains all derivations

• codelist: Contains information about code/decodes, permittedvalues and external libraries

• supp: Contains information specific to supplemental variables

Here is a schema of how all this fits together:

This table covers the basic information about each dataset. There isonly a single row per dataset, with the following information:

• dataset: The abbreviated name of the dataset (e.g. AE)

• structure: Value structure of the dataset as a sting

• label: Dataset label

This table contains the information that bridges between purely datasetlevel and purely variable level. There is one row per dataset pervariable:

• dataset: The abbreviated name of the dataset. This will match to thename inds_spec

• variable: Variable name

• key_seq: Sequence key, which are the variables used to order adataset. This is a column of integers, where 1 is the first sortingvariable and 2 is the second etc. If the variable is not used insorting it will be leftNA

• order: Order sets the order of the columns to appear in the dataset.This is also a numeric value

• keep: Logical value about if the variable needs to be kept

• core: ADaM core, which should be one of the following values:“Expected”, “Required”, “Permissible”, “Conditionally Required”,“Conditionally Expected”, or NA. For more information about core seeCDISC

• supp_flag: Logical to determine if the variable is in thesupplemental datasets

This table contains the purely variable level information. The goal isthere is a single row per variable, which is common across all datasets.This helps ensure variables follow the CDISC standard. But, this isn’talways possible, so if information for a given variable differs acrossdatasets, the variable will be recorded as dataset.variable in thevariable column.

• variable: Variable name, which should match the name inds_spec.Unless the variable needs to be duplicated, then the name will be acombination of the the dataset name and variable name fromds_spec(dataset.variable)

• type: Variable class

• length: Variable length (while not relevant to R datasets, this isimportant for when creating XPT files)

• label: Variable label

• common: Common across ADaM datasets

• format: Variable format

This table contains the information the information at the value level.There will be at least one row per dataset/variable combination. Thereis more than one row per dataset/variable combination if the combinationhas values which have differing metadata. For instance LBORRES that aredifferent data types depending on the value. The information containedare as follows:

• dataset: The abbreviated name of the dataset. This will match to thename inds_spec

• variable: Variable name. This will match to the name inds_vars

• type: String of the value type

• origin: Origin of the value

• sig_dig: Significant digits of the value

• code_id: ID for the code list to match the id in thecodelisttable

• where: Value of the variable

• derivation_id: ID for the derivation to match with thederivation table

This table has all the derivation information, with one row perderivation ID and the following information:

• derivation_id: The ID, which should match tovalue_spec

• derivation: Text describing the derivation

This table contains the code lists, permitted value lists, and externallibraries nested within a tibble. There is only a single row perlist/library, with the following information:

• code_id: the ID used to identify the code list. This should be thesame as thecode_id inval_spec

• name: Name of the code list

• code: A list of tibbles (for code / decode combinations) and vectors(for permitted values and libraries), which contain all the codes

• type: An indicator of if the information in the code column is acode/decode table, permitted value, or external library

This table contains the information needed to create supplementaltables. If you want to add a variable which will go into a supplementalqualifier then you can create as normal (i.e. label information going tothevar_spec table and derivation and origin going into thevalue_spec table), but you need to flag it as supplemental in theds_vars table and add a row to thesupp table. There is only asingle row per dataset/variable, with the following information:

• dataset: The abbreviated name of the dataset. This will match to thename inds_spec

• variable: Variable name. This will match to the name inds_spec

• idvar: ID variable used for the supplemental variable. Can be leftmissing if not needed

• qeval: Evaluator for the supplemental variable

To get more information about the metacore objects and how to build aspecification reader, please see our vignettes.

This is an alpha release of this package, so if you have ideas on futureimprovements please add them to the issue log.