doc sweep

NAMESPACE

@@ -10,7 +10,6 @@ export(set_last_modified)
 export(set_metadata_ref)
 export(set_metadata_version)
 export(set_originator)
-export(set_reference_data)
 export(set_source_system)
 export(set_study_oid)
 export(validate_dataset_json)

R/data.R

@@ -5,12 +5,11 @@
 #'
 #' @format ## `iris_items` A data frame with 5 rows and 6 columns:
 #' \describe{
-#'   \item{OID}{Unique identifier for Variable. Must correspond to ItemDef/@OID in Define-XML.}
+#'   \item{itemOID}{Unique identifier for Variable. Must correspond to ItemDef/@OID in Define-XML.}
 #'   \item{name}{Display format supports data visualization of numeric float and date values.}
 #'   \item{label}{Label for Variable}
-#'   \item{type}{Data type for Variable}
+#'   \item{dataType}{Data type for Variable}
 #'   \item{length}{Length for Variable}
-#'   \item{displayFormat}{Display format supports data visualization of numeric float and date values.}
 #'   \item{keySequence}{Indicates that this item is a key variable in the dataset structure. It also provides an ordering for the keys.}
 #' }
 "iris_items"

R/datasetjson.R

@@ -4,33 +4,69 @@
 #'
 #' @details
 #'
+#' The `columns` parameter should be provided as a dataframe based off the
+#' Dataset JSON Specification:
+#' - **itemOID**: *string, required*: Unique identifier for the variable that may also
+#' function as a foreign key to an ItemDef/@OID in an associated Define-XML
+#' file. See the [ODM
+#' specification](https://wiki.cdisc.org/display/PUB/Element+Identifiers+and+References)
+#' for OID considerations.
+#' - **name**: *string, required*: Variable name
+#' - **label**: *string, required*: Variable label
+#' - **dataType**: *string, required*: Logical data type of the variable. The dataType
+#' attribute represents the planned specificity of the data. See the [ODM Data
+#' Formats specification](https://wiki.cdisc.org/display/PUB/Data+Formats) for
+#' details.
+#' -**targetDataType**: *string, optional*: Indicates the data type into which
+#' the receiving system must transform the associated Dataset-JSON variable. The
+#' variable with the data type attribute of dataType must be converted into the
+#' targetDataType when transforming the Dataset-JSON dataset into a format for
+#' operational use (e.g., SAS dataset, R dataframe, loading into a system's data
+#' store). Only specify targetDataType when it is different from the dataType
+#' attribute or the JSON data type and the data needs to be transformed by the
+#' receiving system. See the Supported Column Data Type Combinations table for
+#' details on usage. See the User's Guide for additional information.
+#' - **length**: *integer, optional*: Specifies the number of characters
+#' allowed for the variable value when it is represented as a text.
+#' - **displayFormat**: *string, optional: A SAS display format value used for
+#' data visualization of numeric float and date values.
+#' - **keySequence**: *integer, optional*: Indicates that this item is a key
+#' variable in the dataset structure. It also provides an ordering for the keys.
+#'
 #' Note that DatasetJSON is on version 1.1.0. Based off findings from the pilot,
-#' version 1.1.0 reflects feedback from the user community. Support for 1.0.0 has
-#' been deprecated.
+#' version 1.1.0 reflects feedback from the user community. Support for 1.0.0
+#' has been deprecated.
 #'
 #' @param .data Input data to contain within the Dataset JSON file. Written to
 #'   the itemData parameter.
-#' @param sys sourceSystem parameter, defined as "The computer system or
-#'   database management system that is the source of the information in this
-#'   file."
-#' @param sys_version sourceSystemVersion, defined as "The version of the
-#'   sourceSystem"
-#' @param originator originator parameter, defined as "The organization that
-#'   generated the Dataset-JSON file."
 #' @param file_oid fileOID parameter, defined as "A unique identifier for this
-#'   file."
-#' @param study Study OID value
-#' @param metadata_version Metadata version OID value
-#' @param metadata_ref Metadata reference (i.e. path to Define.xml)
+#'   file." (optional)
+#' @param last_modified The date/time the source database was last modified
+#'   before creating the Dataset-JSON file (optional)
+#' @param originator originator parameter, defined as "The organization that
+#'   generated the Dataset-JSON file." (optional)
+#' @param sys sourceSystem.name parameter, defined as "The computer system or
+#'   database management system that is the source of the information in this
+#'   file." (Optional, required if coupled with sys_version)
+#' @param sys_version sourceSystem.Version, defined as "The version of the
+#'   sourceSystem" (Optional, required if coupled with sys)
+#' @param study Study OID value (optional)
+#' @param metadata_version Metadata version OID value (optional)
+#' @param metadata_ref Metadata reference (i.e. path to Define.xml) (optional)
 #' @param item_oid ID used to label dataset with the itemGroupData parameter.
 #'   Defined as "Object of Datasets. Key value is a unique identifier for
 #'   Dataset, corresponding to ItemGroupDef/@OID in Define-XML."
-#' @param version The DatasetJSON version to use. Currently only 1.1.0 is supported.
-#' @param columns Variable level metadata for the Dataset JSON object
+#' @param name Dataset name
+#' @param dataset_label Dataset Label
+#' @param version The DatasetJSON version to use. Currently only 1.1.0 is
+#'   supported.
+#' @param columns Variable level metadata for the Dataset JSON object. See
+#'   details for format requirements.
 #'
 #' @return dataset_json object pertaining to the specific Dataset JSON version
 #'   specific
 #' @export
+#' @md
 #'
 #' @examples
 #' # Create a basic object
@@ -51,17 +87,17 @@
 #' )
 #'
 #' # Attach attributes directly
