Metadata Requirements

As noted in Supported Standards, a standard consists of properties, messages, and metadata files that collectively represent the standard in the SAS Clinical Standards Toolkit. Each SAS Clinical Standards Toolkit registered standard can support validation if the standards.supportsvalidation flag is set to Y. This setting indicates that the required set of validation files defining the standard exist. By default, the set of validation files that supports the standards that are supplied by SAS is in the cstGlobalLibrary folder hierarchy.

For example, validation files that define the CDISC SDTM 3.1.1 standard are in this folder hierarchy:

The following sections describe each type of file that defines metadata. The file type is either entirely unique to a SAS Clinical Standards Toolkit validation process, it has validation-specific elements. For information about metadata files that are common to all SAS Clinical Standards Toolkit processes, see Metadata File Descriptions.

For CDISC standards, reference metadata refers to metadata about data sets. Reference metadata is defined in a reference_tables data set, and metadata about columns is defined in a reference_columns data set. An example of a reference_tables record is provided in Sample Reference_Tables Record (CDISC SDTM 3.1.2) and an example of a reference_columns record is provided in Sample Reference_Columns Record (CDISC SDTM 3.1.2). The reference metadata in these examples is required, and it serves as the gold standard specifically describing the tables and columns of CDISC SDTM. As noted in Supported Standards, each standard that is supplied by SAS provides a SAS interpretation of the published source guidelines or specification of that standard. Each standard is designed to serve as a representative model or template of the source specification. Each model or template can be modified to establish your own gold standard.

The standard reference metadata provided by SAS is in the SAS Clinical Standards Toolkit global standards library. By default, this library is here:

For example, for the CDISC SDTM 3.1.1 standard, the location is:

This global standards library metadata folder can contain other standard-specific metadata. For example, CDISC SDTM includes class_tables and class_columns data sets. These data sets have more generic metadata than specific domain instances like DM or AE, and they are most useful when deriving new, custom domains. For example, if a new CDISC SDTM events domain is required, you can initialize table metadata based on the EVENTS record in class_tables data set, and can initialize column metadata based on the EVENTS, IDENTIFIERS, and TIMING records in the class_columns data set.

The SAS Clinical Standards Toolkit validation processes require source metadata that describes source (study) domains and columns. This is the study data that is to be validated. The SAS Clinical Standards Toolkit assumes that the reference metadata (that is, reference_tables and reference_columns) for a standard serves as a model or template for the source metadata (that is, source_tables and source_columns). It is recommended that these two sets of metadata be structurally equivalent. However, additional metadata attributes might exist if they are used for other purposes or for custom extensions to the SAS Clinical Standards Toolkit.

The SAS Clinical Standards Toolkit assumes that source_tables and source_columns data sets accurately reflect and are consistent with the source data that they describe. Although some standard-specific validation checks might look for discrepancies and report them in detail, failure to accurately reflect and be consistent with the source data can lead to errors in the SAS Clinical Standards Toolkit validation process. It can even halt the execution of the process.

The Validation Master data set contains all validation checks defined for a standard. By default, this data set is deployed to this directory in each supported standard:

By default, the Validation Master SAS data set's actual name is validation_master.sas7bdat.

The SAS Clinical Standards Toolkit requires that this data set have a fixed structure.

The content of the Validation Master data set is based on a combination of compliance requirements and the SAS representation of the standard.

The Validation Master data set contains all validation checks for a standard, whereas the Validation Control data set is the run-time equivalent and contains just the validation checks to be run in a validation process. The Validation Control data set is structurally equivalent to the Validation Master data set. For additional information about how the validation check metadata in the Validation Control data set is used in the SAS Clinical Standards Toolkit validation processes, see Special Topic: How the SAS Clinical Standards Toolkit Interprets Validation Check Metadata.

The validation standard references data set contains additional information about each of the checks in the Validation Master data set. This data set is used in the validation metadata reporting process to provide additional information to you about the origin of the check. It also provides any supporting documentation about the check. By default, this data set is deployed to this directory in each supported standard:

The content of the Validation_StdRef data set is based on information from any source that supports the check.

The SAS Clinical Standards Toolkit validation metadata, as specified in the Validation Master data set, uses the tablescope and columnscope columns to define the scope of the check. The scope being what domains (tables) and what columns will be validated when the check is run. The SAS Clinical Standards Toolkit uses a shorthand syntax in these columns that is interpreted by the SAS Clinical Standards Toolkit framework macros to build a list of target tables and columns. For more information, see Special Topic: How the SAS Clinical Standards Toolkit Interprets Validation Check Metadata. The Validation_DomainsByCheck data set is supplied in <global standards library directory>/standards/<standard>/validation/control. It contains records for each domain that is to-be-validated by each check in the Validation Master data set. This data set is used by reporting tools that are provided with the SAS Clinical Standards Toolkit to report domain-specific errors. For more information, see Reporting. It is also available to other programs and applications that might need to subset checks that are applicable to specific domains.

