Release: prepare for first CRAN release

.Rbuildignore

@@ -4,3 +4,8 @@
 ^icons$
 ^_development$
 ^\.github$
+^_pkgdown.yml$
+^doc$
+^Meta$
+^cran-comments\.md$
+^LICENSE\.md$

.github/workflows/R-CMD-check.yaml

@@ -1,20 +1,49 @@
-on: [push, pull_request]
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
 
 name: R-CMD-check
 
 jobs:
   R-CMD-check:
-    runs-on: macOS-latest
+    runs-on: ${{ matrix.config.os }}
+
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - {os: macos-latest,   r: 'release'}
+          - {os: windows-latest, r: 'release'}
+          - {os: ubuntu-latest,  r: 'devel', http-user-agent: 'release'}
+          - {os: ubuntu-latest,  r: 'release'}
+          - {os: ubuntu-latest,  r: 'oldrel-1'}
+
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      R_KEEP_PKG_SOURCE: yes
+
     steps:
       - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
       - uses: r-lib/actions/setup-r@v2
-      - name: Install dependencies
-        run: |
-          install.packages(c("remotes", "rcmdcheck"))
-          remotes::install_deps(dependencies = TRUE)
-        shell: Rscript {0}
-      - name: Check
-        env:
-          _R_CHECK_FORCE_SUGGESTS_: true
-        run: rcmdcheck::rcmdcheck(args = "--no-manual", error_on = "error")
-        shell: Rscript {0}
+        with:
+          r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          args: 'c("--no-manual", "--as-cran")'
+          error-on: '"error"'
+          upload-snapshots: true

.gitignore

@@ -2,3 +2,5 @@
 .Rhistory
 .RData
 .Ruserdata
+/doc/
+/Meta/

DESCRIPTION

@@ -1,18 +1,25 @@
 Package: surveytoolbox
 Type: Package
 Title: Useful Support Functions for Survey Analysis
-Version: 0.1.0.9000
-Author: Martin Chan
-Maintainer: Martin Chan <martinchan53@gmail.com>
-URL: https://github.com/martinctc/surveytoolbox
-Description: A R package containing useful support functions for survey analysis.
+Version: 0.1.0
+Authors@R: 
+    person("Martin", "Chan", , "martinchan53@gmail.com", role = c("aut", "cre"))
+URL: https://github.com/martinctc/surveytoolbox/
+BugReports: https://github.com/martinctc/surveytoolbox/issues
+Description: A collection of tools for analyzing and visualizing survey data 
+    in R. This package provides functions for manipulating variable and value 
+    labels commonly found in SPSS datasets, creating data dictionaries, 
+    converting variable types between labelled and standard R types, performing 
+    rowwise operations with 'dplyr' syntax, creating dummy variables from 
+    categorical data, and computing common survey metrics such as Net Promoter 
+    Score (NPS) and top-box/bottom-box transformations. It integrates seamlessly 
+    with the 'tidyverse' workflow and the 'haven' package for labelled data.
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 Roxygen: list(markdown = TRUE)
 Imports: 
-    base,
     dplyr,
     stringr,
     stats,
@@ -21,11 +28,19 @@ Imports:
     readr,
     haven,
     tidyr,
-    psych,
     magrittr,
     purrr,
     glue,
-    data.table
+    data.table,
+    broom,
+    rstatix,
+    graphics,
+    rlang
 Suggests: 
-    testthat (>= 3.0.0)
+    testthat (>= 3.0.0),
+    knitr,
+    rmarkdown,
+    ggplot2,
+    psych
 Config/testthat/edition: 3
+VignetteBuilder: knitr

LICENSE.md

@@ -0,0 +1,5 @@
+# GNU General Public License v3.0
+
+This package is licensed under the GNU General Public License version 3 (GPL-3).
+
+For the full text of the license, see: https://www.gnu.org/licenses/gpl-3.0.en.html

NAMESPACE

@@ -17,6 +17,7 @@ export(chr_to_var)
 export(clean_strings)
 export(copy_df)
 export(cor_to_df)
+export(create_freq_dist)
 export(create_named_list)
 export(data_dict)
 export(extract_fa_loads)
@@ -40,19 +41,31 @@ export(squish)
 export(superspread)
 export(superspread_count)
 export(superspread_fill)
+export(test_chisq)
 export(timed_fn)
 export(ttest_nps)
 export(varl_tb)
 export(wrap_text)
 import(dplyr)
 import(haven)
 import(stringr)
+importFrom(broom,tidy)
 importFrom(data.table,":=")
+importFrom(dplyr,filter)
+importFrom(dplyr,mutate)
+importFrom(dplyr,select)
 importFrom(glue,glue)
+importFrom(graphics,hist)
 importFrom(magrittr,"%>%")
 importFrom(purrr,is_null)
 importFrom(purrr,map)