-#' ds_json_updated <- set_file_oid(ds_json_updated, "/some/path")
-#' ds_json_updates <- set_last_modified(ds_json_updates, "2023-02-15T10:23:15")
-#' ds_json_updated <- set_metadata_ref(ds_json_updated, "some/define.xml")
-#' ds_json_updated <- set_metadata_version(ds_json_updated, "MDV.MSGv2.0.SDTMIG.3.3.SDTM.1.7")
-#' ds_json_updated <- set_originator(ds_json_updated, "Some Org")
-#' ds_json_updated <- set_source_system(ds_json_updated, "source system", "1.0")
-#' ds_json_updated <- set_study_oid(ds_json_updated, "SOMESTUDY")
-#' ds_json_updated <- set_item_oid(ds_json_updated, "IG.IRIS")
-#' ds_json_updated <- set_dataset_name(ds_json_updated, "IRIS")
-#' ds_json_updated <- set_dataset_label(ds_json_updated, "Iris")
-#' ds_json_updates <- set_columns(ds_json_updated, iris_items)
+#' ds_json <- dataset_json(iris, columns = iris_items)
+#' ds_json <- set_file_oid(ds_json, "/some/path")
+#' ds_json <- set_last_modified(ds_json, "2025-01-21T13:34:50")
+#' ds_json <- set_originator(ds_json, "Some Org")
+#' ds_json <- set_source_system(ds_json, "source system", "1.0")
+#' ds_json <- set_study_oid(ds_json, "SOMESTUDY")
+#' ds_json <- set_metadata_ref(ds_json, "some/define.xml")
+#' ds_json <- set_metadata_version(ds_json, "MDV.MSGv2.0.SDTMIG.3.3.SDTM.1.7")
+#' ds_json <- set_item_oid(ds_json, "IG.IRIS")
+#' ds_json <- set_dataset_name(ds_json, "Iris")
+#' ds_json <- set_dataset_label(ds_json, "The Iris Dataset")
 dataset_json <- function(.data, file_oid=NULL, last_modified=NULL,
                           originator=NULL, sys=NULL, sys_version = NULL,
                           study=NULL, metadata_version=NULL,metadata_ref=NULL,

R/file_metadata.R

@@ -1,7 +1,7 @@
 #' Dataset Metadata Setters
 #'
-#' Set information about the file, source system, study, and dataset used to generate the Dataset
-#' JSON object.
+#' Set information about the file, source system, study, and dataset used to
+#' generate the Dataset JSON object.
 #'
 #' @details
 #'
@@ -14,23 +14,23 @@
 #' the first file in a series for study 5894 from Best Pharmaceuticals."
 #'
 #' @param x datasetjson object
-#' @param sys sourceSystem parameter, defined as "The computer system or
-#'   database management system that is the source of the information in this
-#'   file."
-#' @param sys_version sourceSystemVersion, defined as "The version of the
-#'   sourceSystem"
-#' @param originator originator parameter, defined as "The organization that
-#'   generated the Dataset-JSON file."
 #' @param file_oid fileOID parameter, defined as "A unique identifier for this
-#'   file."
-#' @param study Study OID value
-#' @param metadata_version Metadata version OID value
-#' @param metadata_ref Metadata reference (i.e. path to Define.xml)
+#'   file." (optional)
+#' @param last_modified The date/time the source database was last modified
+#'   before creating the Dataset-JSON file (optional)
+#' @param originator originator parameter, defined as "The organization that
+#'   generated the Dataset-JSON file." (optional)
+#' @param sys sourceSystem.name parameter, defined as "The computer system or
+#'   database management system that is the source of the information in this
+#'   file." (Optional, required if coupled with sys_version)
+#' @param sys_version sourceSystem.Version, defined as "The version of the
+#'   sourceSystem" (Optional, required if coupled with sys)
+#' @param study Study OID value (optional)
+#' @param metadata_version Metadata version OID value (optional)
+#' @param metadata_ref Metadata reference (i.e. path to Define.xml) (optional)
 #' @param item_oid ID used to label dataset with the itemGroupData parameter.
 #'   Defined as "Object of Datasets. Key value is a unique identifier for
 #'   Dataset, corresponding to ItemGroupDef/@OID in Define-XML."
-#' @param ref_data Boolean value that is set to "true" when the dataset contains
-#'   reference data (not subject data). The default value is "false".
 #' @param name Dataset name
 #' @param dataset_label Dataset Label
 #'
@@ -40,16 +40,17 @@
 #' @rdname dataset_metadata_setters
 #'
 #' @examples
-#' ds_json <- dataset_json(iris)
+#' ds_json <- dataset_json(iris, columns = iris_items)
 #' ds_json <- set_file_oid(ds_json, "/some/path")
-#' ds_json <- set_study_oid(ds_json, "SOMESTUDY")
+#' ds_json <- set_last_modified(ds_json, "2025-01-21T13:34:50")
 #' ds_json <- set_originator(ds_json, "Some Org")
 #' ds_json <- set_source_system(ds_json, "source system", "1.0")
+#' ds_json <- set_study_oid(ds_json, "SOMESTUDY")
 #' ds_json <- set_metadata_ref(ds_json, "some/define.xml")
 #' ds_json <- set_metadata_version(ds_json, "MDV.MSGv2.0.SDTMIG.3.3.SDTM.1.7")
 #' ds_json <- set_item_oid(ds_json, "IG.IRIS")
-#' ds_json <- set_dataset_name(ds_json, "IRIS")
-#' ds_json <- set_dataset_label(ds_json, "Iris")
+#' ds_json <- set_dataset_name(ds_json, "Iris")
+#' ds_json <- set_dataset_label(ds_json, "The Iris Dataset")
 set_source_system <- function(x, sys, sys_version) {
   stopifnot_datasetjson(x)
   if (!is.character(sys)) {
@@ -134,6 +135,7 @@ set_item_oid <- function(x, item_oid) {
     stop("`item_oid` must be a character")
   }
   attr(x, "itemGroupOID") <- item_oid
+  x
 }
 
 #' @export
@@ -145,6 +147,7 @@ set_dataset_name <- function(x, name) {
     stop("`name` must be a character")
   }
   attr(x, 'name') <- name
+  x
 }
 
 #' @export
@@ -156,17 +159,7 @@ set_dataset_label <- function(x, dataset_label) {
     stop("`dataset_label` must be a character")
   }
   attr(x, 'label') <- dataset_label
-}
-
-#' @export
-#' @family Dataset Metadata Setters
-#' @rdname dataset_metadata_setters
-set_reference_data <- function(x, is_refdata) {
-  stopifnot_datasetjson(x)
-  if (!is.logical(is_refdata)) {
-    stop("`is_refdata` must be a boolean")
-  }
-  attr(x, 'isReferenceData') <- is_refdata
+  x
 }
 
 #' @export