The version of the Validation_DomainsByCheck data set that is supplied by SAS is built from the version of the Validation Master data set that is also supplied by SAS. If the tableScope and columnScope columns are modified, then the Validation_DomainsByCheck data set must also be modified or rebuilt.

For CDISC SDTM 3.1.2 validation check SDTM0207, the Validation_DomainsByCheck data set contains records for 14 domains. These 14 domains are DA, EG, FA, IE, LB, MB, MS, PC, PE, PP, QS, SV, TV, and VS. The target domains and columns for check SDTM0207 are defined as tableScope=_ALL_ and columnScope=VISITNUM. This means there are 14 domains in the sample study metadata provided for CDISC SDTM 3.1.2 that contain the column VISITNUM.

Properties specific to validation processes are provided with the SAS Clinical Standards Toolkit. These properties enable you to specify how validation checks are to be processed and whether metrics are to be reported.

As with all SAS Clinical Standards Toolkit properties files, a call to the %cst_setproperties macro is required to translate the properties into SAS global macro variables. This call can be explicitly made as a driver module setup task, or it can be made by including the Validation.Properties file as a record in the SASReferences data set. For all standards that support validation, the Validation.Properties file is required, even if no metrics are wanted because the SAS Clinical Standards Toolkit validation process does expect, and will use, the metrics global macro variables.

By default, for all standards that support validation, Validation.Properties is here:

Properties can logically be associated with each study. Using the CDISC SDTM 3.1.1 sample study provided with the SAS Clinical Standards Toolkit as an example, a study-specific instance of the Validation.Properties file is in a !sasroot subdirectory similar to /sample/cdisc-sdtm-3.1.1–1.4/sascstdemodata/programs.

Each SAS Clinical Standards Toolkit registered standard that supports validation has a Validation Master data set, and an associated Messages data set. The Validation Master data set provides the super-set of checks defined for that standard. The Messages data set provides messages to be generated during the execution of each validation process. A distinct Messages data set record is expected for each set of checkid and checksource values in the Validation Master data set. Messages can be parameterized and internationalized.

By default, the standard-specific Messages data set is deployed to this directory in each supported standard:

All Messages data sets in the SAS Clinical Standards Toolkit should have the same structure. The structure is defined in Metadata File Descriptions.

During a process, the SAS Clinical Standards Toolkit appends any standard-specific messages that are required by the process to any generic SAS Clinical Standards Toolkit framework messages that are available to all processes. This appended Messages data set follows the naming convention that is defined within the global macro variable _cstMessages.

For complete message lists supporting the SAS Clinical Standards Toolkit standards, see these appendixes:

Generating the SAS Clinical Standards Toolkit validation metrics provides a meaningful denominator for most validation checks. This enables you to more accurately assess the relative scope of errors that are detected. Generally, the calculated denominator is a count of the number of records processed in a domain.

This code segment, which is extracted from a validation check macro, shows a typical calculation of the number of records in a domain. It also shows the macro call to add the count to the Validation Metrics data set:

data _null_;
if 0 then set &_cstDSName nobs=_numobs;
call symputx('_cstMetricsCntNumRecs',_numobs);
stop;
run;
 
* Write applicable metrics *;
%if &_cstMetrics %then %do;
%if &_cstMetricsNumRecs %then
   %cstutil_writemetric(
     _cstMetricParameter=# of records tested,
     _cstResultID=&_cstCheckID,
     _cstResultSeqParm=&_cstResultSeq,
     _cstMetricCnt=&_cstMetricsCntNumRecs,
     _cstSrcDataParm=&_cstDSname
   );   
%end; 

Because a check can evaluate multiple columns in a domain, the count will be greater. In addition, a metadata-level check that does not access the domain data directly might report the number of metadata records instead.

Metrics processing is enabled based on settings in the Validation.Properties file. See Properties in the Validation.Properties File.

Lines 1 through 2 document that the SDTM0451 check was invoked twice. The missing recount value and the absence of other metrics indicate that the two check invocations failed. This should be reported in the Results data set.

Lines 3 through 7 provide metrics information about the SDTM0623 check. SDTM0623 checks that multiple standard units do not exist for any test in the findings domains. The SDTM0623 check was run on two domains using the cstcheck_notunique check macro. The number of subjects and records tested, and the elapsed time to run the check are reported.

Lines 8 through 14 are summary metrics reported at the end of the SDTM validation process in the sdtm_validate macro. There are no errors. It is noted that two checks could not be run (lines 9 and 14).