Merge pull request #148 from atorus-research/7-function-documentation

Function Documentation ReDo

R/df_label.R

@@ -1,16 +1,28 @@
 #' Assign Dataset Label
 #'
 #' Assigns dataset label from a dataset level metadata to a given data frame.
+#' This is stored in the 'label' attribute of the dataframe.
 #'
-#' @param .df A data frame of CDISC standard.
-#' @param metadata A data frame containing dataset level metadata.
-#' @param domain A character value to subset the `.df`. If `NULL`(default), uses
-#'   `.df` value as a subset condition.
-#' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass metadata now renamed with `metadata`
+#' @param metadata A data frame containing dataset. See 'Metadata' section for
+#'   details.
+#' @inheritParams xportr_length
 #'
 #' @return Data frame with label attributes.
-#' @family metadata functions
-#' @seealso [xportr_label()], [xportr_format()] and [xportr_length()]
+#'
+#' @section Metadata: The argument passed in the 'metadata' argument can either
+#'   be a metacore object, or a data.frame containing the data listed below. If
+#'   metacore is used, no changes to options are required.
+#'
+#'   For data.frame 'metadata' arguments two columns must be present:
+#'
+#'   1) Domain Name - passed as the 'xportr.df_domain_name' option. Default:
+#'   "dataset". This is the column subset by the 'domain' argument in the
+#'   function.
+#'
+#'   2) Label Name - passed as the 'xportr.df_label' option. Default:
+#'   "format". Character values to update the 'format.sas' attribute of the
+#'   dataframe This is passed to `haven::write_xpt` to note the label.
+#'
 #' @export
 #'
 #' @examples
@@ -27,12 +39,15 @@
 #' )
 #'
 #' adsl <- xportr_df_label(adsl, metadata)
-xportr_df_label <- function(.df, metadata = NULL, domain = NULL, metacore = deprecated()) {
+xportr_df_label <- function(.df,
+                            metadata = NULL,
+                            domain = NULL,
+                            metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",
-      what = "xportr_format(metacore = )",
-      with = "xportr_format(metadata = )"
+      what = "xportr_df_label(metacore = )",
+      with = "xportr_df_label(metadata = )"
     )
     metadata <- metacore
   }

R/format.R

@@ -1,18 +1,31 @@
 #' Assign SAS Format
 #'
-#' Assigns a SAS format from a variable level metadata to a given data frame.
+#' Assigns a SAS format from a variable level metadata to a given data frame. If
+#' no format is found for a given variable, it is set as an empty character
+#' vector. This is stored in the format.sas attribute.
 #'
-#' @param .df A data frame of CDISC standard.
-#' @param metadata A data frame containing variable level metadata.
-#' @param domain A character value to subset the `.df`. If `NULL`(default), uses
-#'   `.df` value as a subset condition.
-#' @param verbose The action the function takes when a variable label isn't.
-#'   found. Options are 'stop', 'warn', 'message', and 'none'
-#' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass metadata now renamed with `metadata`
+#' @inheritParams xportr_length
 #'
 #' @return Data frame with `SASformat` attributes for each variable.
-#' @family metadata functions
-#' @seealso [xportr_label()], [xportr_df_label()] and [xportr_length()]
+#'
+#' @section Metadata: The argument passed in the 'metadata' argument can either
+#'   be a metacore object, or a data.frame containing the data listed below. If
+#'   metacore is used, no changes to options are required.
+#'
+#'   For data.frame 'metadata' arguments three columns must be present:
+#'
+#'   1) Domain Name - passed as the 'xportr.domain_name' option. Default:
+#'   "dataset". This is the column subset by the 'domain' argument in the
+#'   function.
+#'
+#'   2) Format Name - passed as the 'xportr.format_name' option.
+#'   Default: "format". Character values to update the 'format.sas' attribute of
+#'   the column. This is passed to `haven::write` to note the format.
+#'
+#'   3) Variable Name - passed as the 'xportr.variable_name' option. Default:
+#'   "variable". This is used to match columns in '.df' argument and the
+#'   metadata.
+#'
 #' @export
 #'
 #' @examples