@@ -178,6 +171,7 @@ set_last_modified <- function(x, last_modified) {
     stop("`last_modified` must be a character")
   }
   attr(x, 'dbLastModifiedDateTime') <- last_modified
+  x
 }
 
 #' Create an ISO8601 formatted datetime of the current time

R/read_dataset_json.R

@@ -1,13 +1,43 @@
-#' Read a Dataset JSON to datasetjson object
+#'Read a Dataset JSON to datasetjson object
 #'
-#' This function validates a dataset JSON file against the Dataset JSON schema,
-#' and if valid returns a datasetjson object. The Dataset JSON file can be
-#' either a file path on disk of a URL which contains the Dataset JSON file.
+#'This function validates a dataset JSON file against the Dataset JSON schema,
+#'and if valid returns a datasetjson object. The Dataset JSON file can be either
+#'a file path on disk of a URL which contains the Dataset JSON file.
 #'
-#' @param file File path or URL of a Dataset JSON file
+#'@details
 #'
-#' @return datasetjson object
-#' @export
+#'The resulting dataframe contains the additional metadata available on the
+#'Dataset JSON file within the attributes to make this accessible to the user.
+#'Note that these attributes are only populated if available.
+#' - **sourceSystem**: The information system from which the content of this
+#'dataset was source, including system name and version.
+#' - **datasetJSONVersion**: The version of the Dataset-JSON standard used to
+#'create the dataset.
+#' - **fileOID**: A unique identifier for this dataset.
+#' - **dbLastModifiedDateTime**: The date/time the source database was last
+#'modified before creating the Dataset-JSON file.
+#' - **originator**: The organization that generated the Dataset-JSON dataset.
+#' - **studyOID**: Unique identifier for the study that may also function as a
+#'foreign key to a Study/@OID in an associated Define-XML document, or to any
+#'studyOID references that are used as keys in other documents;
+#' - **metaDataVersionOID**: Unique identifier for the metadata version that may
+#'also function as a foreign key to a MetaDataVersion/@OID in an associated
+#'Define-XML file
+#' - **metaDataRef**: URI for the metadata file describing the dataset (e.g.,
+#'a Define-XML file).
+#' - **itemGroupOID**: Unique identifier for the dataset that may also function
+#'as a foreign key to an ItemGroupDef/@OID in an associated Define-XML file.
+#' - **name**: The human-readable name for the dataset.
+#' - **label**: A short description of the dataset.
+#' - **columns**: An array of metadata objects that describe the dataset
+#'variables. See `dataset_json()` for further information on the contents of
+#'these fields.
+#'
+#'@param file File path or URL of a Dataset JSON file
+#'
+#'@return A dataframe with additional attributes attached containing the
+#'  DatasetJSON metadata.
+#'@export
 #'
 #' @examples
 #' # Read from disk

R/utils.R

@@ -36,6 +36,28 @@ get_null_inds <- function(x) {
   which(vapply(x, is.null, FUN.VALUE = TRUE))
 }
 
+#' Remove nulls from a Dataset JSON object
+#'
+#' Only targets the file and data metadata to pull off optional elements
+#'
+#' @param x A Dataset JSON object
+#'
+#' @return A Dataset JSON object
+#' @noRd
+remove_nulls <- function(x) {
+
+  # Specifically target the data metadata
+  dm_nulls <- get_null_inds(x)
+
+  # Top level
+  dm_nulls <- get_null_inds(x)
+  if (length(dm_nulls) > 0) {
+    x <- x[-dm_nulls]
+  }
+
+  x
+}
+
 
 
 #' Check if given path is a URL

R/write_dataset_json.R

@@ -2,7 +2,9 @@
 #'
 #' @param x datasetjson object
 #' @param file File path to save Dataset JSON file
-#' @param pretty If TRUE, write with readable formatting
+#' @param pretty If TRUE, write with readable formatting. *Note: The Dataset
+#'   JSON standard prefers compressed formatting without line feeds. It is not
+#'   recommended you use pretty printing for submission purposes.*
 #'
 #' @return NULL when file written to disk, otherwise character string
 #' @export
@@ -44,6 +46,8 @@ write_dataset_json <- function(x, file, pretty=FALSE) {
     "columns")
     ]
 
+  temp <- remove_nulls(temp)
+
   # add data rows
   temp$rows <- unname(x)