+importFrom(rlang,.data)
+importFrom(rlang,sym)
+importFrom(rstatix,chisq_test)
+importFrom(stats,chisq.test)
+importFrom(stats,fisher.test)
 importFrom(tibble,enframe)
 importFrom(tibble,tibble)
 importFrom(tidyr,drop_na)
+importFrom(tidyr,pivot_longer)
 importFrom(tidyr,unnest)

NEWS.md

@@ -0,0 +1,25 @@
+# surveytoolbox (development version)
+
+# surveytoolbox 0.1.0
+
+## New Features
+
+* Initial CRAN release
+* Core functions for survey data manipulation:
+  - `superspread()`, `superspread_count()`, `superspread_fill()` for creating dummy variables
+  - `data_dict()` for creating data dictionaries from labelled data
+  - `look_up()` for lookup table operations
+  - `apply_row()` for rowwise operations with dplyr syntax
+  - `box_it()` for creating top/bottom box variables
+  - `as_nps()` and `as_nps_cat()` for NPS calculations
+  - `test_chisq()` and `ttest_nps()` for statistical tests
+  - Label manipulation functions: `set_varl()`, `set_vall()`, `recode_vallab()`, `extract_vallab()`
+  - Data conversion functions: `char_to_lab()`, `lab_to_char()`, `chr_to_var()`
+  - Utility functions: `clean_strings()`, `wrap_text()`, `timed_fn()`, `categorise()`
+  - File operations: `sav_to_rds()`, `copy_df()`, `read_df()`
+  - Scale transformations: `likert_convert()`, `likert_reverse()`, `maxmin()`
+
+## Documentation
+
+* Added vignettes: "Getting Started" and "surveytoolbox Walkthrough"
+* Full roxygen2 documentation for all exported functions

R/CAGR.R

@@ -1,12 +1,14 @@
-#' Calculate CAGR
+#' @title Calculate CAGR
 #' 
-#' Calculates the Compound Annual Growth Rate (CAGR).
+#' @description Compute the Compound Annual Growth Rate (CAGR).
 #' @param value_begin The value at the start of the series.
 #' @param value_end The value at the end of the series.
 #' @param n_periods The number of periods to base the CAGR calculations on.
 #' 
 #' @seealso http://www.investopedia.com/terms/c/cagr.asp
 #' 
