diff --git a/.Rbuildignore b/.Rbuildignore index 208d4de..68053ca 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,4 +1,4 @@ -^a11ytables\.Rproj$ +^aftables\.Rproj$ ^\.Rproj\.user$ ^data-raw$ ^README\.Rmd$ @@ -11,3 +11,4 @@ ^codecov\.yml$ ^doc$ ^Meta$ +^cran-comments\.md$ diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 27344ac..7790c50 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -1,4 +1,4 @@ -# Code of Conduct for `a11ytables` +# Code of Conduct for `aftables` ## Civil Service Code diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 682046a..4eb0c4f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to {a11ytables} +# Contributing to {aftables} -This outlines how to propose a change to {a11ytables}. +This outlines how to propose a change to {aftables}. ## Fixing typos diff --git a/DESCRIPTION b/DESCRIPTION index bcdf009..029e007 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ -Package: a11ytables +Package: aftables Title: Create Spreadsheet Publications Following Best Practice -Version: 0.3.2 +Version: 1.0.0 Authors@R: c( person("Matt", "Dray", , "mwdray@gmail.com", role = c("aut")), person("Tim", "Taylor", role = "ctb"), @@ -13,11 +13,11 @@ Description: Generate spreadsheet publications that follow best practice accessibility. Based on 'openxlsx'. See also the Python package 'gptables'. License: MIT + file LICENSE -URL: https://best-practice-and-impact.github.io/a11ytables/, - https://github.com/best-practice-and-impact/a11ytables -BugReports: https://github.com/best-practice-and-impact/a11ytables/issues +URL: https://best-practice-and-impact.github.io/aftables/, + https://github.com/best-practice-and-impact/aftables +BugReports: https://github.com/best-practice-and-impact/aftables/issues Depends: - R (>= 2.10) + R (>= 3.5) Imports: openxlsx, pillar diff --git a/NAMESPACE b/NAMESPACE index 1cd6fce..4f1b52e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,11 +1,11 @@ # Generated by roxygen2: do not edit by hand -S3method(summary,a11ytable) -S3method(tbl_sum,a11ytable) -export(as_a11ytable) -export(at_template_a11ytable) +S3method(summary,aftable) +S3method(tbl_sum,aftable) +export(as_aftable) +export(at_template_aftable) export(at_template_workflow) -export(create_a11ytable) +export(create_aftable) export(generate_workbook) -export(is_a11ytable) +export(is_aftable) importFrom(pillar,tbl_sum) diff --git a/NEWS.md b/NEWS.md index 0ce148f..90350a9 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,8 @@ +# aftables 1.0.0 + +* Updated package name to aftables. Function names have been updated to remove references to a11ytables. + + # a11ytables 0.3.2 * Bug fix: ensured factors are converted to character before assessing whether the column needs to be widened (#110, #113). diff --git a/R/addin.R b/R/addin.R index 0f5fe73..eba8a17 100644 --- a/R/addin.R +++ b/R/addin.R @@ -1,17 +1,17 @@ -#' Insert Demo 'create_a11ytable' Template +#' Insert Demo 'create_aftable' Template #' -#' Insert at the cursor a template for \code{\link{create_a11ytable}} from the -#' 'a11ytable' package, pre-filled with demo data. +#' Insert at the cursor a template for \code{\link{create_aftable}} from the +#' 'aftable' package, pre-filled with demo data. #' #' @export -at_template_a11ytable <- function() { - rstudioapi::insertText(string_create_a11ytable()) +at_template_aftable <- function() { + rstudioapi::insertText(string_create_aftable()) } -#' Insert Full Demo 'a11ytables' Template Workflow +#' Insert Full Demo 'aftables' Template Workflow #' #' Insert at the cursor (a) demo templates for cover, contents and notes -#' tables, and (b) a call to \code{\link{create_a11ytable}} pre-filled with +#' tables, and (b) a call to \code{\link{create_aftable}} pre-filled with #' demo data. #' #' @export @@ -23,13 +23,13 @@ at_template_workflow <- function() { "\n\n", string_tables(), "\n\n", - "# Create new a11ytable", + "# Create new aftable", "\n\n", - string_create_a11ytable(), + string_create_aftable(), "\n\n", - "# Generate workbook from a11ytable", + "# Generate workbook from aftable", "\n\n", - "my_wb <- a11ytables::generate_workbook(my_a11ytable)", + "my_wb <- aftables::generate_workbook(my_aftable)", "\n\n", "# Create output", "\n\n", @@ -41,7 +41,7 @@ at_template_workflow <- function() { } -#' A String Containing Code to Prepare Tables for an 'a11ytables' Object +#' A String Containing Code to Prepare Tables for an 'aftables' Object #' @noRd string_tables <- function() { @@ -49,8 +49,8 @@ string_tables <- function() { "Section 1" = c("First row of Section 1.", "Second row of Section 1."), "Section 2" = "The only row of Section 2.", "Section 3" = c( - "[Website](https://best-practice-and-impact.github.io/a11ytables/)", - "[Email address](mailto:fake.address@a11ytables.com)" + "[Website](https://best-practice-and-impact.github.io/aftables/)", + "[Email address](mailto:fake.address@aftables.com)" ) ) @@ -85,16 +85,16 @@ table_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10)' } -#' A String Containing Code to Generate an 'a11ytables' Object +#' A String Containing Code to Generate an 'aftables' Object #' @noRd -string_create_a11ytable <- function() { +string_create_aftable <- function() { - 'my_a11ytable <- - a11ytables::create_a11ytable( + 'my_aftable <- + aftables::create_aftable( tab_titles = c("Cover", "Contents", "Notes", "Table_1", "Table_2"), sheet_types = c("cover", "contents", "notes", "tables", "tables"), sheet_titles = c( - "The \'a11ytables\' Demo Workbook", + "The \'aftables\' Demo Workbook", "Table of contents", "Notes", "Table 1: First Example Sheet", @@ -111,13 +111,13 @@ string_create_a11ytable <- function() { NA_character_, c( "First custom row for Table 1.", - "A second custom row [with a hyperlink.](https://best-practice-and-impact.github.io/a11ytables/)" + "A second custom row [with a hyperlink.](https://best-practice-and-impact.github.io/aftables/)" ), "A custom row for Table 2" ), sources = c( rep(NA_character_, 3), - "[The Source Material, 2024](https://best-practice-and-impact.github.io/a11ytables/)", + "[The Source Material, 2024](https://best-practice-and-impact.github.io/aftables/)", "The Source Material, 2024" ), tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df) diff --git a/R/a11ytable.R b/R/aftable.R similarity index 82% rename from R/a11ytable.R rename to R/aftable.R index d88285c..beccf7e 100644 --- a/R/a11ytable.R +++ b/R/aftable.R @@ -1,7 +1,7 @@ -#' Create An 'a11ytable' Object +#' Create An 'aftable' Object #' -#' Create a new a11ytable-class object, which is a special data.frame that +#' Create a new aftable-class object, which is a special data.frame that #' contains all the information needed in your output spreadsheet. In turn, the #' object created by this function can be used to populate an 'openxlsx' #' Workbook-class object with the function \code{\link{generate_workbook}}. @@ -79,7 +79,7 @@ #' \item To the 'source' argument for sheets of type 'table' only. #' } #' -#' @return An object with classes 'a11ytable', 'tbl' and 'data.frame'. +#' @return An object with classes 'aftable', 'tbl' and 'data.frame'. #' #' @examples #' # Prepare some demo tables of information @@ -90,8 +90,8 @@ #' "Section 1" = c("First row of Section 1.", "Second row of Section 1."), #' "Section 2" = "The only row of Section 2.", #' "Section 3" = c( -#' "[Website](https://best-practice-and-impact.github.io/a11ytables/)", -#' "[Email address](mailto:fake.address@a11ytables.com)" +#' "[Website](https://best-practice-and-impact.github.io/aftables/)", +#' "[Email address](mailto:fake.address@aftables.com)" #' ) #' ) #' @@ -124,14 +124,14 @@ #' #' table_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10) #' -#' # Create 'a11ytables' object +#' # Create 'aftables' object #' #' x <- -#' a11ytables::create_a11ytable( +#' aftables::create_aftable( #' tab_titles = c("Cover", "Contents", "Notes", "Table_1", "Table_2"), #' sheet_types = c("cover", "contents", "notes", "tables", "tables"), #' sheet_titles = c( -#' "The 'a11ytables' Demo Workbook", +#' "The 'aftables' Demo Workbook", #' "Table of contents", #' "Notes", #' "Table 1: First Example Sheet", @@ -147,27 +147,27 @@ #' NA_character_, #' "A custom row.", #' c( -#' "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/a11ytables/)", +#' "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/aftables/)", #' "Second custom row." #' ), #' "A custom row." #' ), #' sources = c( #' rep(NA_character_, 3), -#' "[The Source Material, 2024.](https://best-practice-and-impact.github.io/a11ytables/)", +#' "[The Source Material, 2024.](https://best-practice-and-impact.github.io/aftables/)", #' "The Source Material, 2024." #' ), #' tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df) #' ) #' -#' # Test that 'a11ytable' is one of the object's classes -#' is_a11ytable(x) +#' # Test that 'aftable' is one of the object's classes +#' is_aftable(x) #' #' # Look at the structure of the object #' str(x, max.level = 2) #' #' @export -create_a11ytable <- function(tab_titles, +create_aftable <- function(tab_titles, sheet_types = c("cover", "contents", "notes", "tables"), sheet_titles, blank_cells = NA_character_, @@ -187,25 +187,25 @@ create_a11ytable <- function(tab_titles, x[["custom_rows"]] <- custom_rows x[["table"]] <- tables - as_a11ytable(x) + as_aftable(x) } -#' Coerce To An 'a11ytable' Object +#' Coerce To An 'aftable' Object #' -#' Functions to check if an object is an a11ytable, or coerce it if possible. +#' Functions to check if an object is an aftable, or coerce it if possible. #' #' @param x A data.frame object to coerce. #' -#' @return \code{as_a11ytable} returns an object of class a11ytable if possible. -#' \code{is_a11ytable} returns \code{TRUE} if the object has class -#' a11ytable, otherwise \code{FALSE}. +#' @return \code{as_aftable} returns an object of class aftable if possible. +#' \code{is_aftable} returns \code{TRUE} if the object has class +#' aftable, otherwise \code{FALSE}. #' #' @examples -#' is_a11ytable(demo_a11ytable) +#' is_aftable(demo_aftable) #' #' @export -as_a11ytable <- function(x) { +as_aftable <- function(x) { if (any(names(x) %in% "tab_title")) { .check_tab_titles(x[["tab_title"]]) @@ -216,41 +216,41 @@ as_a11ytable <- function(x) { x[["blank_cells"]] <- .append_period(x[["blank_cells"]]) } - class(x) <- c("a11ytable", "tbl", "data.frame") + class(x) <- c("aftable", "tbl", "data.frame") - .validate_a11ytable(x) - .warn_a11ytable(x) + .validate_aftable(x) + .warn_aftable(x) x } -#' @rdname as_a11ytable +#' @rdname as_aftable #' @export -is_a11ytable <- function(x) { +is_aftable <- function(x) { - inherits(x, "a11ytable") + inherits(x, "aftable") } -#' Summarise An 'a11ytable' Object +#' Summarise An 'aftable' Object #' -#' A concise result summary of an a11ytable-class object to see information +#' A concise result summary of an aftable-class object to see information #' about the sheet content. Shows a numbered list of sheets with each tab title, #' sheet type and table dimensions. #' -#' @param object An a11ytable-class object for which to get a summary. +#' @param object An aftable-class object for which to get a summary. #' @param ... Other arguments to pass. #' #' @examples -#' # Print a concise summary of the a11ytable-class object -#' summary(demo_a11ytable) +#' # Print a concise summary of the aftable-class object +#' summary(demo_aftable) #' #' # Alternatively, look at the structure -#' str(demo_a11ytable, max.level = 2) +#' str(demo_aftable, max.level = 2) #' #' @export -summary.a11ytable <- function(object, ...) { +summary.aftable <- function(object, ...) { tables <- object[["table"]] @@ -288,31 +288,31 @@ summary.a11ytable <- function(object, ...) { ) ) - cat("# An a11ytable with", nrow(object), "sheets:", summary_string) + cat("# An aftable with", nrow(object), "sheets:", summary_string) invisible(object) } -#' Provide A Succinct Summary Of An 'a11ytable' Object +#' Provide A Succinct Summary Of An 'aftable' Object #' -#' A brief text description of an a11ytable-class object. +#' A brief text description of an aftable-class object. #' -#' @param x An a11ytable-class object to summarise. +#' @param x An aftable-class object to summarise. #' @param ... Other arguments to pass. #' #' @return Named character vector. #' #' @examples #' # Print with description -#' print(demo_a11ytable) +#' print(demo_aftable) #' #' # Print description only (package 'tibble' must be installed) -#' tibble::tbl_sum(demo_a11ytable) +#' tibble::tbl_sum(demo_aftable) #' #' @export -tbl_sum.a11ytable <- function(x, ...) { +tbl_sum.aftable <- function(x, ...) { header <- sprintf( "%s x %s", @@ -320,6 +320,6 @@ tbl_sum.a11ytable <- function(x, ...) { formatC(ncol(x), big.mark = ",") ) - c("a11ytable" = header) + c("aftable" = header) } diff --git a/R/a11ytables-package.R b/R/aftables-package.R similarity index 100% rename from R/a11ytables-package.R rename to R/aftables-package.R diff --git a/R/data.R b/R/data.R index dd733de..e691e13 100644 --- a/R/data.R +++ b/R/data.R @@ -1,7 +1,7 @@ #' A Demo 'data.frame' Object #' -#' A pre-created data.frame ready to be converted to an a11ytables-class object -#' with \code{\link{as_a11ytable}} and then an 'openxlsx' Workbook-class object +#' A pre-created data.frame ready to be converted to an aftables-class object +#' with \code{\link{as_aftable}} and then an 'openxlsx' Workbook-class object #' with \code{\link{generate_workbook}}. #' #' @format A data.frame with 6 rows and 7 columns: @@ -16,9 +16,9 @@ #' } "demo_df" -#' A Demo 'a11ytables' Object +#' A Demo 'aftables' Object #' -#' A pre-created 'a11ytables' object ready to be converted to an 'openxlsx' +#' A pre-created 'aftables' object ready to be converted to an 'openxlsx' #' Workbook-class object with \code{\link{generate_workbook}}. #' #' @format A data.frame with 6 rows and 7 columns: @@ -31,12 +31,12 @@ #' \item{source}{Character. The origin of the data, if relevant.} #' \item{table}{List-column of data.frames (apart from the cover, which is a list) containing the statistical tables.} #' } -"demo_a11ytable" +"demo_aftable" #' A Demo 'Workbook' Object #' #' A pre-created 'openxlsx' Workbook'-class object generated from an -#' a11ytables-class object with \code{\link{generate_workbook}}. +#' aftables-class object with \code{\link{generate_workbook}}. #' #' @format An 'openxlsx' Workbook-class object with 5 sheets. "demo_workbook" @@ -48,8 +48,8 @@ #' favour of \code{\link{demo_df}}. #' #' A modified version of the mtcars dataset prepared into a data.frame structure -#' ready for coercion to an a11ytables-class object with -#' \code{\link{as_a11ytable}}. Uses a dataframe as input to the cover table; +#' ready for coercion to an aftables-class object with +#' \code{\link{as_aftable}}. Uses a dataframe as input to the cover table; #' \code{\link{mtcars_df}} uses a list as input to the cover table. #' #' @details @@ -80,8 +80,8 @@ #' favour of \code{\link{demo_df}}. #' #' A modified version of the mtcars dataset prepared into a data.frame structure -#' ready for coercion to an a11ytables-class object with -#' \code{\link{as_a11ytable}}. +#' ready for coercion to an aftables-class object with +#' \code{\link{as_aftable}}. #' #' @details #' Uses a list as input to the cover table (implemented in version 0.2), whereas diff --git a/R/utils-a11ytable.R b/R/utils-aftable.R similarity index 95% rename from R/utils-a11ytable.R rename to R/utils-aftable.R index 275570e..0f0d7b6 100644 --- a/R/utils-a11ytable.R +++ b/R/utils-aftable.R @@ -60,11 +60,11 @@ } -#' Validate an 'a11ytable' Object -#' @param text x. An object with class 'a11ytable', likely created with -#' \code{\link{create_a11ytable}}. +#' Validate an 'aftable' Object +#' @param text x. An object with class 'aftable', likely created with +#' \code{\link{create_aftable}}. #' @noRd -.validate_a11ytable <- function(x) { +.validate_aftable <- function(x) { names_req <- c( "tab_title", @@ -194,11 +194,11 @@ } -#' Warn if an 'a11ytable' Has a Non-critical Problem -#' @param text x. An object with class 'a11ytable', likely created with -#' \code{\link{create_a11ytable}}. +#' Warn if an 'aftable' Has a Non-critical Problem +#' @param text x. An object with class 'aftable', likely created with +#' \code{\link{create_aftable}}. #' @noRd -.warn_a11ytable <- function(content) { +.warn_aftable <- function(content) { # Warn about tab_title limitations diff --git a/R/workbook.R b/R/workbook.R index 62c7c3b..3c0892c 100644 --- a/R/workbook.R +++ b/R/workbook.R @@ -1,55 +1,55 @@ -#' Generate A Workbook Object From An 'a11ytable' +#' Generate A Workbook Object From An 'aftable' #' #' Populate an 'openxlsx' Workbook-class object with content from an -#' a11ytable-class object. In turn, the output can be passed to +#' aftable-class object. In turn, the output can be passed to #' \code{\link[openxlsx]{saveWorkbook}} from 'openxlsx' #' -#' @param a11ytable An a11ytable-class object created using -#' \code{\link{create_a11ytable}} (or \code{\link{as_a11ytable}}), which +#' @param aftable An aftable-class object created using +#' \code{\link{create_aftable}} (or \code{\link{as_aftable}}), which #' contains the data and information needed to create a workbook. #' #' @return A Workbook-class object. #' #' @examples -#' # Convert an a11ytable to a Workbook-class object -#' x <- generate_workbook(demo_a11ytable) +#' # Convert an aftable to a Workbook-class object +#' x <- generate_workbook(demo_aftable) #' class(x) #' #' # As above, using a compliant data.frame and the base pipe #' y <- demo_df |> -#' as_a11ytable() |> +#' as_aftable() |> #' generate_workbook() #' #' @export -generate_workbook <- function(a11ytable) { +generate_workbook <- function(aftable) { - if (!is_a11ytable(a11ytable)) { - stop("The object passed to argument 'content' must have class 'a11ytable'.") + if (!is_aftable(aftable)) { + stop("The object passed to argument 'content' must have class 'aftable'.") } # Create a table_name from tab_title (unique, no spaces, no punctuation) - a11ytable[["table_name"]] <- - gsub(" ", "_", tolower(trimws(a11ytable[["tab_title"]]))) - a11ytable[["table_name"]] <- - gsub("(?!_)[[:punct:]]", "", a11ytable[["table_name"]], perl = TRUE) + aftable[["table_name"]] <- + gsub(" ", "_", tolower(trimws(aftable[["tab_title"]]))) + aftable[["table_name"]] <- + gsub("(?!_)[[:punct:]]", "", aftable[["table_name"]], perl = TRUE) # Create workbook, add tabs, cover, contents (required for all workbooks) wb <- openxlsx::createWorkbook() - wb <- .add_tabs(wb, a11ytable) - wb <- .add_cover(wb, a11ytable) - wb <- .add_contents(wb, a11ytable) + wb <- .add_tabs(wb, aftable) + wb <- .add_cover(wb, aftable) + wb <- .add_contents(wb, aftable) # There won't always be a notes tab - if (any(a11ytable$sheet_type %in% "notes")) { - wb <- .add_notes(wb, a11ytable) + if (any(aftable$sheet_type %in% "notes")) { + wb <- .add_notes(wb, aftable) } # Iterable titles for tabs containing tables - table_sheets <- a11ytable[a11ytable$sheet_type == "tables", ][["table_name"]] + table_sheets <- aftable[aftable$sheet_type == "tables", ][["table_name"]] for (i in table_sheets) { - wb <- .add_tables(wb, a11ytable, table_name = i) + wb <- .add_tables(wb, aftable, table_name = i) } return(wb) diff --git a/README.Rmd b/README.Rmd index 4a6d303..fb1830c 100644 --- a/README.Rmd +++ b/README.Rmd @@ -13,20 +13,20 @@ knitr::opts_chunk$set( ) ``` -# {a11ytables} +# {aftables} [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![CRAN -status](https://www.r-pkg.org/badges/version/a11ytables)](https://CRAN.R-project.org/package=a11ytables) -[![R-CMD-check](https://github.com/best-practice-and-impact/a11ytables/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/best-practice-and-impact/a11ytables/actions/workflows/R-CMD-check.yaml) +status](https://www.r-pkg.org/badges/version/aftables)](https://CRAN.R-project.org/package=aftables) +[![R-CMD-check](https://github.com/best-practice-and-impact/aftables/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/best-practice-and-impact/aftables/actions/workflows/R-CMD-check.yaml) ## Purpose -An R package to help automatically create reproducible spreadsheets that adhere to the guidance on [releasing statistics in spreadsheets](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) from the UK government's [Analysis Function](https://analysisfunction.civilservice.gov.uk/), with a focus on accessibility ('a11y'). +An R package to help automatically create reproducible spreadsheets that adhere to the guidance on [releasing statistics in spreadsheets](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) from the UK government's [Analysis Function](https://analysisfunction.civilservice.gov.uk/), with a focus on accessibility. -Visit [the {a11ytables} website](https://best-practice-and-impact.github.io/a11ytables/) for documentation. +Visit [the {aftables} website](https://best-practice-and-impact.github.io/aftables/) for documentation. ## Accessibility @@ -34,24 +34,24 @@ This package is not yet capable of creating perfectly accessible spreadsheets bu ## Contribute -The package is under (opinionated) active development. Please see [the NEWS file](https://best-practice-and-impact.github.io/a11ytables/news/index.html) for the latest changes. +The package is under (opinionated) active development. Please see [the NEWS file](https://best-practice-and-impact.github.io/aftables/news/index.html) for the latest changes. -To contribute, please add [an issue](https://github.com/best-practice-and-impact/a11ytables/issues) or [a pull request](https://github.com/best-practice-and-impact/a11ytables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/a11ytables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/a11ytables/blob/main/.github/CONTRIBUTING.md) guidance. +To contribute, please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/aftables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance. ## Install -Install the package [from GitHub](https://github.com/best-practice-and-impact/a11ytables) using [{remotes}](https://remotes.r-lib.org/). +Install the package [from GitHub](https://github.com/best-practice-and-impact/aftables) using [{remotes}](https://remotes.r-lib.org/). ```{r install, eval=FALSE} install.packages("remotes") # if not already installed remotes::install_github( - repo = "best-practice-and-impact/a11ytables", # GitHub user/repository + repo = "best-practice-and-impact/aftables", # GitHub user/repository dependencies = TRUE, # install required/suggested packages build_vignettes = TRUE # generate vignette documentation ) -library(a11ytables) # attach package +library(aftables) # attach package ``` @@ -59,28 +59,28 @@ library(a11ytables) # attach package To create a spreadsheet: -1. Use `create_a11ytable()` +1. Use `create_aftable()` 1. Pass the output to `generate_workbook()` 1. Pass the output to `openxlsx::saveWorkbook()` -Run `?function_name` or visit [the package website](https://best-practice-and-impact.github.io/a11ytables/reference/index.html) for function documentation. For long-form documentation, [visit the package website](https://best-practice-and-impact.github.io/a11ytables/) or run `browseVignettes("a11ytables")` to read the: +Run `?function_name` or visit [the package website](https://best-practice-and-impact.github.io/aftables/reference/index.html) for function documentation. For long-form documentation, [visit the package website](https://best-practice-and-impact.github.io/aftables/) or run `browseVignettes("aftables")` to read the: -* [introductory vignette](https://best-practice-and-impact.github.io/a11ytables/articles/a11ytables.html) to get started -* [accessbility checklist vignette](https://best-practice-and-impact.github.io/a11ytables/articles/checklist.html) to see how the package complies with best-practice guidance -* [terminology vignette](https://best-practice-and-impact.github.io/a11ytables/articles/terminology) to understand the nomenclature of spreadsheet terms as used in this package -* [package structure vignette](https://best-practice-and-impact.github.io/a11ytables/articles/structure) to see how the package works under the hood +* [introductory vignette](https://best-practice-and-impact.github.io/aftables/articles/aftables.html) to get started +* [accessbility checklist vignette](https://best-practice-and-impact.github.io/aftables/articles/checklist.html) to see how the package complies with best-practice guidance +* [terminology vignette](https://best-practice-and-impact.github.io/aftables/articles/terminology) to understand the nomenclature of spreadsheet terms as used in this package +* [package structure vignette](https://best-practice-and-impact.github.io/aftables/articles/structure) to see how the package works under the hood -This package also includes [an RStudio Addin](https://rstudio.github.io/rstudioaddins/) that inserts pre-filled demo skeletons of the {a11ytables} workflow. +This package also includes [an RStudio Addin](https://rstudio.github.io/rstudioaddins/) that inserts pre-filled demo skeletons of the {aftables} workflow. ## Related projects -The ONS's Analysis Standards and Pipelines team has released [a Python package called 'gptables'](https://github.com/best-practice-and-impact/gptables). {a11ytables} is an independent effort that offers a native R solution that is very similar to gptables in its outputs, though there are some differences in implementation. +The ONS's Analysis Standards and Pipelines team has released [a Python package called 'gptables'](https://github.com/best-practice-and-impact/gptables). {aftables} is an independent effort that offers a native R solution that is very similar to gptables in its outputs, though there are some differences in implementation. -{a11ytables} can help you fulfil a [Reproducible Analytical Pipeline](https://analysisfunction.civilservice.gov.uk/support/reproducible-analytical-pipelines/) by automating the generation of compliant spreadsheets for publication. +{aftables} can help you fulfill a [Reproducible Analytical Pipeline](https://analysisfunction.civilservice.gov.uk/support/reproducible-analytical-pipelines/) by automating the generation of compliant spreadsheets for publication. ## Code of Conduct -Please note that the {a11ytables} project is released with a [Contributor Code of Conduct](https://best-practice-and-impact.github.io/a11ytables/CODE_OF_CONDUCT.html). +Please note that the {aftables} project is released with a [Contributor Code of Conduct](https://best-practice-and-impact.github.io/aftables/CODE_OF_CONDUCT.html). ## Copyright and Licensing diff --git a/README.md b/README.md index 39b68c8..657c822 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# {a11ytables} +# {aftables} @@ -9,8 +9,8 @@ state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![CRAN -status](https://www.r-pkg.org/badges/version/a11ytables)](https://CRAN.R-project.org/package=a11ytables) -[![R-CMD-check](https://github.com/best-practice-and-impact/a11ytables/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/best-practice-and-impact/a11ytables/actions/workflows/R-CMD-check.yaml) +status](https://www.r-pkg.org/badges/version/aftables)](https://CRAN.R-project.org/package=aftables) +[![R-CMD-check](https://github.com/best-practice-and-impact/aftables/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/best-practice-and-impact/aftables/actions/workflows/R-CMD-check.yaml) ## Purpose @@ -20,10 +20,10 @@ adhere to the guidance on [releasing statistics in spreadsheets](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) from the UK government’s [Analysis Function](https://analysisfunction.civilservice.gov.uk/), with a focus -on accessibility (‘a11y’). +on accessibility. -Visit [the {a11ytables} -website](https://best-practice-and-impact.github.io/a11ytables/) for +Visit [the {aftables} +website](https://best-practice-and-impact.github.io/aftables/) for documentation. ## Accessibility @@ -42,87 +42,87 @@ monitor use and the outputs produced. The package is under (opinionated) active development. Please see [the NEWS -file](https://best-practice-and-impact.github.io/a11ytables/news/index.html) +file](https://best-practice-and-impact.github.io/aftables/news/index.html) for the latest changes. To contribute, please add [an -issue](https://github.com/best-practice-and-impact/a11ytables/issues) or +issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull -request](https://github.com/best-practice-and-impact/a11ytables/pulls) +request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of -conduct](https://github.com/best-practice-and-impact/a11ytables/blob/main/CODE_OF_CONDUCT.md) +conduct](https://github.com/best-practice-and-impact/aftables/blob/main/CODE_OF_CONDUCT.md) and -[contributing](https://github.com/best-practice-and-impact/a11ytables/blob/main/.github/CONTRIBUTING.md) +[contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance. ## Install Install the package [from -GitHub](https://github.com/best-practice-and-impact/a11ytables) using +GitHub](https://github.com/best-practice-and-impact/aftables) using [{remotes}](https://remotes.r-lib.org/). ``` r install.packages("remotes") # if not already installed remotes::install_github( - repo = "best-practice-and-impact/a11ytables", # GitHub user/repository + repo = "best-practice-and-impact/aftables", # GitHub user/repository dependencies = TRUE, # install required/suggested packages build_vignettes = TRUE # generate vignette documentation ) -library(a11ytables) # attach package +library(aftables) # attach package ``` ## Use To create a spreadsheet: -1. Use `create_a11ytable()` +1. Use `create_aftable()` 2. Pass the output to `generate_workbook()` 3. Pass the output to `openxlsx::saveWorkbook()` Run `?function_name` or visit [the package -website](https://best-practice-and-impact.github.io/a11ytables/reference/index.html) +website](https://best-practice-and-impact.github.io/aftables/reference/index.html) for function documentation. For long-form documentation, [visit the -package website](https://best-practice-and-impact.github.io/a11ytables/) -or run `browseVignettes("a11ytables")` to read the: +package website](https://best-practice-and-impact.github.io/aftables/) +or run `browseVignettes("aftables")` to read the: - [introductory - vignette](https://best-practice-and-impact.github.io/a11ytables/articles/a11ytables.html) + vignette](https://best-practice-and-impact.github.io/aftables/articles/aftables.html) to get started - [accessbility checklist - vignette](https://best-practice-and-impact.github.io/a11ytables/articles/checklist.html) + vignette](https://best-practice-and-impact.github.io/aftables/articles/checklist.html) to see how the package complies with best-practice guidance - [terminology - vignette](https://best-practice-and-impact.github.io/a11ytables/articles/terminology) + vignette](https://best-practice-and-impact.github.io/aftables/articles/terminology) to understand the nomenclature of spreadsheet terms as used in this package - [package structure - vignette](https://best-practice-and-impact.github.io/a11ytables/articles/structure) + vignette](https://best-practice-and-impact.github.io/aftables/articles/structure) to see how the package works under the hood This package also includes [an RStudio Addin](https://rstudio.github.io/rstudioaddins/) that inserts pre-filled -demo skeletons of the {a11ytables} workflow. +demo skeletons of the {aftables} workflow. ## Related projects The ONS’s Analysis Standards and Pipelines team has released [a Python package called ‘gptables’](https://github.com/best-practice-and-impact/gptables). -{a11ytables} is an independent effort that offers a native R solution -that is very similar to gptables in its outputs, though there are some +{aftables} is an independent effort that offers a native R solution that +is very similar to gptables in its outputs, though there are some differences in implementation. -{a11ytables} can help you fulfil a [Reproducible Analytical +{aftables} can help you fulfill a [Reproducible Analytical Pipeline](https://analysisfunction.civilservice.gov.uk/support/reproducible-analytical-pipelines/) by automating the generation of compliant spreadsheets for publication. ## Code of Conduct -Please note that the {a11ytables} project is released with a -[Contributor Code of -Conduct](https://best-practice-and-impact.github.io/a11ytables/CODE_OF_CONDUCT.html). +Please note that the {aftables} project is released with a [Contributor +Code of +Conduct](https://best-practice-and-impact.github.io/aftables/CODE_OF_CONDUCT.html). ## Copyright and Licensing diff --git a/_pkgdown.yml b/_pkgdown.yml index 3b62bc5..5334d03 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,4 +1,4 @@ -url: https://best-practice-and-impact.github.io/a11ytables/ +url: https://best-practice-and-impact.github.io/aftables/ template: bootstrap: 5 @@ -19,16 +19,16 @@ footer: legal: © Crown Copyright, 2023 reference: - - title: "a11ytables" - desc: "Create, coerce and inspect a11ytable-class objects" + - title: "aftables" + desc: "Create, coerce and inspect aftable-class objects" contents: - - as_a11ytable - - create_a11ytable - - is_a11ytable - - summary.a11ytable - - tbl_sum.a11ytable + - as_aftable + - create_aftable + - is_aftable + - summary.aftable + - tbl_sum.aftable - title: "Workbooks" - desc: "Convert a11ytable- to Workbook-class objects" + desc: "Convert aftable- to Workbook-class objects" contents: generate_workbook - title: "Data" desc: "Demo datasets used in package examples" diff --git a/a11ytables.Rproj b/aftables.Rproj similarity index 100% rename from a11ytables.Rproj rename to aftables.Rproj diff --git a/cran-comments.md b/cran-comments.md new file mode 100644 index 0000000..858617d --- /dev/null +++ b/cran-comments.md @@ -0,0 +1,5 @@ +## R CMD check results + +0 errors | 0 warnings | 1 note + +* This is a new release. diff --git a/data-raw/data.R b/data-raw/data.R index 5fc4572..c6229de 100644 --- a/data-raw/data.R +++ b/data-raw/data.R @@ -1,7 +1,7 @@ # This file generates and writes demo datasets -# demo_df and demo_a11ytable (as of v0.3) --------------------------------- +# demo_df and demo_aftable (as of v0.3) --------------------------------- set.seed(1066) @@ -10,8 +10,8 @@ cover_list <- list( "Section 1" = c("First row of Section 1.", "Second row of Section 1."), "Section 2" = "The only row of Section 2.", "Section 3" = c( - "[Website](https://best-practice-and-impact.github.io/a11ytables/)", - "[Email address](mailto:fake.address@a11ytables.com)" + "[Website](https://best-practice-and-impact.github.io/aftables/)", + "[Email address](mailto:fake.address@aftables.com)" ) ) @@ -44,12 +44,11 @@ table_1_df <- data.frame( table_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10) -demo_a11ytable <- - a11ytables::create_a11ytable( +demo_aftable <- create_aftable( tab_titles = c("Cover", "Contents", "Notes", "Table_1", "Table_2"), sheet_types = c("cover", "contents", "notes", "tables", "tables"), sheet_titles = c( - "The 'a11ytables' Demo Workbook", + "The 'aftables' Demo Workbook", "Table of contents", "Notes", "Table_1: First Example Sheet", @@ -65,26 +64,26 @@ demo_a11ytable <- NA_character_, "A custom row.", c( - "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/a11ytables/)", + "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/aftables/)", "Second custom row." ), "A custom row." ), sources = c( rep(NA_character_, 3), - "[The Source Material, 2024.](https://best-practice-and-impact.github.io/a11ytables/)", + "[The Source Material, 2024.](https://best-practice-and-impact.github.io/aftables/)", "The Source Material, 2024." ), tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df) ) -demo_df <- as.data.frame(demo_a11ytable) +demo_df <- as.data.frame(demo_aftable) -demo_workbook <- generate_workbook(demo_a11ytable) +demo_workbook <- generate_workbook(demo_aftable) # Write to data/ usethis::use_data(demo_df, overwrite = TRUE) -usethis::use_data(demo_a11ytable, overwrite = TRUE) +usethis::use_data(demo_aftable, overwrite = TRUE) usethis::use_data(demo_workbook, overwrite = TRUE) @@ -110,7 +109,7 @@ cover_list <- ), "Properties" = "Suppressed values are replaced with the value '[c]'.", "Contact" = c( - "[Visit the website.](https://github.com/best-practice-and-impact/a11ytables)", + "[Visit the website.](https://github.com/best-practice-and-impact/aftables)", "[Email the team.](mailto:not-a-real-email-address@completely-fake.net)", "Telephone 0123456789" ) diff --git a/data/demo_a11ytable.rda b/data/demo_a11ytable.rda deleted file mode 100644 index b3b9840..0000000 Binary files a/data/demo_a11ytable.rda and /dev/null differ diff --git a/data/demo_aftable.rda b/data/demo_aftable.rda new file mode 100644 index 0000000..c15f7c9 Binary files /dev/null and b/data/demo_aftable.rda differ diff --git a/data/demo_df.rda b/data/demo_df.rda index 980d300..78dd85f 100644 Binary files a/data/demo_df.rda and b/data/demo_df.rda differ diff --git a/data/demo_workbook.rda b/data/demo_workbook.rda index 295619e..e5baff4 100644 Binary files a/data/demo_workbook.rda and b/data/demo_workbook.rda differ diff --git a/data/mtcars_df.rda b/data/mtcars_df.rda index 4fe4983..8bef866 100644 Binary files a/data/mtcars_df.rda and b/data/mtcars_df.rda differ diff --git a/data/mtcars_df2.rda b/data/mtcars_df2.rda index 0842ccb..70b2d9f 100644 Binary files a/data/mtcars_df2.rda and b/data/mtcars_df2.rda differ diff --git a/inst/CITATION b/inst/CITATION index cac3633..8229a53 100644 --- a/inst/CITATION +++ b/inst/CITATION @@ -1,16 +1,16 @@ -citHeader("To cite a11ytables in publications use:") +citHeader("To cite aftables in publications use:") citEntry( entry = "Manual", - title = "a11ytables: Create Spreadsheet Publications Following GSS Best Practice", + title = "aftables: Create Spreadsheet Publications Following GSS Best Practice", author = person(given = "Matt", family = "Dray", role = c("aut", "cre"), email = "mwdray@gmail.com"), year = "2021", organization = "Crown Copyright", - url = "https://github.com/best-practice-and-impact/a11ytables", + url = "https://github.com/best-practice-and-impact/aftables", textVersion = paste( "Dray M (2021)", - "a11ytables: Create Spreadsheet Publications Following GSS Best Practice,", + "aftables: Create Spreadsheet Publications Following GSS Best Practice,", "Crown Copyright,", - "https://github.com/best-practice-and-impact/a11ytables" + "https://github.com/best-practice-and-impact/aftables" ) ) diff --git a/inst/rstudio/addins.dcf b/inst/rstudio/addins.dcf index 447c04b..61aa786 100644 --- a/inst/rstudio/addins.dcf +++ b/inst/rstudio/addins.dcf @@ -1,12 +1,12 @@ -Name: Insert 'a11ytable' Template -Description: Insert at the cursor a template for create_a11ytable() from the - 'a11ytable' package, pre-filled with example information. -Binding: at_template_a11ytable +Name: Insert 'aftable' Template +Description: Insert at the cursor a template for create_aftable() from the + 'aftable' package, pre-filled with example information. +Binding: at_template_aftable Interactive: false -Name: Insert Full 'a11ytables' Template Workflow +Name: Insert Full 'aftables' Template Workflow Description: Insert at the cursor (a) templates for cover, contents and notes - tables, and (b) create_a11ytable(), which are all pre-filled with example + tables, and (b) create_aftable(), which are all pre-filled with example information. Binding: at_template_workflow Interactive: false diff --git a/man/a11ytables-package.Rd b/man/aftables-package.Rd similarity index 68% rename from man/a11ytables-package.Rd rename to man/aftables-package.Rd index 5093372..f4e3728 100644 --- a/man/a11ytables-package.Rd +++ b/man/aftables-package.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/a11ytables-package.R +% Please edit documentation in R/aftables-package.R \docType{package} -\name{a11ytables-package} -\alias{a11ytables} -\alias{a11ytables-package} -\title{a11ytables: Create Spreadsheet Publications Following Best Practice} +\name{aftables-package} +\alias{aftables} +\alias{aftables-package} +\title{aftables: Create Spreadsheet Publications Following Best Practice} \description{ \if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}} @@ -13,9 +13,9 @@ Generate spreadsheet publications that follow best practice guidance from the UK \seealso{ Useful links: \itemize{ - \item \url{https://best-practice-and-impact.github.io/a11ytables/} - \item \url{https://github.com/best-practice-and-impact/a11ytables} - \item Report bugs at \url{https://github.com/best-practice-and-impact/a11ytables/issues} + \item \url{https://best-practice-and-impact.github.io/aftables/} + \item \url{https://github.com/best-practice-and-impact/aftables} + \item Report bugs at \url{https://github.com/best-practice-and-impact/aftables/issues} } } diff --git a/man/as_a11ytable.Rd b/man/as_a11ytable.Rd deleted file mode 100644 index 304e66c..0000000 --- a/man/as_a11ytable.Rd +++ /dev/null @@ -1,26 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/a11ytable.R -\name{as_a11ytable} -\alias{as_a11ytable} -\alias{is_a11ytable} -\title{Coerce To An 'a11ytable' Object} -\usage{ -as_a11ytable(x) - -is_a11ytable(x) -} -\arguments{ -\item{x}{A data.frame object to coerce.} -} -\value{ -\code{as_a11ytable} returns an object of class a11ytable if possible. -\code{is_a11ytable} returns \code{TRUE} if the object has class -a11ytable, otherwise \code{FALSE}. -} -\description{ -Functions to check if an object is an a11ytable, or coerce it if possible. -} -\examples{ -is_a11ytable(demo_a11ytable) - -} diff --git a/man/as_aftable.Rd b/man/as_aftable.Rd new file mode 100644 index 0000000..6b2e007 --- /dev/null +++ b/man/as_aftable.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/aftable.R +\name{as_aftable} +\alias{as_aftable} +\alias{is_aftable} +\title{Coerce To An 'aftable' Object} +\usage{ +as_aftable(x) + +is_aftable(x) +} +\arguments{ +\item{x}{A data.frame object to coerce.} +} +\value{ +\code{as_aftable} returns an object of class aftable if possible. +\code{is_aftable} returns \code{TRUE} if the object has class +aftable, otherwise \code{FALSE}. +} +\description{ +Functions to check if an object is an aftable, or coerce it if possible. +} +\examples{ +is_aftable(demo_aftable) + +} diff --git a/man/at_template_a11ytable.Rd b/man/at_template_a11ytable.Rd deleted file mode 100644 index 92caaab..0000000 --- a/man/at_template_a11ytable.Rd +++ /dev/null @@ -1,12 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/addin.R -\name{at_template_a11ytable} -\alias{at_template_a11ytable} -\title{Insert Demo 'create_a11ytable' Template} -\usage{ -at_template_a11ytable() -} -\description{ -Insert at the cursor a template for \code{\link{create_a11ytable}} from the -'a11ytable' package, pre-filled with demo data. -} diff --git a/man/at_template_aftable.Rd b/man/at_template_aftable.Rd new file mode 100644 index 0000000..e444011 --- /dev/null +++ b/man/at_template_aftable.Rd @@ -0,0 +1,12 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/addin.R +\name{at_template_aftable} +\alias{at_template_aftable} +\title{Insert Demo 'create_aftable' Template} +\usage{ +at_template_aftable() +} +\description{ +Insert at the cursor a template for \code{\link{create_aftable}} from the +'aftable' package, pre-filled with demo data. +} diff --git a/man/at_template_workflow.Rd b/man/at_template_workflow.Rd index 9c1d2a4..a77835d 100644 --- a/man/at_template_workflow.Rd +++ b/man/at_template_workflow.Rd @@ -2,12 +2,12 @@ % Please edit documentation in R/addin.R \name{at_template_workflow} \alias{at_template_workflow} -\title{Insert Full Demo 'a11ytables' Template Workflow} +\title{Insert Full Demo 'aftables' Template Workflow} \usage{ at_template_workflow() } \description{ Insert at the cursor (a) demo templates for cover, contents and notes -tables, and (b) a call to \code{\link{create_a11ytable}} pre-filled with +tables, and (b) a call to \code{\link{create_aftable}} pre-filled with demo data. } diff --git a/man/create_a11ytable.Rd b/man/create_aftable.Rd similarity index 90% rename from man/create_a11ytable.Rd rename to man/create_aftable.Rd index 9ee5c50..6ca1e44 100644 --- a/man/create_a11ytable.Rd +++ b/man/create_aftable.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/a11ytable.R -\name{create_a11ytable} -\alias{create_a11ytable} -\title{Create An 'a11ytable' Object} +% Please edit documentation in R/aftable.R +\name{create_aftable} +\alias{create_aftable} +\title{Create An 'aftable' Object} \usage{ -create_a11ytable( +create_aftable( tab_titles, sheet_types = c("cover", "contents", "notes", "tables"), sheet_titles, @@ -48,10 +48,10 @@ type 'tables', but can also be used for sheet types 'contents' and supplied as a list), one per sheet. See details.} } \value{ -An object with classes 'a11ytable', 'tbl' and 'data.frame'. +An object with classes 'aftable', 'tbl' and 'data.frame'. } \description{ -Create a new a11ytable-class object, which is a special data.frame that +Create a new aftable-class object, which is a special data.frame that contains all the information needed in your output spreadsheet. In turn, the object created by this function can be used to populate an 'openxlsx' Workbook-class object with the function \code{\link{generate_workbook}}. @@ -113,8 +113,8 @@ cover_list <- list( "Section 1" = c("First row of Section 1.", "Second row of Section 1."), "Section 2" = "The only row of Section 2.", "Section 3" = c( - "[Website](https://best-practice-and-impact.github.io/a11ytables/)", - "[Email address](mailto:fake.address@a11ytables.com)" + "[Website](https://best-practice-and-impact.github.io/aftables/)", + "[Email address](mailto:fake.address@aftables.com)" ) ) @@ -147,14 +147,14 @@ table_1_df <- data.frame( table_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10) -# Create 'a11ytables' object +# Create 'aftables' object x <- - a11ytables::create_a11ytable( + aftables::create_aftable( tab_titles = c("Cover", "Contents", "Notes", "Table_1", "Table_2"), sheet_types = c("cover", "contents", "notes", "tables", "tables"), sheet_titles = c( - "The 'a11ytables' Demo Workbook", + "The 'aftables' Demo Workbook", "Table of contents", "Notes", "Table 1: First Example Sheet", @@ -170,21 +170,21 @@ x <- NA_character_, "A custom row.", c( - "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/a11ytables/)", + "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/aftables/)", "Second custom row." ), "A custom row." ), sources = c( rep(NA_character_, 3), - "[The Source Material, 2024.](https://best-practice-and-impact.github.io/a11ytables/)", + "[The Source Material, 2024.](https://best-practice-and-impact.github.io/aftables/)", "The Source Material, 2024." ), tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df) ) -# Test that 'a11ytable' is one of the object's classes -is_a11ytable(x) +# Test that 'aftable' is one of the object's classes +is_aftable(x) # Look at the structure of the object str(x, max.level = 2) diff --git a/man/demo_a11ytable.Rd b/man/demo_aftable.Rd similarity index 84% rename from man/demo_a11ytable.Rd rename to man/demo_aftable.Rd index 1b861bb..b935077 100644 --- a/man/demo_a11ytable.Rd +++ b/man/demo_aftable.Rd @@ -1,9 +1,9 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/data.R \docType{data} -\name{demo_a11ytable} -\alias{demo_a11ytable} -\title{A Demo 'a11ytables' Object} +\name{demo_aftable} +\alias{demo_aftable} +\title{A Demo 'aftables' Object} \format{ A data.frame with 6 rows and 7 columns: \describe{ @@ -17,10 +17,10 @@ A data.frame with 6 rows and 7 columns: } } \usage{ -demo_a11ytable +demo_aftable } \description{ -A pre-created 'a11ytables' object ready to be converted to an 'openxlsx' +A pre-created 'aftables' object ready to be converted to an 'openxlsx' Workbook-class object with \code{\link{generate_workbook}}. } \keyword{datasets} diff --git a/man/demo_df.Rd b/man/demo_df.Rd index 8acdf09..189695b 100644 --- a/man/demo_df.Rd +++ b/man/demo_df.Rd @@ -20,8 +20,8 @@ A data.frame with 6 rows and 7 columns: demo_df } \description{ -A pre-created data.frame ready to be converted to an a11ytables-class object -with \code{\link{as_a11ytable}} and then an 'openxlsx' Workbook-class object +A pre-created data.frame ready to be converted to an aftables-class object +with \code{\link{as_aftable}} and then an 'openxlsx' Workbook-class object with \code{\link{generate_workbook}}. } \keyword{datasets} diff --git a/man/demo_workbook.Rd b/man/demo_workbook.Rd index 3d6868a..83fa41b 100644 --- a/man/demo_workbook.Rd +++ b/man/demo_workbook.Rd @@ -12,6 +12,6 @@ demo_workbook } \description{ A pre-created 'openxlsx' Workbook'-class object generated from an -a11ytables-class object with \code{\link{generate_workbook}}. +aftables-class object with \code{\link{generate_workbook}}. } \keyword{datasets} diff --git a/man/generate_workbook.Rd b/man/generate_workbook.Rd index df620ad..274c329 100644 --- a/man/generate_workbook.Rd +++ b/man/generate_workbook.Rd @@ -2,13 +2,13 @@ % Please edit documentation in R/workbook.R \name{generate_workbook} \alias{generate_workbook} -\title{Generate A Workbook Object From An 'a11ytable'} +\title{Generate A Workbook Object From An 'aftable'} \usage{ -generate_workbook(a11ytable) +generate_workbook(aftable) } \arguments{ -\item{a11ytable}{An a11ytable-class object created using -\code{\link{create_a11ytable}} (or \code{\link{as_a11ytable}}), which +\item{aftable}{An aftable-class object created using +\code{\link{create_aftable}} (or \code{\link{as_aftable}}), which contains the data and information needed to create a workbook.} } \value{ @@ -16,17 +16,17 @@ A Workbook-class object. } \description{ Populate an 'openxlsx' Workbook-class object with content from an -a11ytable-class object. In turn, the output can be passed to +aftable-class object. In turn, the output can be passed to \code{\link[openxlsx]{saveWorkbook}} from 'openxlsx' } \examples{ -# Convert an a11ytable to a Workbook-class object -x <- generate_workbook(demo_a11ytable) +# Convert an aftable to a Workbook-class object +x <- generate_workbook(demo_aftable) class(x) # As above, using a compliant data.frame and the base pipe y <- demo_df |> - as_a11ytable() |> + as_aftable() |> generate_workbook() } diff --git a/man/mtcars_df.Rd b/man/mtcars_df.Rd index 8365ccd..c99d500 100644 --- a/man/mtcars_df.Rd +++ b/man/mtcars_df.Rd @@ -26,8 +26,8 @@ Superseded. mtcars_df and \code{\link{mtcars_df2}} have been superseded in favour of \code{\link{demo_df}}. A modified version of the mtcars dataset prepared into a data.frame structure -ready for coercion to an a11ytables-class object with -\code{\link{as_a11ytable}}. Uses a dataframe as input to the cover table; +ready for coercion to an aftables-class object with +\code{\link{as_aftable}}. Uses a dataframe as input to the cover table; \code{\link{mtcars_df}} uses a list as input to the cover table. } \details{ diff --git a/man/mtcars_df2.Rd b/man/mtcars_df2.Rd index f2a1c61..cc6f057 100644 --- a/man/mtcars_df2.Rd +++ b/man/mtcars_df2.Rd @@ -26,8 +26,8 @@ Superseded. \code{\link{mtcars_df}} and mtcars_df2 have been superseded in favour of \code{\link{demo_df}}. A modified version of the mtcars dataset prepared into a data.frame structure -ready for coercion to an a11ytables-class object with -\code{\link{as_a11ytable}}. +ready for coercion to an aftables-class object with +\code{\link{as_aftable}}. } \details{ Uses a list as input to the cover table (implemented in version 0.2), whereas diff --git a/man/summary.a11ytable.Rd b/man/summary.a11ytable.Rd deleted file mode 100644 index 946c712..0000000 --- a/man/summary.a11ytable.Rd +++ /dev/null @@ -1,26 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/a11ytable.R -\name{summary.a11ytable} -\alias{summary.a11ytable} -\title{Summarise An 'a11ytable' Object} -\usage{ -\method{summary}{a11ytable}(object, ...) -} -\arguments{ -\item{object}{An a11ytable-class object for which to get a summary.} - -\item{...}{Other arguments to pass.} -} -\description{ -A concise result summary of an a11ytable-class object to see information -about the sheet content. Shows a numbered list of sheets with each tab title, -sheet type and table dimensions. -} -\examples{ -# Print a concise summary of the a11ytable-class object -summary(demo_a11ytable) - -# Alternatively, look at the structure -str(demo_a11ytable, max.level = 2) - -} diff --git a/man/summary.aftable.Rd b/man/summary.aftable.Rd new file mode 100644 index 0000000..570816e --- /dev/null +++ b/man/summary.aftable.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/aftable.R +\name{summary.aftable} +\alias{summary.aftable} +\title{Summarise An 'aftable' Object} +\usage{ +\method{summary}{aftable}(object, ...) +} +\arguments{ +\item{object}{An aftable-class object for which to get a summary.} + +\item{...}{Other arguments to pass.} +} +\description{ +A concise result summary of an aftable-class object to see information +about the sheet content. Shows a numbered list of sheets with each tab title, +sheet type and table dimensions. +} +\examples{ +# Print a concise summary of the aftable-class object +summary(demo_aftable) + +# Alternatively, look at the structure +str(demo_aftable, max.level = 2) + +} diff --git a/man/tbl_sum.a11ytable.Rd b/man/tbl_sum.a11ytable.Rd deleted file mode 100644 index ea27a93..0000000 --- a/man/tbl_sum.a11ytable.Rd +++ /dev/null @@ -1,27 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/a11ytable.R -\name{tbl_sum.a11ytable} -\alias{tbl_sum.a11ytable} -\title{Provide A Succinct Summary Of An 'a11ytable' Object} -\usage{ -\method{tbl_sum}{a11ytable}(x, ...) -} -\arguments{ -\item{x}{An a11ytable-class object to summarise.} - -\item{...}{Other arguments to pass.} -} -\value{ -Named character vector. -} -\description{ -A brief text description of an a11ytable-class object. -} -\examples{ -# Print with description -print(demo_a11ytable) - -# Print description only (package 'tibble' must be installed) -tibble::tbl_sum(demo_a11ytable) - -} diff --git a/man/tbl_sum.aftable.Rd b/man/tbl_sum.aftable.Rd new file mode 100644 index 0000000..ebcb9e0 --- /dev/null +++ b/man/tbl_sum.aftable.Rd @@ -0,0 +1,27 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/aftable.R +\name{tbl_sum.aftable} +\alias{tbl_sum.aftable} +\title{Provide A Succinct Summary Of An 'aftable' Object} +\usage{ +\method{tbl_sum}{aftable}(x, ...) +} +\arguments{ +\item{x}{An aftable-class object to summarise.} + +\item{...}{Other arguments to pass.} +} +\value{ +Named character vector. +} +\description{ +A brief text description of an aftable-class object. +} +\examples{ +# Print with description +print(demo_aftable) + +# Print description only (package 'tibble' must be installed) +tibble::tbl_sum(demo_aftable) + +} diff --git a/tests/testthat.R b/tests/testthat.R index bbb7195..d60f9d0 100644 --- a/tests/testthat.R +++ b/tests/testthat.R @@ -1,4 +1,4 @@ library(testthat) -library(a11ytables) +library(aftables) -test_check("a11ytables") +test_check("aftables") diff --git a/tests/testthat/_snaps/a11ytable.md b/tests/testthat/_snaps/a11ytable.md index 1454303..902ddbe 100644 --- a/tests/testthat/_snaps/a11ytable.md +++ b/tests/testthat/_snaps/a11ytable.md @@ -1,6 +1,6 @@ # tbl output looks as intended - # a11ytable: 3 x 7 + # aftable: 3 x 7 tab_title sheet_type sheet_title blank_cells source custom_rows table 1 A cover A diff --git a/tests/testthat/_snaps/addins.md b/tests/testthat/_snaps/addins.md index e4f11d4..5865499 100644 --- a/tests/testthat/_snaps/addins.md +++ b/tests/testthat/_snaps/addins.md @@ -1,8 +1,8 @@ -# string_create_a11ytable skeleton is okay +# string_create_aftable skeleton is okay - [1] "my_a11ytable <-\n a11ytables::create_a11ytable(\n tab_titles = c(\"Cover\", \"Contents\", \"Notes\", \"Table_1\", \"Table_2\"),\n sheet_types = c(\"cover\", \"contents\", \"notes\", \"tables\", \"tables\"),\n sheet_titles = c(\n \"The 'a11ytables' Demo Workbook\",\n \"Table of contents\",\n \"Notes\",\n \"Table 1: First Example Sheet\",\n \"Table 2: Second Example Sheet\"\n ),\n blank_cells = c(\n rep(NA_character_, 3),\n \"Blank cells indicate that there's no note in that row.\",\n NA_character_\n ),\n custom_rows = list(\n NA_character_,\n \"A custom row in the Contents sheet.\",\n NA_character_,\n c(\n \"First custom row for Table 1.\",\n \"A second custom row [with a hyperlink.](https://best-practice-and-impact.github.io/a11ytables/)\"\n ),\n \"A custom row for Table 2\"\n ),\n sources = c(\n rep(NA_character_, 3),\n \"[The Source Material, 2024](https://best-practice-and-impact.github.io/a11ytables/)\",\n \"The Source Material, 2024\"\n ),\n tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df)\n )" + [1] "my_aftable <-\n aftables::create_aftable(\n tab_titles = c(\"Cover\", \"Contents\", \"Notes\", \"Table_1\", \"Table_2\"),\n sheet_types = c(\"cover\", \"contents\", \"notes\", \"tables\", \"tables\"),\n sheet_titles = c(\n \"The 'aftables' Demo Workbook\",\n \"Table of contents\",\n \"Notes\",\n \"Table 1: First Example Sheet\",\n \"Table 2: Second Example Sheet\"\n ),\n blank_cells = c(\n rep(NA_character_, 3),\n \"Blank cells indicate that there's no note in that row.\",\n NA_character_\n ),\n custom_rows = list(\n NA_character_,\n \"A custom row in the Contents sheet.\",\n NA_character_,\n c(\n \"First custom row for Table 1.\",\n \"A second custom row [with a hyperlink.](https://best-practice-and-impact.github.io/aftables/)\"\n ),\n \"A custom row for Table 2\"\n ),\n sources = c(\n rep(NA_character_, 3),\n \"[The Source Material, 2024](https://best-practice-and-impact.github.io/aftables/)\",\n \"The Source Material, 2024\"\n ),\n tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df)\n )" # string_tables_tibble skeleton is okay - [1] "cover_list <- list(\n \"Section 1\" = c(\"First row of Section 1.\", \"Second row of Section 1.\"),\n \"Section 2\" = \"The only row of Section 2.\",\n \"Section 3\" = c(\n \"[Website](https://best-practice-and-impact.github.io/a11ytables/)\",\n \"[Email address](mailto:fake.address@a11ytables.com)\"\n )\n)\n\ncontents_df <- data.frame(\n \"Sheet name\" = c(\"Notes\", \"Table 1\", \"Table 2\"),\n \"Sheet title\" = c(\n \"Notes used in this workbook\",\n \"First Example Sheet\",\n \"Second Example Sheet\"\n ),\n check.names = FALSE\n)\n\nnotes_df <- data.frame(\n \"Note number\" = paste(\"[note \", 1:2, \"]\"),\n \"Note text\" = c(\"First note.\", \"Second note.\"),\n check.names = FALSE\n)\n\ntable_1_df <- data.frame(\n Category = LETTERS[1:10],\n Numeric = 1:10,\n \"Numeric suppressed\" = c(1:4, \"[c]\", 6:9, \"[x]\"),\n \"Numeric thousands\" = abs(round(rnorm(10), 4) * 1e5),\n \"Numeric decimal\" = abs(round(rnorm(10), 5)),\n \"A column with a long name\" = 1:10,\n Notes = c(\"[note 1]\", rep(NA_character_, 4), \"[note 2]\", rep(NA_character_, 4)),\n check.names = FALSE\n)\n\ntable_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10)" + [1] "cover_list <- list(\n \"Section 1\" = c(\"First row of Section 1.\", \"Second row of Section 1.\"),\n \"Section 2\" = \"The only row of Section 2.\",\n \"Section 3\" = c(\n \"[Website](https://best-practice-and-impact.github.io/aftables/)\",\n \"[Email address](mailto:fake.address@aftables.com)\"\n )\n)\n\ncontents_df <- data.frame(\n \"Sheet name\" = c(\"Notes\", \"Table 1\", \"Table 2\"),\n \"Sheet title\" = c(\n \"Notes used in this workbook\",\n \"First Example Sheet\",\n \"Second Example Sheet\"\n ),\n check.names = FALSE\n)\n\nnotes_df <- data.frame(\n \"Note number\" = paste(\"[note \", 1:2, \"]\"),\n \"Note text\" = c(\"First note.\", \"Second note.\"),\n check.names = FALSE\n)\n\ntable_1_df <- data.frame(\n Category = LETTERS[1:10],\n Numeric = 1:10,\n \"Numeric suppressed\" = c(1:4, \"[c]\", 6:9, \"[x]\"),\n \"Numeric thousands\" = abs(round(rnorm(10), 4) * 1e5),\n \"Numeric decimal\" = abs(round(rnorm(10), 5)),\n \"A column with a long name\" = 1:10,\n Notes = c(\"[note 1]\", rep(NA_character_, 4), \"[note 2]\", rep(NA_character_, 4)),\n check.names = FALSE\n)\n\ntable_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10)" diff --git a/tests/testthat/test-a11ytable.R b/tests/testthat/test-a11ytable.R index c0b71d9..44a167e 100644 --- a/tests/testthat/test-a11ytable.R +++ b/tests/testthat/test-a11ytable.R @@ -1,11 +1,11 @@ -test_that("a11ytable can be created by hand (with list for cover)", { +test_that("aftable can be created by hand (with list for cover)", { # Uses demo_df, which has a list containing cover information in the # 'table' column. x <- suppressWarnings( - create_a11ytable( + create_aftable( tab_titles = demo_df$tab_title, sheet_types = demo_df$sheet_type, sheet_titles = demo_df$sheet_title, @@ -13,12 +13,12 @@ test_that("a11ytable can be created by hand (with list for cover)", { ) ) - expect_s3_class(x, class = "a11ytable") - expect_identical(class(x), c("a11ytable", "tbl", "data.frame")) + expect_s3_class(x, class = "aftable") + expect_identical(class(x), c("aftable", "tbl", "data.frame")) expect_error( suppressWarnings( - create_a11ytable( + create_aftable( tab_titles = demo_df$tab_title, sheet_types = "x", sheet_titles = demo_df$sheet_title, @@ -29,10 +29,10 @@ test_that("a11ytable can be created by hand (with list for cover)", { }) -test_that("a11ytable can be created by hand (with df for cover)", { +test_that("aftable can be created by hand (with df for cover)", { x <- suppressWarnings( - create_a11ytable( + create_aftable( tab_titles = demo_df$tab_title, sheet_types = demo_df$sheet_type, sheet_titles = demo_df$sheet_title, @@ -43,12 +43,12 @@ test_that("a11ytable can be created by hand (with df for cover)", { ) ) - expect_s3_class(x, class = "a11ytable") - expect_identical(class(x), c("a11ytable", "tbl", "data.frame")) + expect_s3_class(x, class = "aftable") + expect_identical(class(x), c("aftable", "tbl", "data.frame")) expect_error( suppressWarnings( - create_a11ytable( + create_aftable( tab_titles = demo_df$tab_title, sheet_types = "x", sheet_titles = demo_df$sheet_title, @@ -62,7 +62,7 @@ test_that("a11ytable can be created by hand (with df for cover)", { test_that("strings are not converted to factors", { x <- suppressWarnings( - create_a11ytable( + create_aftable( tab_titles = demo_df$tab_title, sheet_types = demo_df$sheet_type, sheet_titles = demo_df$sheet_title, @@ -79,70 +79,70 @@ test_that("strings are not converted to factors", { test_that("suitable objects can be coerced", { - x <- suppressWarnings(as_a11ytable(demo_df)) + x <- suppressWarnings(as_aftable(demo_df)) - expect_s3_class(x, class = "a11ytable") - expect_identical(class(x), c("a11ytable", "tbl", "data.frame")) + expect_s3_class(x, class = "aftable") + expect_identical(class(x), c("aftable", "tbl", "data.frame")) - expect_identical(is_a11ytable(x), TRUE) - expect_identical(is_a11ytable("x"), FALSE) + expect_identical(is_aftable(x), TRUE) + expect_identical(is_aftable("x"), FALSE) - expect_true(is_a11ytable(x)) - expect_false(is_a11ytable(mtcars)) + expect_true(is_aftable(x)) + expect_false(is_aftable(mtcars)) }) test_that("class validation works", { - expect_length(suppressWarnings(as_a11ytable(demo_df)), 7) + expect_length(suppressWarnings(as_aftable(demo_df)), 7) - expect_error(as_a11ytable(1)) - expect_error(as_a11ytable("x")) - expect_error(as_a11ytable(list())) - expect_error(as_a11ytable(data.frame())) + expect_error(as_aftable(1)) + expect_error(as_aftable("x")) + expect_error(as_aftable(list())) + expect_error(as_aftable(data.frame())) x <- demo_df names(x)[1] <- "foo" - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x[["table"]] <- as.character(x[["table"]]) - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df[, 1:4] - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df[1, ] - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x[x$sheet_type %in% c("cover", "contents"), "sheet_type"] <- "foo" - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x[x$tab_title == "Table_2", "sheet_type"] <- "foo" - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x$sheet_type <- NA_character_ - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x$custom_rows <- NA_character_ - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x$custom_rows <- rep(list(1), nrow(x)) - expect_error(as_a11ytable(x)) + expect_error(as_aftable(x)) x <- demo_df x[x$tab_title == "Table_2", "tab_title"] <- "Lorem_ipsum_dolor_sit_amet__consectetur_adipiscing" - expect_warning(as_a11ytable(x)) + expect_warning(as_aftable(x)) x <- demo_df x[x$tab_title == "Table_2", "tab_title"] <- "!?" - expect_warning(as_a11ytable(x)) + expect_warning(as_aftable(x)) x <- demo_df x[x$sheet_type == "notes", "table"][[1]] <- @@ -153,23 +153,23 @@ test_that("class validation works", { check.names = FALSE ) ) - expect_warning(as_a11ytable(x)) + expect_warning(as_aftable(x)) }) test_that("summary method works", { - x <- suppressWarnings(as_a11ytable(demo_df)) + x <- suppressWarnings(as_aftable(demo_df)) expect_output(summary(x)) }) -test_that("absence of note sheets doesn't prevent a11ytable formation", { +test_that("absence of note sheets doesn't prevent aftable formation", { df <- demo_df[demo_df$sheet_type != "notes", ] - suppressWarnings(x <- as_a11ytable(df)) + suppressWarnings(x <- as_aftable(df)) - expect_s3_class(x, "a11ytable") + expect_s3_class(x, "aftable") expect_s4_class(generate_workbook(x), "Workbook") }) @@ -181,7 +181,7 @@ test_that("tab_titles with starting numeral will error", { expect_error( with( demo_df, - create_a11ytable( + create_aftable( tab_titles = tab_title, sheet_types = sheet_type, sheet_titles = sheet_title, @@ -196,7 +196,7 @@ test_that("tab_titles with starting numeral will error", { test_that("non-conforming tab_titles are cleaned", { expect_warning( - create_a11ytable( + create_aftable( tab_titles = c("cover", "contents", "Table 2"), sheet_types = c("cover", "contents", "tables"), sheet_titles = c("Cover", "Contents", "Table"), @@ -219,7 +219,7 @@ test_that("tab_titles are unique", { expect_error( with( demo_df, - create_a11ytable( + create_aftable( tab_titles = tab_title, sheet_types = sheet_type, sheet_titles = sheet_title, @@ -232,7 +232,7 @@ test_that("tab_titles are unique", { test_that("tbl output looks as intended", { - x <- create_a11ytable( + x <- create_aftable( tab_titles = LETTERS[1:3], sheet_type = c("cover", "contents", "tables"), sheet_titles = LETTERS[1:3], @@ -244,25 +244,25 @@ test_that("tbl output looks as intended", { ) ) - expect_snapshot_output(as_a11ytable(x)) + expect_snapshot_output(as_aftable(x)) }) test_that("input other than data.frame is intercepted during validation", { - expect_error(.validate_a11ytable("x")) + expect_error(.validate_aftable("x")) x <- demo_df x[, "table"] <- "x" expect_error( - as_a11ytable(x), + as_aftable(x), "Column 'table' must be a listcol of data.frame objects." ) y <- subset(demo_df, select = -table) y[, "table"] <- list(rep(list("x"), nrow(y))) expect_error( - as_a11ytable(y), + as_aftable(y), "List-column 'table' must contain data.frame objects only." ) @@ -277,9 +277,9 @@ test_that("only one cover, contents, notes can be used", { notes_dupe <- rbind(demo_df, demo_df[demo_df$sheet_type == "notes", ]) - expect_error(as_a11ytable(cover_dupe)) - expect_error(as_a11ytable(contents_dupe)) - expect_error(as_a11ytable(notes_dupe)) + expect_error(as_aftable(cover_dupe)) + expect_error(as_aftable(contents_dupe)) + expect_error(as_aftable(notes_dupe)) }) @@ -294,10 +294,10 @@ test_that("NAs in certain columns cause failure", { table_na <- demo_df table_na$table <- NA_character_ - expect_error(as_a11ytable(tab_na)) - expect_error(as_a11ytable(type_na)) - expect_error(as_a11ytable(title_na)) - expect_error(as_a11ytable(table_na)) + expect_error(as_aftable(tab_na)) + expect_error(as_aftable(type_na)) + expect_error(as_aftable(title_na)) + expect_error(as_aftable(table_na)) }) @@ -307,7 +307,7 @@ test_that("Note mismatch is caught", { x[x$sheet_type == "contents", "table"][[1]] <- list(data.frame(x = c("x", "y"), y = c("x", "y"))) - expect_warning(as_a11ytable(x), "You have a 'notes' sheet") + expect_warning(as_aftable(x), "You have a 'notes' sheet") z <- demo_df[!demo_df$tab_title == "Table_2", ] z[z$sheet_type == "contents", "table"][[1]] <- @@ -320,7 +320,7 @@ test_that("Note mismatch is caught", { ) ) - expect_warning(as_a11ytable(z), "Some notes are in the notes sheet") + expect_warning(as_aftable(z), "Some notes are in the notes sheet") }) @@ -329,7 +329,7 @@ test_that("warning is raised if a source statement is missing", { demo_df[demo_df$tab_title == "Table_1", "source"] <- NA_character_ expect_warning( - as_a11ytable(demo_df), + as_aftable(demo_df), "One of your tables is missing a source statement." ) @@ -339,7 +339,7 @@ test_that("warning is raised if there's no blank cells but there is a reason", { demo_df[demo_df$tab_title == "Table_2", "blank_cells"] <- "x" expect_warning( - as_a11ytable(demo_df), + as_aftable(demo_df), "There's no blank cells in these tables" ) @@ -389,23 +389,23 @@ test_that("tab titles are cleaned and warnings provided", { x <- demo_df x[1, "tab_title"] <- long_title - expect_warning(as_a11ytable(x)) + expect_warning(as_aftable(x)) x <- demo_df x[1, "tab_title"] <- "Cover!" - expect_warning(as_a11ytable(x)) + expect_warning(as_aftable(x)) x <- demo_df x["tab_title"][5, ] <- long_title expect_warning( - .warn_a11ytable(x), + .warn_aftable(x), "Each tab_title must be shorter than 31 characters." ) x <- demo_df x["tab_title"][5, ] <- "Table-1!" expect_warning( - .warn_a11ytable(x), + .warn_aftable(x), "Each tab_title must contain only letters, numbers or underscores." ) @@ -414,13 +414,13 @@ test_that("tab titles are cleaned and warnings provided", { test_that("input column names are okay", { names(demo_df)[1] <- "x" - expect_error(as_a11ytable(demo_df)) + expect_error(as_aftable(demo_df)) }) test_that("character class columns are caught if not character class", { demo_df[, "sheet_type"] <- seq_len(nrow(demo_df)) - expect_error(as_a11ytable(demo_df)) + expect_error(as_aftable(demo_df)) }) diff --git a/tests/testthat/test-addins.R b/tests/testthat/test-addins.R index 23878c5..c7fd322 100644 --- a/tests/testthat/test-addins.R +++ b/tests/testthat/test-addins.R @@ -1,6 +1,6 @@ -test_that("string_create_a11ytable skeleton is okay", { - expect_snapshot_output(string_create_a11ytable()) +test_that("string_create_aftable skeleton is okay", { + expect_snapshot_output(string_create_aftable()) }) test_that("string_tables_tibble skeleton is okay", { diff --git a/tests/testthat/test-workbook.R b/tests/testthat/test-workbook.R index 52e37a4..977622a 100644 --- a/tests/testthat/test-workbook.R +++ b/tests/testthat/test-workbook.R @@ -1,15 +1,15 @@ test_that("workbook object is created", { - x <- suppressWarnings(generate_workbook(as_a11ytable(demo_df))) + x <- suppressWarnings(generate_workbook(as_aftable(demo_df))) expect_s4_class(x, class = "Workbook") expect_identical(class(x)[1], "Workbook") }) -test_that("a11ytable is passed", { +test_that("aftable is passed", { - x <- suppressWarnings(as_a11ytable(demo_df)) + x <- suppressWarnings(as_aftable(demo_df)) expect_error(generate_workbook("x")) expect_error(generate_workbook(1)) @@ -21,17 +21,17 @@ test_that("a11ytable is passed", { test_that(".stop_bad_input works as intended", { wb <- openxlsx::createWorkbook() - a11ytable <- as_a11ytable(demo_df) + aftable <- as_aftable(demo_df) - expect_error(.stop_bad_input("x", a11ytable, "cover")) - expect_error(.stop_bad_input(wb, a11ytable, 1)) + expect_error(.stop_bad_input("x", aftable, "cover")) + expect_error(.stop_bad_input(wb, aftable, 1)) }) test_that("hyperlinks are generated on the cover page", { # demo dataset has two hyperlinks on the cover - y <- suppressWarnings(generate_workbook(as_a11ytable(demo_df))) + y <- suppressWarnings(generate_workbook(as_aftable(demo_df))) expect_length(y$worksheets[[1]]$hyperlinks, 2) }) diff --git a/vignettes/a11ytables.Rmd b/vignettes/aftables.Rmd similarity index 69% rename from vignettes/a11ytables.Rmd rename to vignettes/aftables.Rmd index d085681..795da86 100644 --- a/vignettes/a11ytables.Rmd +++ b/vignettes/aftables.Rmd @@ -1,8 +1,8 @@ --- -title: "Introduction to {a11ytables}" +title: "Introduction to {aftables}" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{a11ytables} + %\VignetteIndexEntry{aftables} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -16,32 +16,32 @@ knitr::opts_chunk$set( ## Purpose -This vignette demonstrates how to use {a11ytables} to generate a spreadsheet output that automatically follows [best practice](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/). +This vignette demonstrates how to use {aftables} to generate a spreadsheet output that automatically follows [best practice](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/). ## Installation -Install the package [from GitHub](https://github.com/best-practice-and-impact/a11ytables) using [{remotes}](https://remotes.r-lib.org/). +Install the package [from GitHub](https://github.com/best-practice-and-impact/aftables) using [{remotes}](https://remotes.r-lib.org/). ```{r install, eval=FALSE} install.packages("remotes") # if not already installed -remotes::install_github("best-practice-and-impact/a11ytables") +remotes::install_github("best-practice-and-impact/aftables") ``` -The package depends on [{openxlsx}](https://ycphs.github.io/openxlsx/) and [{pillar}](https://pillar.r-lib.org/), which are also installed with {a11ytables}. +The package depends on [{openxlsx}](https://ycphs.github.io/openxlsx/) and [{pillar}](https://pillar.r-lib.org/), which are also installed with {aftables}. ## Workflow -Having installed the {a11ytables} package, there are three steps to generating a compliant spreadsheet: +Having installed the {aftables} package, there are three steps to generating a compliant spreadsheet: -1. Use `create_a11ytable()` to create a special dataframe (with class 'a11ytable') that contains all the content that will go in your spreadsheet -1. Pass the output to `generate_workbook()` to convert the a11ytable to {openxlsx}'s 'Workbook' class, which adds spreadsheet structure and styles +1. Use `create_aftable()` to create a special dataframe (with class 'aftable') that contains all the content that will go in your spreadsheet +1. Pass the output to `generate_workbook()` to convert the aftable to {openxlsx}'s 'Workbook' class, which adds spreadsheet structure and styles 1. Pass the output to `openxlsx::saveWorkbook()` to write out to an xlsx file (or `openxlsx::openXL()` to open a temporary copy) -You can use the package's [RStudio Addin](https://rstudio.github.io/rstudioaddins/), which is installed with {a11ytables}, to insert a pre-filled demo skeleton of this workflow (RStudio users only). +You can use the package's [RStudio Addin](https://rstudio.github.io/rstudioaddins/), which is installed with {aftables}, to insert a pre-filled demo skeleton of this workflow (RStudio users only). -### 1. Create an a11ytable +### 1. Create an aftable -Each argument to `create_a11ytable()` provides the information needed to construct each sheet in the spreadsheet. +Each argument to `create_aftable()` provides the information needed to construct each sheet in the spreadsheet. | Argument | Required | Type | Accepted values | Explanation | | :--- | :- | :--- | :--- | :------ | @@ -53,13 +53,13 @@ Each argument to `create_a11ytable()` provides the information needed to constru | `sources` | No | Character vector | | A sentence provides the source of the data found in each table (if applicable, likely only needed for sheets with `sheet_types` of 'table') | | `tables` | Yes | List of dataframes (although the cover sheet content can be provided as a list object) | | The main content for each sheet, expressed as flat ([probably tidy](https://www.jstatsoft.org/article/view/v059i10)) dataframes of rows and columns (though the cover can be a list) | -You can read more about these arguments and their requirements in the function's help pages, which you can access by running `?create_a11ytable` in the R console. See also the [terminology vignette](https://best-practice-and-impact.github.io/a11ytables/articles/terminology), `vignette("terminology", "a11ytables")`, for these terms and more. +You can read more about these arguments and their requirements in the function's help pages, which you can access by running `?create_aftable` in the R console. See also the [terminology vignette](https://best-practice-and-impact.github.io/aftables/articles/terminology), `vignette("terminology", "aftables")`, for these terms and more. #### Pre-prepare tables -Rather than pass a big list of dataframes directly to the `tables` argument of `create_a11ytable()`, it's preferable to prepare them first into their own named objects. +Rather than pass a big list of dataframes directly to the `tables` argument of `create_aftable()`, it's preferable to prepare them first into their own named objects. -Below are some demo tables that we will later pass to `create_a11ytable()`. I've used `tibble::tribble()` for human-readable row-by-row dataframe construction, but you can just use `data.frame()` if you want. +Below are some demo tables that we will later pass to `create_aftable()`. I've used `tibble::tribble()` for human-readable row-by-row dataframe construction, but you can just use `data.frame()` if you want. Note that you can use the RStudio Addin 'Insert table templates using 'tibble'' and 'Insert table templates using 'data.frame'' to insert a demo skeleton into your R script. @@ -72,8 +72,8 @@ cover_list <- list( "Section 1" = c("First row of Section 1.", "Second row of Section 1."), "Section 2" = "The only row of Section 2.", "Section 3" = c( - "[Website](https://best-practice-and-impact.github.io/a11ytables/)", - "[Email address](mailto:fake.address@a11ytables.com)" + "[Website](https://best-practice-and-impact.github.io/aftables/)", + "[Email address](mailto:fake.address@aftables.com)" ) ) ``` @@ -144,9 +144,9 @@ table_2_df See [the best practice guidance](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) for more information on how to present data in these tables. -#### Create a11ytable +#### Create aftable -Now we can construct an a11ytable by passing the required sheet elements as character vectors with `c()`—or a `list()` in the case of the `tables` and `custom_rows` arguments—to the `create_a11ytable()` function. +Now we can construct an aftable by passing the required sheet elements as character vectors with `c()`—or a `list()` in the case of the `tables` and `custom_rows` arguments—to the `create_aftable()` function. Note that: @@ -154,12 +154,12 @@ Note that: * you must use `NA_character_` wherever an element isn't required (e.g. there is no information about blank cells nor sources for the first three sheets) * you can insert a template of this demo using the package's RStudio Addin -```{r new-a11ytable} -my_a11ytable <- a11ytables::create_a11ytable( +```{r new-aftable} +my_aftable <- aftables::create_aftable( tab_titles = c("Cover", "Contents", "Notes", "Table 1", "Table_2"), sheet_types = c("cover", "contents", "notes", "tables", "tables"), sheet_titles = c( - "The 'a11ytables' Demo Workbook", + "The 'aftables' Demo Workbook", "Table of contents", "Notes", "Table 1: First Example Sheet", @@ -175,14 +175,14 @@ my_a11ytable <- a11ytables::create_a11ytable( NA_character_, "A custom row.", c( - "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/a11ytables/)", + "First custom row [with a hyperlink.](https://best-practice-and-impact.github.io/aftables/)", "Second custom row." ), "A custom row." ), sources = c( rep(NA_character_, 3), - "[The Source Material., 2024](https://best-practice-and-impact.github.io/a11ytables/)", + "[The Source Material., 2024](https://best-practice-and-impact.github.io/aftables/)", "The Source Material, 2024." ), tables = list(cover_list, contents_df, notes_df, table_1_df, table_2_df) @@ -193,24 +193,24 @@ The function will return errors or warnings if anything is missing or seems odd. Here's a preview of the object that was created: -```{r a11ytable-preview} -my_a11ytable +```{r aftable-preview} +my_aftable ``` -You can immediately tell that this is an a11ytable because it's the first word that's printed with the output. +You can immediately tell that this is an aftable because it's the first word that's printed with the output. -So our a11ytable is basically just a table with one row per sheet and one column per sheet element. In fact, it has class 'data.frame'/'tbl' along with 'a11ytable'. For convenience, you can also check for the a11ytable class with `is_a11ytable()`. +So our aftable is basically just a table with one row per sheet and one column per sheet element. In fact, it has class 'data.frame'/'tbl' along with 'aftable'. For convenience, you can also check for the aftable class with `is_aftable()`. -Note that `create_a11ytable()` is the preferred method for generating a11ytable-class objects, but it's also possible to convert a correctly-formatted, pre-built data.frame or tibble directly to an a11ytable with `as_a11ytable()`. +Note that `create_aftable()` is the preferred method for generating aftable-class objects, but it's also possible to convert a correctly-formatted, pre-built data.frame or tibble directly to an aftable with `as_aftable()`. ### 2. Convert to a workbook -We can use `generate_workbook()` to convert our a11ytable to an [{openxlsx}](https://ycphs.github.io/openxlsx/) Workbook-class object. +We can use `generate_workbook()` to convert our aftable to an [{openxlsx}](https://ycphs.github.io/openxlsx/) Workbook-class object. -This type of object adds information from each row of our a11ytable into separate sheets and applies other relevant structure, mark-up and styles for compliance with [the best practice guidance](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/). +This type of object adds information from each row of our aftable into separate sheets and applies other relevant structure, mark-up and styles for compliance with [the best practice guidance](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/). -```{r create-a11y-wb} -my_wb <- a11ytables::generate_workbook(my_a11ytable) +```{r create-af-wb} +my_wb <- aftables::generate_workbook(my_aftable) ```
Click for a preview of the Workbook object @@ -237,18 +237,18 @@ You could also open a temporary copy of the workbook with `openxlsx::openXL()`, The content of your output spreadsheet will end up looking something like this:
-Gif of a simple Excel workbook created using the a11ytables package, revealing tabs for cover, contents, notes and a table. +Gif of a simple Excel workbook created using the aftables package, revealing tabs for cover, contents, notes and a table.
You'll notice that various best-practice formatting (e.g. Arial size 12 font for body text) and mark-up (e.g. tables, donated by a marker in the lower-right corner of the lower-right cell of each one) have been applied throughout. -Note also that two 'pre-table' meta-elements were created automatically in the sheets that contain statistical tables, which you didn't need to supply to `create_a11ytable()`: (1) the number of tables and (2) the presence of notes. These are required for accessibility good practice. +Note also that two 'pre-table' meta-elements were created automatically in the sheets that contain statistical tables, which you didn't need to supply to `create_aftable()`: (1) the number of tables and (2) the presence of notes. These are required for accessibility good practice. #### Final tweaks -It's your responsibility to check and amend the output from {a11ytables} to ensure it meets users' accessibility needs. +It's your responsibility to check and amend the output from {aftables} to ensure it meets users' accessibility needs. -You can apply some final tweaks to the output xlsx file if the defaults don't quite meet your requirements (e.g. some column widths), though it's advisable to keep changes to a minimum for reproducibility purposes and because you may undo some of the compliant structuring and formatting that {a11ytables} provides. +You can apply some final tweaks to the output xlsx file if the defaults don't quite meet your requirements (e.g. some column widths), though it's advisable to keep changes to a minimum for reproducibility purposes and because you may undo some of the compliant structuring and formatting that {aftables} provides. At time of writing (v0.3.0) you might want to address manually some other [accessibility requirements](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) that are not yet covered by the package: @@ -256,8 +256,8 @@ At time of writing (v0.3.0) you might want to address manually some other [acces 3. Convert to an ODS file rather than the proprietary xlsx format 4. Various number-formatting issues, like padding decimal places with zeroes -We're trying to address a number of these limitations. Please [see the issues on GitHub](https://github.com/best-practice-and-impact/a11ytables/issues) for the current status. +We're trying to address a number of these limitations. Please [see the issues on GitHub](https://github.com/best-practice-and-impact/aftables/issues) for the current status. ## Contribute -To contribute, please add [an issue](https://github.com/best-practice-and-impact/a11ytables/issues) or [a pull request](https://github.com/best-practice-and-impact/a11ytables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/a11ytables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/a11ytables/blob/main/.github/CONTRIBUTING.md) guidance. +To contribute, please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/aftables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance. diff --git a/vignettes/checklist.Rmd b/vignettes/checklist.Rmd index f1bc553..05b6309 100644 --- a/vignettes/checklist.Rmd +++ b/vignettes/checklist.Rmd @@ -16,68 +16,68 @@ knitr::opts_chunk$set( ## Purpose -This vignette shows you how {a11ytables} meets accessibility best practice. +This vignette shows you how {aftables} meets accessibility best practice. ## Checklists -This page shows how the features of the {a11ytables} package meet the Analysis Function's ['Making spreadsheets accessible: checklist of the basics'](https://analysisfunction.civilservice.gov.uk/policy-store/making-spreadsheets-accessible-a-brief-checklist-of-the-basics/) guidance. +This page shows how the features of the {aftables} package meet the Analysis Function's ['Making spreadsheets accessible: checklist of the basics'](https://analysisfunction.civilservice.gov.uk/policy-store/making-spreadsheets-accessible-a-brief-checklist-of-the-basics/) guidance. -The assessments in the table below are based on generating an unedited output from a typical {a11ytables} workflow, i.e. use `create_a11ytable()` to make an a11ytable that's passed to `generate_workbook()` and then written with `openxlsx::saveWorkbook()`. +The assessments in the table below are based on generating an unedited output from a typical {aftables} workflow, i.e. use `create_aftable()` to make an aftable that's passed to `generate_workbook()` and then written with `openxlsx::saveWorkbook()`. There are several self-assessed indicators used in the 'status' column of the tables below: -* 'met' means that {a11ytables} contains a feature (or the absence of a feature) to help meet the requirement +* 'met' means that {aftables} contains a feature (or the absence of a feature) to help meet the requirement * 'user's responsibility' means that the user must make a decision about how to meet the requirement -* 'partly' means that {a11ytables} contains a feature to help meet the requirement, but the user may need to provide additional input -* 'not applicable' means the checklist item does not need to be met due to the way in which {a11ytables} works +* 'partly' means that {aftables} contains a feature to help meet the requirement, but the user may need to provide additional input +* 'not applicable' means the checklist item does not need to be met due to the way in which {aftables} works ### Tables | Description | Essential? | Status | Explanation | | :-- | :- | :- | :---- | | Mark up tables | Yes | Met | Provided automatically by `generate_workbook()` | -| Give tables meaningful names | No | Met | Unique table names are generated from the `tab_titles` argument in `create_a11ytable()` | -| Remove merged cells, split cells and nested tables | Yes | Met | {a11ytables} doesn't create these features | -| Remove blank rows and columns within tables | Yes | Partly/user’s responsibility | A warning is supplied to a user if cells in the table are blank but no explanation has been provided in the `blank_cells` column of the provided a11ytables object | +| Give tables meaningful names | No | Met | Unique table names are generated from the `tab_titles` argument in `create_aftable()` | +| Remove merged cells, split cells and nested tables | Yes | Met | {aftables} doesn't create these features | +| Remove blank rows and columns within tables | Yes | Partly/user’s responsibility | A warning is supplied to a user if cells in the table are blank but no explanation has been provided in the `blank_cells` column of the provided aftables object | | All tables should have one tagged header row | Yes | Met | R's data.frame class only allows for one header row, which must have unique names; the header row is tagged when marked-up as a table | -| Wrap text within cells | Yes | Met | `generate_workbook()` wraps content by default; there's a simple check in {a11ytables} to widen a column if it contains long strings | -| Avoid adding filters and freeze panes | No | Met | Filters and freezing aren't supported by {a11ytables} | -| Only leave cells with no data empty in certain circumstances | Yes | User's responsibility | The user should describe why there are blank cells in the `blank_cells` column of their a11ytables object | -| Avoid hiding rows or columns | No | Met | Hiding isn't supported by {a11ytables} | -| Columns should be a sensible width | No | Partly | {a11ytables} uses a fixed default column width for data tables (16), which is doubled (32) if the length of the content exceeds a threshold number of characters (50) | +| Wrap text within cells | Yes | Met | `generate_workbook()` wraps content by default; there's a simple check in {aftables} to widen a column if it contains long strings | +| Avoid adding filters and freeze panes | No | Met | Filters and freezing aren't supported by {aftables} | +| Only leave cells with no data empty in certain circumstances | Yes | User's responsibility | The user should describe why there are blank cells in the `blank_cells` column of their aftables object | +| Avoid hiding rows or columns | No | Met | Hiding isn't supported by {aftables} | +| Columns should be a sensible width | No | Partly | {aftables} uses a fixed default column width for data tables (16), which is doubled (32) if the length of the content exceeds a threshold number of characters (50) | ### Footnotes | Description | Essential? | Status | Explanation | | :-- | :- | :- | :---- | -| Do not use symbols or superscript to signpost to notes | Yes | Met/user’s responsibility | Notes are detected automatically as digits in square brackets; superscript is not supported by {a11ytables} | +| Do not use symbols or superscript to signpost to notes | Yes | Met/user’s responsibility | Notes are detected automatically as digits in square brackets; superscript is not supported by {aftables} | | Use the word 'note' when referring to footnotes | No | User’s responsibility | Notes are detected in the form '[note 1]'; the user should be consistent about this wording | | Avoid putting note markers in specific cells | No | User’s responsibility | Columns named 'Notes' and note markers in column headers are detected, the user should not put these elsewhere | -| Put note text in a notes table on a notes worksheet | No | Met | `create_a11ytable()` expects the `sheet_type` 'notes' | +| Put note text in a notes table on a notes worksheet | No | Met | `create_aftable()` expects the `sheet_type` 'notes' | ### Formatting | Description | Essential? | Status | Explanation | | :-- | :- | :- | :---- | -| All written content needs to meet the accessibility guidelines | No | User's responsibility | {a11ytables} does not check the validity of user-supplied text | -| Links must be accessible | Yes | User's responsibility | {a11ytables} does not check the validity of user-supplied text | +| All written content needs to meet the accessibility guidelines | No | User's responsibility | {aftables} does not check the validity of user-supplied text | +| Links must be accessible | Yes | User's responsibility | {aftables} does not check the validity of user-supplied text | | Format text to make it accessible | No | Met | `generate_workbook()` auto-formats the text | -| All worksheets should have descriptive titles which are properly tagged and formatted | Yes | Partly/user’s responsibility | {a11ytables} does not check user-supplied text nor data; the package handles formatting but not yet mark-up for headings | -| Avoid using symbols in general | No | User's responsibility | {a11ytables} does not check the validity of user-supplied text | -| Do not use headers and footers, floating text boxes or floating toolbars | Yes | Met | These features aren't supported by {a11ytables} | -| Do not use visual devices to divide data regions | No | Met | Colours and patterns aren't supported by {a11ytables} | -| Do not use a background fill | No | Met | Fills aren't supported by {a11ytables} | -| Do not use colour as the only way to convey a message | Yes | Met | Colour is not supported by {a11ytables} | -| When using colour for emphasis check the contrast | Yes | Not applicable | Colour is not supported by {a11ytables}, so a check is not required | -| Avoid images in spreadsheets | No | Met | Images aren't supported by {a11ytables} | -| Remove macros | No | Met | Macros aren't supported by {a11ytables} | +| All worksheets should have descriptive titles which are properly tagged and formatted | Yes | Partly/user’s responsibility | {aftables} does not check user-supplied text nor data; the package handles formatting but not yet mark-up for headings | +| Avoid using symbols in general | No | User's responsibility | {aftables} does not check the validity of user-supplied text | +| Do not use headers and footers, floating text boxes or floating toolbars | Yes | Met | These features aren't supported by {aftables} | +| Do not use visual devices to divide data regions | No | Met | Colours and patterns aren't supported by {aftables} | +| Do not use a background fill | No | Met | Fills aren't supported by {aftables} | +| Do not use colour as the only way to convey a message | Yes | Met | Colour is not supported by {aftables} | +| When using colour for emphasis check the contrast | Yes | Not applicable | Colour is not supported by {aftables}, so a check is not required | +| Avoid images in spreadsheets | No | Met | Images aren't supported by {aftables} | +| Remove macros | No | Met | Macros aren't supported by {aftables} | ### Structure | Description | Essential? | Status | Explanation | | :-- | :- | :- | :---- | -| Give worksheets unique names or numbers | Yes | User's responsibility | Supply `tab_titles` to `create_a11ytable()`, which gives a warning if any names match | -| Remove blank worksheets | Yes | Met | `create_a11ytable()` will error if expected argument content is missing | +| Give worksheets unique names or numbers | Yes | User's responsibility | Supply `tab_titles` to `create_aftable()`, which gives a warning if any names match | +| Remove blank worksheets | Yes | Met | `create_aftable()` will error if expected argument content is missing | | Use cells in column A wisely | Yes | Met | `generate_workbook()` inserts the sheet title, table count, notes statement, source statement and tables into column A by default | | Position tables against the left-hand edges of each sheet | Yes | Met | `generate_workbook()` inserts automatically the tables into column A | | Avoid putting content below a table | No | Met | `generate_workbook()` adds information to rows above tables only | @@ -87,11 +87,11 @@ There are several self-assessed indicators used in the 'status' column of the ta | Description | Essential? | Status | Explanation | | :-- | :- | :- | :---- | -| Run a spelling and grammar check | Yes | User's responsibility | These checks aren't supported by {a11ytables}; the user should check using their own software | -| Use the accessibility checker | No | User's responsibility | These checks aren't supported by {a11ytables}; the user should check using their own software | -| Add document information | Yes | User's responsibility | Not yet possible with {a11ytables}; users must do this manually | +| Run a spelling and grammar check | Yes | User's responsibility | These checks aren't supported by {aftables}; the user should check using their own software | +| Use the accessibility checker | No | User's responsibility | These checks aren't supported by {aftables}; the user should check using their own software | +| Add document information | Yes | User's responsibility | Not yet possible with {aftables}; users must do this manually | | Ensure the cursor is in cell A1 of the first worksheet when doing your final save | Yes | Met | Occurs automatically | # Contribute -To contribute, please add [an issue](https://github.com/best-practice-and-impact/a11ytables/issues) or [a pull request](https://github.com/best-practice-and-impact/a11ytables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/a11ytables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/a11ytables/blob/main/.github/CONTRIBUTING.md) guidance. +To contribute, please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/aftables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance. diff --git a/vignettes/structure.Rmd b/vignettes/structure.Rmd index 9ce6241..315839a 100644 --- a/vignettes/structure.Rmd +++ b/vignettes/structure.Rmd @@ -20,95 +20,95 @@ This vignette is aimed at developers who want to understand the package better a # Overview -There are only two main user-facing functions in {a11ytables}: +There are only two main user-facing functions in {aftables}: -* `create_a11ytable()` to create a data.frame object (with an additional 'a11ytable' S3 class) filled with all the information needed to create a spreadsheet output, as well as check the validity of the structure and provide errors or warnings -* `generate_workbook()` to convert the output from `create_a11ytable()` to an [{openxlsx}](https://ycphs.github.io/openxlsx/) Workbook-class object, ready for writing to an xlsx file with `openxlsx::saveWorkbook()` +* `create_aftable()` to create a data.frame object (with an additional 'aftable' S3 class) filled with all the information needed to create a spreadsheet output, as well as check the validity of the structure and provide errors or warnings +* `generate_workbook()` to convert the output from `create_aftable()` to an [{openxlsx}](https://ycphs.github.io/openxlsx/) Workbook-class object, ready for writing to an xlsx file with `openxlsx::saveWorkbook()` This simplicity is a feature, not a bug. It's designed to greatly simplify the process of creating compliant spreadsheets. The package does the hard work of making the outputs compliant so the user spends less time dealing with it. This vignette provides a quick look at what's happening 'under the hood' in these functions. -Please add [an issue](https://github.com/best-practice-and-impact/a11ytables/issues) to the package's GitHub repository if you would like any of this explanation to be expanded, or provide a solution in [a pull request](https://github.com/best-practice-and-impact/a11ytables/pulls). +Please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) to the package's GitHub repository if you would like any of this explanation to be expanded, or provide a solution in [a pull request](https://github.com/best-practice-and-impact/aftables/pulls). # Files First it's worth explaining how the source files are laid out. There are four major groups of scripts in the `R/` directory of the package: -1. Code to make a11ytable-class objects: `a11ytable.R` and `utils-a11ytable.R` contain code for handling the a11ytable class, most importantly the `create_a11ytable()` function, but also coercion with `as_a11ytable()`, checking with `is_a11ytable()`, a `summary()` method and a `print()` method, which takes advantage of [the {pillar} package](https://github.com/r-lib/pillar) for prettier outputs. +1. Code to make aftable-class objects: `aftable.R` and `utils-aftable.R` contain code for handling the aftable class, most importantly the `create_aftable()` function, but also coercion with `as_aftable()`, checking with `is_aftable()`, a `summary()` method and a `print()` method, which takes advantage of [the {pillar} package](https://github.com/r-lib/pillar) for prettier outputs. 2. Code to make Workbook-class objects: `workbook.R`, `utils-workbook.R` and `utils-workbook-style.R` contain the code for creating and styling a Workbook-class object with the `generate_workbook()` function. 3. Code to produce demo datasets: `data.R` contains the documentation for demo datasets, which are created in the `data-raw/` directory with the files stored in the `data/` directory. 4. Code that creates the RStudio Addin: `addin.R` and `utils-addin.R` contain code for the [RStudio Addin](https://rstudio.github.io/rstudioaddins/) (the .dcf file for which is in the `inst/rstudio/` directory). -You'll also find the `a11ytables-package.R` file in the `R/` directory, which provides a package-level help page derived from the DESCRIPTION file when `?a11ytables` is run by the user. It doesn't need to be edited. +You'll also find the `aftables-package.R` file in the `R/` directory, which provides a package-level help page derived from the DESCRIPTION file when `?aftables` is run by the user. It doesn't need to be edited. # Code -This sections below focus on the `create_a11ytable()` and `generate_workbook()` functions, which are the primary and most complex functions in the package. +This sections below focus on the `create_aftable()` and `generate_workbook()` functions, which are the primary and most complex functions in the package. The code that underpins these functions is modularised to aid with bug-catching and testing, but also to make it easier for developers to understand how the code fits together. Internal sub-functions are consistently-named and begin with verbs, which should help you better understand their purpose. -Note that {a11ytables} uses a convention that internal functions (i.e. those not presented to the user, but accessed via the `:::` qualifier) are prefixed with a period (i.e. `.f()`) to make it clearer that they are internal to the package. The exported user-facing functions do not use a leading period. +Note that {aftables} uses a convention that internal functions (i.e. those not presented to the user, but accessed via the `:::` qualifier) are prefixed with a period (i.e. `.f()`) to make it clearer that they are internal to the package. The exported user-facing functions do not use a leading period. -## To create a11ytables +## To create aftables -Actually, `create_a11ytable()` itself only does one thing: it takes user inputs from the arguments and combines them into a dataframe. It then passes this off to the most important function in the package, `as_a11ytable()`, which is responsible for coercing the dataframe to a11ytable class and performing checks on its content. +Actually, `create_aftable()` itself only does one thing: it takes user inputs from the arguments and combines them into a dataframe. It then passes this off to the most important function in the package, `as_aftable()`, which is responsible for coercing the dataframe to aftable class and performing checks on its content. -Basically, `as_a11ytable()` creates an S3-class object with classes 'data.frame' and 'tbl' (i.e. [tibble](https://tibble.tidyverse.org/)) and an additional 'a11ytable' class. +Basically, `as_aftable()` creates an S3-class object with classes 'data.frame' and 'tbl' (i.e. [tibble](https://tibble.tidyverse.org/)) and an additional 'aftable' class. ```{r class-demo} -library(a11ytables) -my_a11ytable <- as_a11ytable(demo_df) -class(my_a11ytable) +library(aftables) +my_aftable <- as_aftable(demo_df) +class(my_aftable) ``` The object can be manipulated like a 'normal' dataframe and---thanks to the {pillar} package and the tbl class---it can be printed in compact form without the need for the whole of the {tibble} package to be imported. ```{r print-demo} -my_a11ytable +my_aftable ``` Compare this to its appearance as a regular data.frame, which is trickier to understand: ```{r df-demo-no-eval} -as.data.frame(my_a11ytable) +as.data.frame(my_aftable) ``` -Within `as_a11ytable()` itself are two major functions that help ensure proper construction of an a11ytable object: +Within `as_aftable()` itself are two major functions that help ensure proper construction of an aftable object: -* `.validate_a11ytable()` will generate errors if basic structural expectations of an a11ytable aren't met (e.g. if 'cover', 'contents' or 'notes' have been provided more than once to the `sheet_type` argument) -* `.warn_a11ytable()` checks for things that the user may have forgotten and prints warnings about them (e.g. if 5 notes are declared in the notes sheet but there are fewer in the tables themselves) +* `.validate_aftable()` will generate errors if basic structural expectations of an aftable aren't met (e.g. if 'cover', 'contents' or 'notes' have been provided more than once to the `sheet_type` argument) +* `.warn_aftable()` checks for things that the user may have forgotten and prints warnings about them (e.g. if 5 notes are declared in the notes sheet but there are fewer in the tables themselves) -Advanced users can create a correctly-formatted data.frame on the fly and convert it to an a11ytable with `as_a11ytable()` directly. The `as_a11ytable()` function mainly exists to make testing easier, i.e. you can pass to it the pre-prepared `demo_df` dataset. +Advanced users can create a correctly-formatted data.frame on the fly and convert it to an aftable with `as_aftable()` directly. The `as_aftable()` function mainly exists to make testing easier, i.e. you can pass to it the pre-prepared `demo_df` dataset. ### Methods -There's a few methods for a11ytables that are also found in `R/a11ytables.R`. +There's a few methods for aftables that are also found in `R/aftables.R`. -`is_a11ytable()` is a classic logical test that checks for the a11ytable class in the object provided to it. +`is_aftable()` is a classic logical test that checks for the aftable class in the object provided to it. ```{r is-demo} -is_a11ytable(my_a11ytable) +is_aftable(my_aftable) ``` -The `summary()` method prints a very simple overview of a provided a11ytable. +The `summary()` method prints a very simple overview of a provided aftable. ```{r summary-demo} -summary(my_a11ytable) +summary(my_aftable) ``` -The `tbl_sum()` method is provided via the {pillar} package, with the goal of providing a bespoke header to the printed a11ytable. +The `tbl_sum()` method is provided via the {pillar} package, with the goal of providing a bespoke header to the printed aftable. ```{r tbl-sum-demo} -pillar::tbl_sum(my_a11ytable) +pillar::tbl_sum(my_aftable) ``` ## To create workbooks -The `generate_workbook()` function sets up an [{openxlsx}](https://ycphs.github.io/openxlsx/) Workbook-class object and fills it by iterating over a user-supplied the a11ytable-class object. +The `generate_workbook()` function sets up an [{openxlsx}](https://ycphs.github.io/openxlsx/) Workbook-class object and fills it by iterating over a user-supplied the aftable-class object. ```{r wb-class} -my_wb <- generate_workbook(my_a11ytable) +my_wb <- generate_workbook(my_aftable) class(my_wb) ``` @@ -122,14 +122,14 @@ Several internal sub-functions within `generate_workbook()`---`.add_*()`, `.inse ### Add sheets -A Workbook-class object is first created with `openxlsx::createWorkbook()` and then sheets are added based on the contents of the user-supplied a11ytable. +A Workbook-class object is first created with `openxlsx::createWorkbook()` and then sheets are added based on the contents of the user-supplied aftable. The following functions add sheets and sheet elements into the workbook: -* `.add_tabs()` adds the required number of tabs into the workbook with `openxlsx::addWorksheet()` (as per the `tab_title` column of the supplied a11ytable) -* `.add_cover()` and `.add_contents()` add the information needed for the cover and contents sheets (as per the required 'cover' and 'contents' supplied in the `sheet_type` column of an a11ytable) -* `.add_notes()` if a notes sheet exists (i.e. a row in the supplied a11ytable with a `sheet_type` of 'notes') -* `.add_table()` adds sheets for each statistical table (as per rows of supplied a11ytable with a `sheet_type` of 'table') +* `.add_tabs()` adds the required number of tabs into the workbook with `openxlsx::addWorksheet()` (as per the `tab_title` column of the supplied aftable) +* `.add_cover()` and `.add_contents()` add the information needed for the cover and contents sheets (as per the required 'cover' and 'contents' supplied in the `sheet_type` column of an aftable) +* `.add_notes()` if a notes sheet exists (i.e. a row in the supplied aftable with a `sheet_type` of 'notes') +* `.add_table()` adds sheets for each statistical table (as per rows of supplied aftable with a `sheet_type` of 'table') As sheets are added, content is inserted and styles are applied with the: @@ -138,20 +138,20 @@ As sheets are added, content is inserted and styles are applied with the: #### Insert sheet elements -There are several `.insert_*()` functions that add information to each sheet depending on the `sheet_type` of the provided a11ytable, as well as the content, if any, of its `sheet_title`, `blank_cells`, `source` and `table` columns. +There are several `.insert_*()` functions that add information to each sheet depending on the `sheet_type` of the provided aftable, as well as the content, if any, of its `sheet_title`, `blank_cells`, `source` and `table` columns. The following functions insert 'pre-table' elements in this order: * `.insert_title()` to place the sheet title in cell A1 * `.insert_table_count()` to add a statement about the number of tables in the sheet -* `.insert_notes_statement()` if a `sheet_type` of 'notes' is provided in the user's a11ytable -* `.insert_blanks_message()` if content is provided in the `blanks_cells` column of the user's a11ytable -* `.insert_custom_rows()` if content is provided in the `custom_rows` column of the user's a11ytable -* `.insert_source()` if content is provided in the `source` column of the user's a11ytable +* `.insert_notes_statement()` if a `sheet_type` of 'notes' is provided in the user's aftable +* `.insert_blanks_message()` if content is provided in the `blanks_cells` column of the user's aftable +* `.insert_custom_rows()` if content is provided in the `custom_rows` column of the user's aftable +* `.insert_source()` if content is provided in the `source` column of the user's aftable -A table of data is added under the metadata with `.insert_table()`, which is provided in the `table` column of the user's a11ytable object. +A table of data is added under the metadata with `.insert_table()`, which is provided in the `table` column of the user's aftable object. -The exact `.insert_*()` functions called depend on the `sheet_type` declared in the a11ytable: +The exact `.insert_*()` functions called depend on the `sheet_type` declared in the aftable: * meta sheets (cover, contents and notes) need only `.insert_title()` and `.insert_table_count()` * statistical tables may also require `.insert_blanks_message()`, `.insert_custom_rows()` and `.insert_source()` if the relevant content is provided by the user, as well as `.insert_notes_statement()` if there are notes @@ -162,7 +162,7 @@ For example, if all the elements are supplied, then the table would begin in row #### Apply styles -There are a few `.style_*()` functions that create styles and apply them on the basis of the `sheet_type` provided in the a11ytable. +There are a few `.style_*()` functions that create styles and apply them on the basis of the `sheet_type` provided in the aftable. * `.style_create()` creates an easily-referenced lookup of styles, which is created with `openxlsx::createStyle()` * `.style_workbook()` applies defaults for _the whole workbook_ (i.e. to set the font style to Arial size 12) @@ -171,4 +171,4 @@ There are a few `.style_*()` functions that create styles and apply them on the # Contribute -To contribute, please add [an issue](https://github.com/best-practice-and-impact/a11ytables/issues) or [a pull request](https://github.com/best-practice-and-impact/a11ytables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/a11ytables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/a11ytables/blob/main/.github/CONTRIBUTING.md) guidance. +To contribute, please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/aftables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance. diff --git a/vignettes/terminology.Rmd b/vignettes/terminology.Rmd index 72f93b5..9dfe486 100644 --- a/vignettes/terminology.Rmd +++ b/vignettes/terminology.Rmd @@ -16,7 +16,7 @@ knitr::opts_chunk$set( # Purpose -This vignette provides a quick lookup of spreadsheet nomenclature, as used in the {a11ytables} package. +This vignette provides a quick lookup of spreadsheet nomenclature, as used in the {aftables} package. # Terminology @@ -44,10 +44,10 @@ _Sheets_ themselves are composed of inserted _elements_ that appear in the follo # Example -This is an example xlsx output from the {a11ytables} package: +This is an example xlsx output from the {aftables} package:
-A spreadsheet produced by the a11ytables package. Four things have been marked with numbers. 1 points to the current tab, named Table_1. 2 points to the sheet title. 3 points to four rows of elements below the title and below the table, which refer to the number of tables in the sheet, the presence of notes, the meaning of blank cells and the data source. 4 points to the table. +A spreadsheet produced by the aftables package. Four things have been marked with numbers. 1 points to the current tab, named Table_1. 2 points to the sheet title. 3 points to four rows of elements below the title and below the table, which refer to the number of tables in the sheet, the presence of notes, the meaning of blank cells and the data source. 4 points to the table.
The labels in the image above highlight: @@ -59,4 +59,4 @@ The labels in the image above highlight: # Contribute -To contribute, please add [an issue](https://github.com/best-practice-and-impact/a11ytables/issues) or [a pull request](https://github.com/best-practice-and-impact/a11ytables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/a11ytables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/a11ytables/blob/main/.github/CONTRIBUTING.md) guidance. +To contribute, please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/aftables/blob/main/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance.