Function Documentation ReDo

.github/ISSUE_TEMPLATE/01_bug_report.yml

@@ -0,0 +1,33 @@
+name: Bug Report
+description: Something is not working correctly or is not working at all!
+title: "Bug: <Insert Issue Title Here>"
+labels: ["bug", "programming"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Example:** Bug: xportr_format() does not assign SAS format for `DATE9.` metadata
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Also tell us what were you expecting to happen before the bug?
+      placeholder: "A bug happened!"
+    validations:
+      required: true
+  - type: textarea
+    id: session-info
+    attributes:
+      label: Session Information
+      description: Use `sessionInfo()` in the R console to gather all the details of your environment when the bug happened.
+      placeholder: "Place the console output here"
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Reproducible Example
+      description: We love code that can reproduce the bug. Check out [reprex](https://reprex.tidyverse.org/articles/reprex-dos-and-donts.html)
+      placeholder: "Please give us as many details as you can! The faster we can recreate the bug, the faster we can get a fix in the works.  Warning, Error Messages and Screenshots are also great."
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/02_feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature Request
+description: Enchancement to xportr functionality
+title: "Feature Request: <Insert Issue Title Here>"
+labels: ["enhancement", "programming"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this feature request! We love keeping xportr fresh!
+  - type: textarea
+    id: feature
+    attributes:
+      label: Feature Idea
+      description: Tell us your idea in as few words as possible
+      placeholder: "`xportr_validate` should do x, y and z"
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Relevant Input
+      description: Can you provide what the inputs should look like?
+      placeholder: "What should the input look like? REMINDER: No patient level data or company sensitive information should be shared via this open public issue"
+    validations:
+      required: false
+  - type: textarea
+    id: output
+    attributes:
+      label: Relevant Output
+      description: Can you provide what the final output should look like?
+      placeholder: "What should the output look like? REMINDER: No patient level data or company sensitive information should be shared via this open public issue"
+    validations:
+      required: false
+  - type: textarea
+    id: code
+    attributes:
+      label: Reproducible Example/Pseudo Code
+      description: Can you provide a working example or a sketch of how the code should work?
+      placeholder: "We love example code and it will speed up the process! REMINDER: No patient level data or company sensitive information should be shared via this open public issue"
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE/release.md

@@ -0,0 +1,22 @@
+# Release Description
+<!--- Summarize what is being released.  -->
+
+## Milestone
+<!--- Link to the milestone for the release. ---> 
+<!--- Make sure all relevant issues are included on the linked pages. --->
+Milestone: 
+
+# Release Checklist
+<!--- Fill out the following Release checklist -->
+
+- [ ] DESCRIPTION File version number has been updated
+- [ ] DESCRIPTION file updated with New Developers (if applicable)
+- [ ] NEWS.md has been updated and issues numbers linked
+- [ ] README.md has been updated (if applicable)
+- [ ] Vignettes have been updated (if applicable)
+- [ ] Ensure all unit tests are passing
+- [ ] Review https://r-pkgs.org/release.html for additional checks and guidance
+- [ ] Use `rhub::check_for_cran()` for checking CRAN flavors before submission
+- [ ] Use `usethis::use_revdep()` to check for any reverse dependencies
+- [ ] GitHub actions on this PR are all passing
+- [ ] Draft GitHub release created using automatic template and updated with additional details. Remember to click "release" after PR is merged.

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+### Thank you for your Pull Request! 
+
+We have developed a Pull Request template to aid you and our reviewers.  Completing the below tasks helps to ensure our reviewers can maximize their time on your code as well as making sure the xportr codebase remains robust and consistent.  
+
+### The scope of `{xportr}`
+
+`{xportr}`'s scope is to enable R users to write out submission compliant `xpt` files that can be delivered to a Health Authority or to downstream validation software programs.  We see labels, lengths, types, ordering and formats from a dataset specification object (SDTM and ADaM) as being our primary focus. We also see messaging and warnings to users around applying information from the specification file as a primary focus. Please make sure your Pull Request meets this **scope of {xportr}**. If your Pull Request moves beyond this scope, please get in touch with the `{xportr}` team on [slack](https://pharmaverse.slack.com/archives/C030EB2M4GM) or create an issue to discuss.
+
+Please check off each task box as an acknowledgment that you completed the task. This checklist is part of the Github Action workflows and the Pull Request will not be merged into the `devel` branch until you have checked off each task.
+
+### Changes Description
+
+_(descriptions of changes)_ 
+
+### Task List
+
+- [ ] The spirit of xportr is met in your Pull Request
+- [ ] Place Closes #<insert_issue_number> into the beginning of your Pull Request Title (Use Edit button in top-right if you need to update)
+- [ ] Summary of changes filled out in the above Changes Description.  Can be removed or left blank if changes are minor/self-explanatory.
+- [ ] Check that your Pull Request is targeting the `devel` branch, Pull Requests to `main` should use the [Release Pull Request Template](https://github.com/atorus-research/xportr/tree/94_pr_template/.github/PULL_REQUEST_TEMPLATE)
+- [ ] Code is formatted according to the [tidyverse style guide](https://style.tidyverse.org/).  Use `styler` package and functions to style files accordingly.
+- [ ] Updated relevant unit tests or have written new unit tests. See our [Wiki](https://github.com/atorus-research/xportr/wiki/Style-Guide-for-Unit-Tests) for conventions used in this package.
+- [ ] Creation/updated relevant roxygen headers and examples. See our [Wiki](https://github.com/atorus-research/xportr/wiki/Style-Guide-for-Roxygen-Headers) for conventions used in this package.
+- [ ] Run `devtools::document()` so all `.Rd` files in the `man` folder and the `NAMESPACE` file in the project root are updated appropriately
+- [ ] Run `pkgdown::build_site()` and check that all affected examples are displayed correctly and that all new/updated functions occur on the "Reference" page.
+- [ ] Update NEWS.md if the changes pertain to a user-facing function (i.e. it has an @export tag) or documentation aimed at users (rather than developers)
+- [ ] Address any updates needed for vignettes and/or templates
+- [ ] Link the issue Development Panel so that it closes after successful merging.
+- [ ] Fix merge conflicts 
+- [ ] Pat yourself on the back for a job well done!  Much love to your accomplishment!

.github/workflows/pkgdown.yaml

@@ -14,7 +14,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
 
       - uses: r-lib/actions/setup-pandoc@v1
 

.github/workflows/spellcheck.yml

@@ -32,7 +32,7 @@ jobs:
           fetch-depth: 0
 
       - name: Setup R 📊
-        uses: r-lib/actions/setup-r@v1
+        uses: r-lib/actions/setup-r@v2
         with:
           r-version: 4.1.3
 

.github/workflows/test-coverage.yaml

@@ -18,7 +18,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - uses: r-lib/actions/setup-r@v1
+      - uses: r-lib/actions/setup-r@v2
 
       - uses: r-lib/actions/setup-pandoc@v1
 

R/df_label.R

@@ -1,16 +1,24 @@
 #' 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`
+#' @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 +35,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,28 @@
 #' 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 +41,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,40 @@
 #' Assign Variable Label
 #'
 #' Assigns variable label from a variable level metadata to a given data frame.
+#' This function will give an error if a label is presented that 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 +55,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,49 @@
 #' Assign SAS Length
 #'
-#' Assigns SAS length from a variable level metadata to a given data frame.
+#' Assigns SAS length from a variable level metadata 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 dataset/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 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 +67,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
   }