+#' @return numeric value
+#' 
 #' @export
 CAGR <- function(value_begin, value_end, n_periods){
 

R/any_x.R

@@ -1,21 +1,26 @@
-#' @title Function that returns TRUE/FALSE if value exists in x, but returns NA if x consists entirely of NAs
+#' @title Function that returns either TRUE or FALSE if value exists in x, but
+#'   returns NA if x consists entirely of NAs
 #' 
 #' @description 
-#' A more nuanced response is returned than the standard R method,
-#' which does not return NAs if x is all NAs.
-#' Has useful applications in understanding a set of categorical variables
-#' belonging to a single question.
-#' E.g. A question on brand usage across 10 product types to understand 'any' usage of a brand x.
-#' 
-#' @return A logical vector whether a value exists in x, and returns NA if x contains only NAs.
+#' A more nuanced response is returned than the standard R method, which does
+#' not return NAs if x is all NAs. Has useful applications in understanding a
+#' set of categorical variables belonging to a single question.
+#' E.g. A question on brand usage across 10 product types to understand 'any'
+#' usage of a brand x.
+#'   
 #' @param x Vector of values to test.
-#' @param value Value to test whether it exists in x. NA is returned if none exists at all. 
+#' @param value Value to test whether it exists in x. NA is returned if none
+#'   exists at all.
+#'   
 #' @examples
 #' any_x(c(1,0,1),1) # TRUE
 #' any_x(c(1,NA,1),1) # TRUE
 #' any_x(c(0,0,NA),1) # FALSE
 #' any_x(c(NA,NA,NA),1) # NA
 #' 
+#' @return A logical vector whether a value exists in x, and returns NA if x
+#'   contains only NAs.
+#' 
 #' @export
 any_x <- function(x, value){
   if(all(is.na(x))){

R/append_to_list.R

@@ -1,20 +1,22 @@
 #' @title Append an item to a list dynamically
 #' 
 #' @description
-#' The `append_to_list()` function appends an object to the specified list in Global Environment (default).
-#' This function is pipe-optimised, and allows the option of specifying a name for the new object in the list.
+#' The `append_to_list()` function appends an object to the specified list in
+#' Global Environment (default). This function is pipe-optimised, and allows the
+#' option of specifying a name for the new object in the list.
 #' 
 #' @param x An object to append to list, e.g. vector, data frame. 
 #' @param list_x Target list to append object to. 
-#' @param name Specify a character string for the name of the list. Defaults to blank
+#' @param name character string for the name of the list. Defaults to
+#'   a blank string
 #' @param enviro Specifies the environment
 #'
 #' @examples
 #' a_list <- list(NULL)
 #' append_to_list(iris,a_list,"iris") 
 #' 
 #' @export
-append_to_list <- function(x, list_x, name="", enviro = .GlobalEnv){
+append_to_list <- function(x, list_x, name = "", enviro = .GlobalEnv){
 
   temp <- deparse(substitute(list_x))
 

R/apply_row.R

@@ -1,12 +1,14 @@
-#' @title Apply a function rowwise, selecting variables with dplyr::select() syntax
+#' @title Apply a function rowwise, selecting variables with `dplyr::select()`
+#'   syntax
 #'
 #' @description
 #' `apply_row()` is a wrapper around `apply()` and `select()`,
-#' applying a function rowwise, and selecting variables with dplyr::select() syntax.
+#' applying a function rowwise, and selecting variables with `dplyr::select(`)
+#' syntax.
 #' This makes code slightly less verbose for rowwise operations.
 #'
 #' @param x Data frame or tibble to pass through.
-#' @param select_helpers Select variables using dplyr::select() syntax
+#' @param select_helpers Select variables using `dplyr::select()` syntax
 #' @param FUN Function to be applied to selected columns
 #' @param ... Additional arguments to the function.
 #' 
@@ -21,6 +23,8 @@
 #' iris %>% mutate(Any_Petal = apply_row(., petal_str, function(x) any(x > 1)))
 #' }
 #' 
+#' @return 
+#' transformed version of the vector `x`
 #' 
 #' @export
 

R/as_nps_cat.R

@@ -1,14 +1,23 @@
+#' @title
 #' Convert numeric variable to NPS categorical variable
 #' 
+#' @description
 #' Returns a categorical variable with default values over 1, 2, and 3.
 #' Suited for running multinomial logistic regression. 
 #' To calculate the NPS score, use `as_nps()`.
 #' 
-#' @param x Numeric variable to pass through. Valid range is 0 to 10 inclusive, otherwise returns a NA.
+#' @param x Numeric variable to pass through. Valid range is 0 to 10 inclusive,
+#'   otherwise returns a NA.
 #' @param det Numeric value to represent the code for Detractor. Defaults to 1.
 #' @param pas Numeric value to represent the code for Passive. Defaults to 2.
 #' @param pro Numeric value to represent the code for Promoter. Defaults to 3.
 #' 
+#' @return a labelled double variable
+#' 
+#' @examples
+#' x <- sample(0:10, size = 50, replace = TRUE)
+#' as_nps_cat(x)
+#' 
 #' @export
 as_nps_cat <-function(x, det = 1, pas = 2, pro = 3){
   if(any(!is.numeric(c(det, pas, pro)))){

R/as_percent.R

@@ -1,10 +1,14 @@
+#' @title
 #' Convert as percent (string)
 #' 
+#' @description
 #' Convert a numeric value into a string with percentage sign.
+#' 
 #' @param num Numeric vector to pass through
 #' @param rounding Number of decimal places to round to. Default is 0.
 #' @examples 
 #' as_percent(.86748)
+#' 
 #' @export
 as_percent <- function(num, rounding = 0){
   paste0(round(num * 100, rounding),"%")

R/box_it.R

@@ -1,4 +1,6 @@
-#' Convert ordinal variables into binary variables by "boxing"
+#' @title
+#' Convert ordinal variables into binary variables by creating top or bottom n
+#' 'box' categories
 #' 
 #' @description
 #' For instance, you can create a Top Two Box variable from a 7-point agreement
@@ -25,7 +27,10 @@
 #' @return a binary variable of labelled double type.
 #' 
 #' @examples
-#' box_it(sample(1:10,100,replace = TRUE)) # Converted to binary variable where 9, 10 are selected
+#' # Converted to binary variable where 9, 10 are selected
+#' box_it(sample(1:10,100,replace = TRUE)) 
+#' 
+#' # Example with missing values
 #' box_it(sample(c(1:10, NA),100,replace = TRUE))
 #' 
 #' # Example where specified numeric values are replaced with NAs

R/calc_pc_loglin.R

@@ -1,12 +1,22 @@
+#' @title 
 #' Calculate percentage impact from coefficients of a log-linear model
 #' 
-#' Exponentiates coefficients and takes out 1 to calculate percentage impact.
-#' Returns a tibble
+#' @description
+#' This function exponentiates coefficients and takes out 1 to calculate the
+#' percentage impact of each variable on the response variable in a log-linear
+#' model. The function returns a tibble with three columns: `var`, `coef`, and
+#' `pc_impact`.
+#' 
+#' @param x A log-linear model object.
+#' 
+#' @return A tibble with three columns: `var`, `coef`, and `pc_impact`.
 #' 
 #' @import dplyr
 #' 
 #' @param x Log-linear model to be passed through
 #' 
+#' @return a [tibble][tibble::tibble-package]    
+#' 
 #' @export
 calc_pc_loglin <- function(x){
   x$coefficients %>%