| Title: | Creates Define XML Documents |
|---|---|
| Description: | Creates 'define.xml' documents used for regulatory submissions based on spreadsheet metadata. Can also help create metadata and generate HTML data explorer. |
| Authors: | David Bosak [aut, cre], Aheer Alvi [aut], Jonathan Stallings [ctb] |
| Maintainer: | David Bosak <[email protected]> |
| License: | CC0 |
| Version: | 0.0.5 |
| Built: | 2025-02-02 04:11:36 UTC |
| Source: | https://github.com/dbosak01/definer |
The write_define function inputs an SDTM or ADAM
metadata file and outputs a define.xml and associated files to a specified
directory. Possible associated files are the HTML transformation of
the define.xml and a check report. By default, the check report will
also be shown in the viewer.
write_define( path, dir, type = "sdtm", ver = NULL, check = TRUE, html = TRUE, view = TRUE, report_type = "PDF", end_char = "" )write_define( path, dir, type = "sdtm", ver = NULL, check = TRUE, html = TRUE, view = TRUE, report_type = "PDF", end_char = "" )
path |
The path to the metadata file. Currently only Excel metadata files are supported. Other metadata sources may be added if there is sufficient interest. |
dir |
The output directory to create the define.xml and associated files. If the directory does not exist, the function will attempt to create it. |
type |
The type of define.xml to create. Valid values are "sdtm" and "adam". Default is "sdtm". |
ver |
The version of the define XML to produce. Currently only version "2.0.0" is supported. |
check |
Whether or not to perform consistency checks. If so, a check report will be produced in the output directory. Valid values are TRUE and FALSE. Default is TRUE. |
html |
Whether or not to produce the HTML output associated with the define.xml. Valid values are TRUE and FALSE. Default is TRUE. |
view |
Whether or not to show the check report in the viewer. Valid values are TRUE and FALSE. Default is TRUE. |
report_type |
The output type of the check report, if requested. Valid values are "TXT", "RTF", "PDF", "HTML" and "DOCX". Default is "PDF". |
end_char |
The end character to use on computational method blocks. These blocks often contain code samples that include line feeds or other line ending characters. This parameter can be used to control how these characters are emitted to the XML parser. Default is an empty string (""). If the line feeds in your computational methods are not working, trying using a return ("\r") or new line ("\n"). |
The define.xml document is used by the FDA (and others) to review study data. All datasets used in the study are listed, along with variable and value metadata, where clauses, and more. The define.xml can be used along with an XSLT style sheet to transform the XML into an HTML report. This HTML report has links that allow you to easily navigate the data structures.
The write_define function
creates both the define XML and the define HTML. The path
parameter identifies the location of the Excel metadata, and the
dir parameter specifies an output directory. You can create
both SDTM and ADAM metadata by passing the appropriate value on the
type parameter.
Importantly, the function also produces a check report. This report will compare the define.xml file against the XSD schema supplied by CDISC. Any discrepancies will be written to the check report. By default, the check report is also shown in the viewer, and returned as a vector of strings by the function. This discrepancy list allows you to verify that the metadata has been filled out correctly.
For instance, the conformance check will ensure that each object ID (OID) is unique within the document. Any non-unique IDs will be identified and written to the check report. The check report may therefore be used iteratively to fix the metadata.
Any errors that prevent proper functioning of the procedure will stop execution, and be displayed in the console. All other errors and warnings will be sent to the check report, and will not stop execution.
Note that the check parameter can be used to turn off the
conformance check mechanism, and just create the XML.
The XSD schema and XSLT transformation documents were created by CDISC,
and are included in the defineR package for convenience. To
specify another version of the documents, use the options "defineR.xsd"
and "defineR.xslt". For example:
options("defineR.xsd" = "c:/myproject/define2-1-0.xsd").
The define.xml file and any associated files will be written
to the directory specified on the dir parameter.
write_metadata to create a metadata template.
# Get temp directory tmp <- tempdir() # Create demo metadata pth <- write_metadata(tmp, demo = TRUE) # Generate define files res <- write_define(pth, tmp, view = FALSE) # View check results res # NULL # View XML # file.show(file.path(tmp, "define.sdtm.xml")) # View check report # file.show(file.path(tmp, "check.sdtm.pdf")) # View HTML # file.show(file.path(tmp, "define.sdtm.html"))# Get temp directory tmp <- tempdir() # Create demo metadata pth <- write_metadata(tmp, demo = TRUE) # Generate define files res <- write_define(pth, tmp, view = FALSE) # View check results res # NULL # View XML # file.show(file.path(tmp, "define.sdtm.xml")) # View check report # file.show(file.path(tmp, "check.sdtm.pdf")) # View HTML # file.show(file.path(tmp, "define.sdtm.html"))
The function generates define.xml metadata and
writes it to the file system. The function can generate a blank metadata
spreadsheet, a demonstration spreadsheet, or metadata read
from existing data files. The type parameter can be used
to request an SDTM or ADAM spreadsheet.
write_metadata( dir, type = "sdtm", ver = NULL, src_dir = NULL, check = TRUE, demo = FALSE )write_metadata( dir, type = "sdtm", ver = NULL, src_dir = NULL, check = TRUE, demo = FALSE )
dir |
The directory in which to produce the metadata. |
type |
The type of metadata file to produce. Valid values are "SDTM" and "ADAM". Default is "SDTM". |
ver |
The version of the metadata file. Default is the preferred version of the define standard. The function currently supports only version "2.0.0". |
src_dir |
If the metadata will be generated from existing datasets, supply the directory path for those datasets. If the metadata will not be created from datasets, this parameter should be NULL. Datasets should be in XPT file format. |
check |
Whether or not to run the checks. |
demo |
If this parameter is TRUE, the function will generate a metadata file populated with sample data. If the parameter is FALSE, a blank metadata spreadsheet will be produced. Default is FALSE. |
Frequently, organizations already have study metadata stored in Excel spreadsheets, and in the correct structure. This structure is used commonly in the industry by other software.
The purpose of the write_metadata function is to create an
initial metadata template for studies in which you have no metadata.
This task will ensure that you have the proper metadata structure
to later create the define.xml.
By default, the function creates an unpopulated metadata spreadsheet.
If the demo parameter is set to TRUE, the function will create
the same spreadsheet populated with sample data. This sample data
can help you to understand how to populate the metadata for your study.
Note that this demo spreadsheet is populated correctly, and has no
conformance errors. Use this demo spreadsheet as a guide to fill
out your metadata.
The demo spreadsheet is included in the defineR package for convenience.
The full path of the generated metadata file.
write_define to create a define.xml document and
associated files.
# Get temporary directory tmp <- tempdir() # Create demo spreadsheet out1 <- write_metadata(tmp, demo = TRUE) # View file # file.show(out1) # Create unpopulated spreadsheet out2 <- write_metadata(tmp, demo = FALSE) # View file # file.show(out2)# Get temporary directory tmp <- tempdir() # Create demo spreadsheet out1 <- write_metadata(tmp, demo = TRUE) # View file # file.show(out1) # Create unpopulated spreadsheet out2 <- write_metadata(tmp, demo = FALSE) # View file # file.show(out2)