@@ -31,7 +44,6 @@
 xportr_format <- function(.df,
                           metadata = NULL,
                           domain = NULL,
-                          verbose = getOption("xportr.length_verbose", "none"),
                           metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(

R/label.R

@@ -1,18 +1,44 @@
 #' Assign Variable Label
 #'
 #' Assigns variable label from a variable level metadata to a given data frame.
+#' This function will give detect if a label is greater than
+#' 40 characters which isn't allowed in XPT v5. If labels aren't present for the
+#' variable it will be assigned an empty character value. Labels are stored in
+#' the 'label' attribute of the column.
+#'
+#' @inheritParams xportr_length
+#'
+#' @section Messaging: `label_log()` is the primary messaging tool for
+#'   `xportr_label()`. If there are any columns present in the '.df' that are not
+#'   noted in the metadata, they cannot be assigned a label and a message will
+#'   be generated noting the number or variables that have not been assigned a
+#'   label.
+#'
+#'   If variables were not found in the metadata and the value passed to the
+#'   'verbose' argument is 'stop', 'warn', or 'message', a message will be
+#'   generated detailing the variables that were missing in metadata.
+#'
+#' @section Metadata: The argument passed in the 'metadata' argument can either
+#'   be a metacore object, or a data.frame containing the data listed below. If
+#'   metacore is used, no changes to options are required.
+#'
+#'   For data.frame 'metadata' arguments three columns must be present:
+#'
+#'   1) Domain Name - passed as the 'xportr.domain_name' option. Default:
+#'   "dataset". This is the column subset by the 'domain' argument in the
+#'   function.
+#'
+#'   2) Variable Name - passed as the 'xportr.variable_name' option.
+#'   Default: "variable". This is used to match columns in '.df' argument and
+#'   the metadata.
+#'
+#'   3) Variable Label - passed as the 'xportr.label' option.
+#'   Default: "label". These character values to update the 'label' attribute of
+#'   the column. This is passed to `haven::write` to note the label.
 #'
-#' @param .df A data frame of CDISC standard.
-#' @param metadata A data frame containing variable level metadata.
-#' @param domain A character value to subset the `.df`. If `NULL`(default), uses
-#'   `.df` value as a subset condition.
-#' @param verbose The action the function takes when a variable length isn't
-#'   Found. Options are 'stop', 'warn', 'message', and 'none'
-#' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass metadata now renamed with `metadata`
 #'
 #' @return Data frame with label attributes for each variable.
-#' @family metadata functions
-#' @seealso [xportr_df_label()], [xportr_format()] and [xportr_length()]
+#'
 #' @export
 #'
 #' @examples
@@ -33,13 +59,13 @@
 xportr_label <- function(.df,
                          metadata = NULL,
                          domain = NULL,
-                         verbose = getOption("xportr.length_verbose", "none"),
+                         verbose = getOption("xportr.label_verbose", "none"),
                          metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",
-      what = "xportr_format(metacore = )",
-      with = "xportr_format(metadata = )"
+      what = "xportr_label(metacore = )",
+      with = "xportr_label(metadata = )"
     )
     metadata <- metacore
   }

R/length.R

@@ -1,18 +1,53 @@
 #' Assign SAS Length
 #'
-#' Assigns SAS length from a variable level metadata to a given data frame.
+#' Assigns SAS length from a metadata object to a given data frame. If a
+#' length isn't present for a variable the length value is set to 200 for
+#' character columns, and 8 for non-character columns. This value is stored in
+#' the 'width' attribute of the column.
 #'
 #' @param .df A data frame of CDISC standard.
-#' @param metadata A data frame containing variable level metadata.
-#' @param domain A character value to subset the `.df`. If `NULL`(default), uses
-#'   `.df` value as a subset condition.
-#' @param verbose The action the function takes when a length isn't found in
-#'   metadata. Options are 'stop', 'warn', 'message', and 'none'
-#' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass metadata now renamed with `metadata`
+#' @param metadata A data frame containing variable level metadata. See
+#'   'Metadata' section for details.
+#' @param domain Appropriate CDSIC dataset name, e.g. ADAE, DM. Used to subset
+#'   the metadata object. If none is passed, then name of the dataset passed as
+#'   .df will be used.
+#' @param verbose The action this function takes when an action is taken on the
+#'   dataset or function validation finds an issue. See 'Messaging' section for
+#'   details. Options are 'stop', 'warn', 'message', and 'none'
+#' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass
+#'   metadata now renamed with `metadata`
+#'
+#' @section Messaging: `length_log` is the primary messaging tool for
+#'   `xportr_length`. If there are any columns present in the '.df' that are not
+#'   noted in the metadata, they cannot be assigned a length and a message will
+#'   be generated noting the number or variables that have not been assigned a
+#'   length.
+#'
+#'   If variables were not found in the metadata and the value passed to the
+#'   'verbose' argument is 'stop', 'warn', or 'message', a message will be
+#'   generated detailing the variables that were missing in the metadata.
+#'
+#' @section Metadata: The argument passed in the 'metadata' argument can either
+#'   be a `{metacore}` object, or a data.frame containing the data listed below. If
+#'   metacore is used, no changes to options are required.
+#'
+#'   For data.frame 'metadata' arguments three columns must be present:
+#'
+#'   1) Domain Name - passed as the 'xportr.domain_name' option. Default:
+#'   "dataset". This is the column subset by the 'domain' argument in the
+#'   function.
+#'
+#'   2) Variable Name - passed as the 'xportr.variable_name' option.
+#'   Default: "variable". This is used to match columns in '.df' argument and
+#'   the metadata.
+#'
+#'   3) Variable Label - passed as the 'xportr.length' option.
+#'   Default: "length". These numeric values to update the 'width' attribute of
+#'   the column. This is passed to `haven::write` to note the variable length.
+#'
 #'
 #' @return Data frame with `SASlength` attributes for each variable.
-#' @family metadata functions
-#' @seealso [xportr_label()], [xportr_df_label()] and [xportr_format()]
+#'
 #' @export
 #'
 #' @examples
@@ -36,8 +71,8 @@ xportr_length <- function(.df,
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",
-      what = "xportr_format(metacore = )",
-      with = "xportr_format(metadata = )"
+      what = "xportr_length(metacore = )",
+      with = "xportr_length(metadata = )"
     )
     metadata <- metacore
   }

R/messages.R

@@ -77,15 +77,15 @@ var_names_log <- function(tidy_names_df, verbose) {
 #' @export
 type_log <- function(meta_ordered, type_mismatch_ind, verbose) {
   if (length(type_mismatch_ind) > 0) {
+    cli_h2("Variable type mismatches found.")
+    cli_alert_success("{ length(type_mismatch_ind) } variables coerced")
+
     message <- glue(
       "Variable type(s) in dataframe don't match metadata: ",
       "{encode_vars(meta_ordered[type_mismatch_ind, 'variable'])}"
     )
 
     xportr_logger(message, verbose)
-
-    cli_h2("Variable type mismatches found.")
-    cli_alert_success("{ length(type_mismatch_ind) } variables coerced")
   }
 }
 

R/metadata.R

@@ -2,15 +2,10 @@
 #'
 #' Sets metadata for a dataset in a way that can be accessed by other xportr
 #' functions. If used at the start of an xportr pipeline, it removes the need to
-#' set metadata and domain at each step individually
-#'
-#' @param .df A dataframe with columns that can be manipulated by other xportr
-#'   functions
-#' @param metadata An appropriate metadata object that has available
-#'   column-level metadata appropriate for use in other xportr functions
-#' @param domain Appropriate CDSIC dataset name, e.g. ADAE, DM. Used to subset
-#'   the metadata object. If none is passed, then name of the dataset passed .df
-#'   will be used.
+#' set metadata and domain at each step individually. For details on the format
+#' of the metadata, see the 'Metadata' section for each function in question.
+#'
+#' @inheritParams xportr_length
 #'
 #' @return `.df` dataset with metadata and domain attributes set
 #' @export

R/order.R

@@ -1,13 +1,47 @@
 #' Order variables of a dataset according to Spec
 #'
-#' @param .df A data frame of CDISC standard.
-#' @param metadata A data frame containing variable level metadata.
-#' @param domain A character value to subset the `.df`. If `NULL`(default), uses
-#'   `.df` value as a subset condition.
-#' @param verbose Option for messaging order results
-#' @param metacore `r lifecycle::badge("deprecated")` Previously used to pass metadata now renamed with `metadata`
+#' The `dplyr::arrange()` function is used to order the columns of the dataframe.
+#' Any variables that are missing an order value are appended to the end of the dataframe
+#' after all of the variables that have an order.
+#'
+#' @inheritParams xportr_length
 #'
 #' @export
+#'
+#' @section Messaging: `var_ord_msg()` is the primary messaging tool for
+#'   `xportr_order()`. There are two primary messages that are output from
+#'   `var_ord_msg()`. The first is the "moved" variables. These are the variables
+#'   that were not found in the metadata file and moved to the end of the
+#'   dataset. A message will be generated noting the number, if any, of
+#'   variables that were moved to the end of the dataset. If any variables were
+#'   moved, and the 'verbose' argument is 'stop', 'warn', or 'message', a
+#'   message will be generated detailing the variables that were moved.
+#'
+#'   The second primary message is the number of variables that were in the
+#'   dataset, but not in the correct order. A message will be generated noting
+#'   the number, if any, of variables that have been reordered. If any variables
+#'   were reordered, and the 'verbose' argument is 'stop', 'warn', or 'message',
+#'   a message will be generated detailing the variables that were reordered.
+#'
+#' @section Metadata: The argument passed in the 'metadata' argument can either
+#'   be a metacore object, or a data.frame containing the data listed below. If
+#'   metacore is used, no changes to options are required.
+#'
+#'   For data.frame 'metadata' arguments three columns must be present:
+#'
+#'   1) Domain Name - passed as the 'xportr.domain_name' option. Default:
+#'   "dataset". This is the column subset by the 'domain' argument in the
+#'   function.
+#'
+#'   2) Variable Name - passed as the 'xportr.variable_name' option.
+#'   Default: "variable". This is used to match columns in '.df' argument and
+#'   the metadata.
+#'
+#'   3) Variable Order - passed as the 'xportr.order_name' option.
+#'   Default: "order". These values used to arrange the order of the variables.
+#'   If the values of order metadata are not numeric, they will be corsersed to
+#'   prevent alphabetical sorting of numberic values.
+#'
 #' @return Dataframe that has been re-ordered according to spec
 #'
 #' @examples
@@ -28,13 +62,13 @@
 xportr_order <- function(.df,
                          metadata = NULL,
                          domain = NULL,
-                         verbose = getOption("xportr.length_verbose", "none"),
+                         verbose = getOption("xportr.order_verbose", "none"),
                          metacore = deprecated()) {
   if (!missing(metacore)) {
     lifecycle::deprecate_warn(
       when = "0.3.0",
-      what = "xportr_format(metacore = )",
-      with = "xportr_format(metadata = )"
+      what = "xportr_order(metacore = )",
+      with = "xportr_order(metadata = )"
     )
     metadata <- metacore
   }