| Title: | Create Spreadsheet Publications Following Best Practice |
|---|---|
| Description: | Generate spreadsheet publications that follow best practice guidance from the UK government's Analysis Function, with a focus on accessibility. Based on 'openxlsx'. See also the Python package 'gptables'. |
| Authors: | Matt Dray [aut, cre], Tim Taylor [ctb], Matt Kerlogue [ctb], Crown Copyright [cph, fnd] |
| Maintainer: | Matt Dray <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.3.2 |
| Built: | 2024-09-24 04:44:33 UTC |
| Source: | https://github.com/co-analysis/a11ytables |
Functions to check if an object is an a11ytable, or coerce it if possible.
as_a11ytable(x) is_a11ytable(x)as_a11ytable(x) is_a11ytable(x)
x |
A data.frame object to coerce. |
as_a11ytable returns an object of class a11ytable if possible.
is_a11ytable returns TRUE if the object has class
a11ytable, otherwise FALSE.
is_a11ytable(demo_a11ytable)is_a11ytable(demo_a11ytable)
Insert at the cursor a template for create_a11ytable from the
'a11ytable' package, pre-filled with demo data.
at_template_a11ytable()at_template_a11ytable()
Insert at the cursor (a) demo templates for cover, contents and notes
tables, and (b) a call to create_a11ytable pre-filled with
demo data.
at_template_workflow()at_template_workflow()
Create a new a11ytable-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 generate_workbook.
create_a11ytable( tab_titles, sheet_types = c("cover", "contents", "notes", "tables"), sheet_titles, blank_cells = NA_character_, sources = NA_character_, custom_rows = list(NA_character_), tables )create_a11ytable( tab_titles, sheet_types = c("cover", "contents", "notes", "tables"), sheet_titles, blank_cells = NA_character_, sources = NA_character_, custom_rows = list(NA_character_), tables )
tab_titles |
Required character vector, one value per sheet. Each title will appear literally on each tab of the final spreadsheet output. Keep brief. Letters and numbers only; do not start with a number; use underscores for spaces. For example: 'Cover', 'Contents', 'Notes', 'Table_1'. Will be corrected automatically unless there's an error. |
sheet_types |
Required character vector, one value per sheet. Sheets that don't contain publication tables ('meta' sheets) should be of type 'contents', 'cover' or 'notes'. Sheets that contain statistical tables of data are type 'tables'. |
sheet_titles |
Required character vector, one value per sheet. The main title for each sheet, which will appear in cell A1 (top-left corner). |
blank_cells |
Optional character vector, one value per sheet. A short
sentence to explain the reason for any blank cells in the sheet. Supply
as |
sources |
Optional character vector, one value per sheet. The origin of
the data for a given sheet. Supply as |
custom_rows |
Optional list of character vectors. One list element per
sheet, one character vector element per row of pre-table metadata. Supply
a list element as |
tables |
Required list of data.frames (though the cover sheet may be supplied as a list), one per sheet. See details. |
Formats for the elements collected as a list and passed to the 'tables' argument, depending on the sheet type.
Sheet type 'cover': either (a) a list where each element name is a section header and each element's content is a character vector whose elements will make up separate rows of that section (recommended), or (b) a data.frame with one row per subsection, with one column for section titles and one column for corresponding for that section's body text. For example, you may have a section with the title 'Contact details' that contains an email address and telephone number. You can use linebreaks (i.e. '\n') to separate text into paragraphs.
Sheet type 'contents': one row per sheet, two columns suggested at least (named 'Tab title' and 'Worksheet title').
Sheet type 'notes': one row per note, two columns suggested (named 'Note number', 'Note text'), where notes are in the form '[note 1]'.
Sheet type 'tables': a tidy, rectangular data.frame containing the data to be published. It's the user's responsibility to add notes in the form '[note 1]' to column headers, or in a special 'Notes' row.
You can provide text in Markdown link syntax (e.g. '[GOV.UK](https://www.gov.uk)', adding 'mailto:' before an email address) and the containing cell will be rendered as a hyperlink in the output spreadsheet. Note that whole cells will become hyperlinks; there is no support for selected words in a sentence to be rendered as a hyperlink.
Hyperlinks can be supplied in the character strings to three arguments:
To the 'tables' argument for sheet type 'cover' only. It's recommended to supply the cover information as a list rather than a data.frame, which will allow you to make specific rows within a section (e.g. 'contact us') into hyperlinks.
To the 'custom_rows' argument for sheets of type 'contents, 'notes' and 'tables'.
To the 'source' argument for sheets of type 'table' only.
An object with classes 'a11ytable', 'tbl' and 'data.frame'.
# Prepare some demo tables of information set.seed(1066) 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://co-analysis.github.io/a11ytables/)", "[Email address](mailto:[email protected])" ) ) contents_df <- data.frame( "Sheet name" = c("Notes", "Table_1", "Table_2"), "Sheet title" = c( "Notes used in this workbook", "First Example Sheet", "Second Example Sheet" ), check.names = FALSE ) notes_df <- data.frame( "Note number" = paste0("[note ", 1:3, "]"), "Note text" = c("First note.", "Second note.", "Third note."), check.names = FALSE ) table_1_df <- data.frame( Category = LETTERS[1:10], "Numeric [note 1]" = 1:10, "Numeric suppressed" = c(1:4, "[c]", 6:9, "[x]"), "Numeric thousands" = abs(round(rnorm(10), 4) * 1e5), "Numeric decimal" = abs(round(rnorm(10), 5)), "This column has a very long name that means that the column width needs to be widened" = 1:10, Notes = c("[note 1]", rep(NA_character_, 4), "[note 2]", rep(NA_character_, 4)), check.names = FALSE ) table_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10) # Create 'a11ytables' object x <- a11ytables::create_a11ytable( 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", "Table of contents", "Notes", "Table 1: First Example Sheet", "Table 2: Second Example Sheet" ), blank_cells = c( rep(NA_character_, 3), "Blank cells indicate that there's no note in that row.", NA_character_ ), custom_rows = list( NA_character_, NA_character_, "A custom row.", c( "First custom row [with a hyperlink.](https://co-analysis.github.io/a11ytables/)", "Second custom row." ), "A custom row." ), sources = c( rep(NA_character_, 3), "[The Source Material, 2024.](https://co-analysis.github.io/a11ytables/)", "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) # Look at the structure of the object str(x, max.level = 2)# Prepare some demo tables of information set.seed(1066) 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://co-analysis.github.io/a11ytables/)", "[Email address](mailto:[email protected])" ) ) contents_df <- data.frame( "Sheet name" = c("Notes", "Table_1", "Table_2"), "Sheet title" = c( "Notes used in this workbook", "First Example Sheet", "Second Example Sheet" ), check.names = FALSE ) notes_df <- data.frame( "Note number" = paste0("[note ", 1:3, "]"), "Note text" = c("First note.", "Second note.", "Third note."), check.names = FALSE ) table_1_df <- data.frame( Category = LETTERS[1:10], "Numeric [note 1]" = 1:10, "Numeric suppressed" = c(1:4, "[c]", 6:9, "[x]"), "Numeric thousands" = abs(round(rnorm(10), 4) * 1e5), "Numeric decimal" = abs(round(rnorm(10), 5)), "This column has a very long name that means that the column width needs to be widened" = 1:10, Notes = c("[note 1]", rep(NA_character_, 4), "[note 2]", rep(NA_character_, 4)), check.names = FALSE ) table_2_df <- data.frame(Category = LETTERS[1:10], Numeric = 1:10) # Create 'a11ytables' object x <- a11ytables::create_a11ytable( 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", "Table of contents", "Notes", "Table 1: First Example Sheet", "Table 2: Second Example Sheet" ), blank_cells = c( rep(NA_character_, 3), "Blank cells indicate that there's no note in that row.", NA_character_ ), custom_rows = list( NA_character_, NA_character_, "A custom row.", c( "First custom row [with a hyperlink.](https://co-analysis.github.io/a11ytables/)", "Second custom row." ), "A custom row." ), sources = c( rep(NA_character_, 3), "[The Source Material, 2024.](https://co-analysis.github.io/a11ytables/)", "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) # Look at the structure of the object str(x, max.level = 2)
A pre-created 'a11ytables' object ready to be converted to an 'openxlsx'
Workbook-class object with generate_workbook.
demo_a11ytabledemo_a11ytable
A data.frame with 6 rows and 7 columns:
Character. Text to appear on each sheet's tab.
Character. The content type for each sheet: 'cover', 'contents', 'notes', or 'tables'.
Character. The title that will appear in cell A1 (top-left) of each sheet.
Character. An explanation for any blank cells in the table.
List-column of character vectors. Additional arbitrary pre-table information provided by the user.
Character. The origin of the data, if relevant.
List-column of data.frames (apart from the cover, which is a list) containing the statistical tables.
A pre-created data.frame ready to be converted to an a11ytables-class object
with as_a11ytable and then an 'openxlsx' Workbook-class object
with generate_workbook.
demo_dfdemo_df
A data.frame with 6 rows and 7 columns:
Character. Text to appear on each sheet's tab.
Character. The content type for each sheet: 'cover', 'contents', 'notes', or 'tables'.
Character. The title that will appear in cell A1 (top-left) of each sheet.
Character. An explanation for any blank cells in the table.
List-column of character vectors. Additional arbitrary pre-table information provided by the user.
Character. The origin of the data, if relevant.
List-column of data.frames (apart from the cover, which is a list) containing the statistical tables.
A pre-created 'openxlsx' Workbook'-class object generated from an
a11ytables-class object with generate_workbook.
demo_workbookdemo_workbook
An 'openxlsx' Workbook-class object with 5 sheets.
Populate an 'openxlsx' Workbook-class object with content from an
a11ytable-class object. In turn, the output can be passed to
saveWorkbook from 'openxlsx'
generate_workbook(a11ytable)generate_workbook(a11ytable)
a11ytable |
An a11ytable-class object created using
|
A Workbook-class object.
# Convert an a11ytable to a Workbook-class object x <- generate_workbook(demo_a11ytable) class(x) # As above, using a compliant data.frame and the base pipe y <- demo_df |> as_a11ytable() |> generate_workbook()# Convert an a11ytable to a Workbook-class object x <- generate_workbook(demo_a11ytable) class(x) # As above, using a compliant data.frame and the base pipe y <- demo_df |> as_a11ytable() |> generate_workbook()
Superseded. mtcars_df and mtcars_df2 have been superseded in
favour of demo_df.
A modified version of the mtcars dataset prepared into a data.frame structure
ready for coercion to an a11ytables-class object with
as_a11ytable. Uses a dataframe as input to the cover table;
mtcars_df uses a list as input to the cover table.
mtcars_dfmtcars_df
A data frame with 5 rows and 6 columns:
Character. Text to appear on each sheet's tab.
Character. The content type for each sheet: 'cover', 'contents', 'notes', or 'tables'.
Character. The title that will appear in cell A1 (top-left) of each sheet.
Character. An explanation for any blank cells in the table.
Character. The origin of the data, if relevant.
List-column of data.frames containing the statistical tables.
Uses a data.frame as input to the cover table, whereas
mtcars_df2 uses a list as input to the cover table
(implemented in version 0.2).
Note that this dataset is superseded by demo_df but is
retained for backwards-compatibility with package versions prior to 0.3.
Superseded. mtcars_df and mtcars_df2 have been superseded in
favour of demo_df.
A modified version of the mtcars dataset prepared into a data.frame structure
ready for coercion to an a11ytables-class object with
as_a11ytable.
mtcars_df2mtcars_df2
A data frame with 5 rows and 6 columns:
Character. Text to appear on each sheet's tab.
Character. The content type for each sheet: 'cover', 'contents', 'notes', or 'tables'.
Character. The title that will appear in cell A1 (top-left) of each sheet.
Character. An explanation for any blank cells in the table.
Character. The origin of the data, if relevant.
List-column of data.frames (apart from the cover, which is a list) containing the statistical tables.
Uses a list as input to the cover table (implemented in version 0.2), whereas
mtcars_df uses a data.frame as input to the cover table.
Note that this dataset is superseded by demo_df but is
retained for backwards-compatibility with package versions starting 0.2.
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.
## S3 method for class 'a11ytable' summary(object, ...)## S3 method for class 'a11ytable' summary(object, ...)
object |
An a11ytable-class object for which to get a summary. |
... |
Other arguments to pass. |
# Print a concise summary of the a11ytable-class object summary(demo_a11ytable) # Alternatively, look at the structure str(demo_a11ytable, max.level = 2)# Print a concise summary of the a11ytable-class object summary(demo_a11ytable) # Alternatively, look at the structure str(demo_a11ytable, max.level = 2)
A brief text description of an a11ytable-class object.
## S3 method for class 'a11ytable' tbl_sum(x, ...)## S3 method for class 'a11ytable' tbl_sum(x, ...)
x |
An a11ytable-class object to summarise. |
... |
Other arguments to pass. |
Named character vector.
# Print with description print(demo_a11ytable) # Print description only (package 'tibble' must be installed) tibble::tbl_sum(demo_a11ytable)# Print with description print(demo_a11ytable) # Print description only (package 'tibble' must be installed) tibble::tbl_sum(demo_a11ytable)