├── .gitignore ├── LICENSE ├── inst └── figures │ ├── logo.png │ └── logo-social.png ├── .Rbuildignore ├── NAMESPACE ├── verbaliseR.Rproj ├── R ├── restore_capitals.R ├── listify.R ├── prettify_date.R ├── pluralise.R └── num_to_text.R ├── man ├── restore_capitals.Rd ├── listify.Rd ├── prettify_date.Rd ├── num_to_text.Rd └── pluralise.Rd ├── DESCRIPTION ├── LICENSE.md ├── README.Rmd └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2022 2 | COPYRIGHT HOLDER: verbaliseR authors 3 | -------------------------------------------------------------------------------- /inst/figures/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cararthompson/verbaliseR/HEAD/inst/figures/logo.png -------------------------------------------------------------------------------- /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^verbaliseR\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^LICENSE\.md$ 4 | ^README.Rmd 5 | ^README.md 6 | -------------------------------------------------------------------------------- /inst/figures/logo-social.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cararthompson/verbaliseR/HEAD/inst/figures/logo-social.png -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | export(listify) 4 | export(num_to_text) 5 | export(pluralise) 6 | export(prettify_date) 7 | export(restore_capitals) 8 | -------------------------------------------------------------------------------- /verbaliseR.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: No 4 | SaveWorkspace: No 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | LineEndingConversion: Posix 18 | 19 | BuildType: Package 20 | PackageUseDevtools: Yes 21 | PackageInstallArgs: --no-multiarch --with-keep.source 22 | PackageRoxygenize: rd,collate,namespace 23 | -------------------------------------------------------------------------------- /R/restore_capitals.R: -------------------------------------------------------------------------------- 1 | #' Restore sustom capitalisation in a string 2 | #' 3 | #' @param x A string in which capitalisation needs to be restored 4 | #' @param items_to_capitalise Whole words or acronyms in which capitalisation must be retained; special characters can be included (e.g. "R2-D2") 5 | #' 6 | #' @return A string with restored capitals 7 | #' @export 8 | #' 9 | #' @examples 10 | #' x <- "Should i tell c-3po the french call him z-6po?" 11 | #' restore_capitals(x, c("I", "C-3PO", "French", "Z-6PO")) 12 | #' 13 | restore_capitals <- function(x, items_to_capitalise) { 14 | 15 | for(item in items_to_capitalise) { 16 | 17 | x <- gsub(paste0("\\b", tolower(item), "\\b"), 18 | item, 19 | x) 20 | } 21 | 22 | return(x) 23 | 24 | } 25 | -------------------------------------------------------------------------------- /man/restore_capitals.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/restore_capitals.R 3 | \name{restore_capitals} 4 | \alias{restore_capitals} 5 | \title{Restore sustom capitalisation in a string} 6 | \usage{ 7 | restore_capitals(x, items_to_capitalise) 8 | } 9 | \arguments{ 10 | \item{x}{A string in which capitalisation needs to be restored} 11 | 12 | \item{items_to_capitalise}{Whole words or acronyms in which capitalisation must be retained; special characters can be included (e.g. "R2-D2")} 13 | } 14 | \value{ 15 | A string with restored capitals 16 | } 17 | \description{ 18 | Restore sustom capitalisation in a string 19 | } 20 | \examples{ 21 | x <- "Should i tell c-3po the french call him z-6po?" 22 | restore_capitals(x, c("I", "C-3PO", "French", "Z-6PO")) 23 | 24 | } 25 | -------------------------------------------------------------------------------- /man/listify.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/listify.R 3 | \name{listify} 4 | \alias{listify} 5 | \title{Turn vectors into lists with any specified linking word} 6 | \usage{ 7 | listify(items, linking_word = "and", oxford_comma = FALSE) 8 | } 9 | \arguments{ 10 | \item{items}{A vector of items to turn into a list phrase (e.g. c("a", "b", "c")).} 11 | 12 | \item{linking_word}{Defaults to "and". Can be anything.} 13 | 14 | \item{oxford_comma}{\code{logical}. Defaults to \code{FALSE}. If TRUE, an oxford comma is added (e.g. "a, b, and c").} 15 | } 16 | \value{ 17 | A string in the form of a list (e.g. "a, b and c") 18 | } 19 | \description{ 20 | Turn vectors into lists with any specified linking word 21 | } 22 | \examples{ 23 | listify(c("a", "b", "c"), "or") 24 | 25 | } 26 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: verbaliseR 2 | Title: Make your Text Mighty Fine 3 | Version: 0.1 4 | Authors@R: 5 | person(given = "Cara", 6 | family = "Thompson", 7 | role = c("aut", "cre"), 8 | email = "cara.r.thompson@gmail.com", 9 | comment = c(ORCID = "0000-0002-6472-5073")) 10 | Description: Turn R analysis outputs into full sentences, by writing vectors into in-sentence lists, pluralising words conditionally, spelling out numbers if they are at the start of sentences, writing out dates in full following US or UK style, and managing capitalisations in tidy data. 11 | License: MIT + file LICENSE 12 | Encoding: UTF-8 13 | Roxygen: list(markdown = TRUE) 14 | RoxygenNote: 7.1.2 15 | URL: https://github.com/cararthompson/verbaliseR 16 | BugReports: https://github.com/cararthompson/verbaliseR/issues 17 | Maintainer: Cara Thompson 18 | Imports: stringr 19 | -------------------------------------------------------------------------------- /R/listify.R: -------------------------------------------------------------------------------- 1 | #' Turn vectors into lists with any specified linking word 2 | #' 3 | #' @param items A vector of items to turn into a list phrase (e.g. c("a", "b", "c")). 4 | #' @param linking_word Defaults to "and". Can be anything. 5 | #' @param oxford_comma `logical`. Defaults to `FALSE`. If TRUE, an oxford comma is added (e.g. "a, b, and c"). 6 | #' 7 | #' @return A string in the form of a list (e.g. "a, b and c") 8 | #' @export 9 | #' 10 | #' @examples listify(c("a", "b", "c"), "or") 11 | #' 12 | listify <- function(items, 13 | linking_word = "and", 14 | oxford_comma = FALSE) { 15 | 16 | if(length(items) > 1) { 17 | paste0(paste0(items[1:length(items)-1], 18 | collapse = ", "), 19 | ifelse(oxford_comma == TRUE, ", ", " "), 20 | linking_word, 21 | " ", 22 | items[length(items)]) 23 | } else { 24 | paste(items) 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /man/prettify_date.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/prettify_date.R 3 | \name{prettify_date} 4 | \alias{prettify_date} 5 | \title{Render ordinal dates in UK or US style} 6 | \usage{ 7 | prettify_date( 8 | date_to_format = Sys.Date(), 9 | uk_or_us = "UK", 10 | formal_or_informal = "informal" 11 | ) 12 | } 13 | \arguments{ 14 | \item{date_to_format}{The date to use. It must be either be of class \code{Date} or a string written as "YYYY-MM-DD" or "YYYY/MM/DD")} 15 | 16 | \item{uk_or_us}{Defaults to "UK", which results in outputs like "12th September 2022"; if 17 | "US", the output resembles "September 12th, 2022".} 18 | 19 | \item{formal_or_informal}{Defaults to "informal", so the ordinals are included (e.g. "st", "nd", "rd", "th"). 20 | If "formal" is chosen, the ordinals are omitted (e.g. "12 September 2022").} 21 | } 22 | \value{ 23 | A string (e.g. "12th September 2022") 24 | } 25 | \description{ 26 | Render ordinal dates in UK or US style 27 | } 28 | \examples{ 29 | prettify_date(Sys.Date(), "UK", "informal") 30 | } 31 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # MIT License 2 | 3 | Copyright (c) 2022 verbaliseR authors 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /man/num_to_text.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/num_to_text.R 3 | \name{num_to_text} 4 | \alias{num_to_text} 5 | \title{Spell out numbers if they are smaller than ten} 6 | \usage{ 7 | num_to_text( 8 | number, 9 | sentence_start = FALSE, 10 | zero_or_no = "no", 11 | uk_or_us = "UK", 12 | big_mark = "," 13 | ) 14 | } 15 | \arguments{ 16 | \item{number}{Whole number as \code{numeric} or \code{integer}, to be turned into text. Numbers 1-10 are always written out in full, 17 | regardless of their place in the sentence. Number 11-999 are written out in full if they are at the beginning of a sentence. 18 | Numbers greater than 1000 are returned as numerals.} 19 | 20 | \item{sentence_start}{Logical. If \code{TRUE}, numbers below 100 are written out in full, and their first letter is capitalised.} 21 | 22 | \item{zero_or_no}{Specify what to print when the number is 0. Defaults to "no". Can be any string.} 23 | 24 | \item{uk_or_us}{Defaults to UK which adds an "and" between "hundred" and other numbers (e.g. "One hundred and five"). If "US" 25 | is chosen, the "and" is removed (e.g. "One hundred five").} 26 | 27 | \item{big_mark}{Defaults to "," (e.g. "1,999").} 28 | } 29 | \value{ 30 | A string 31 | } 32 | \description{ 33 | Spell out numbers if they are smaller than ten 34 | } 35 | \examples{ 36 | num_to_text(3) 37 | num_to_text(333, sentence_start = TRUE) 38 | 39 | } 40 | -------------------------------------------------------------------------------- /R/prettify_date.R: -------------------------------------------------------------------------------- 1 | #' Render ordinal dates in UK or US style 2 | #' 3 | #' @param date_to_format The date to use. It must be either be of class `Date` or a string written as "YYYY-MM-DD" or "YYYY/MM/DD") 4 | #' @param uk_or_us Defaults to "UK", which results in outputs like "12th September 2022"; if 5 | #' "US", the output resembles "September 12th, 2022". 6 | #' @param formal_or_informal Defaults to "informal", so the ordinals are included (e.g. "st", "nd", "rd", "th"). 7 | #' If "formal" is chosen, the ordinals are omitted (e.g. "12 September 2022"). 8 | #' 9 | #' @return A string (e.g. "12th September 2022") 10 | #' @export 11 | #' 12 | #' @examples prettify_date(Sys.Date(), "UK", "informal") 13 | prettify_date <- function(date_to_format = Sys.Date(), 14 | uk_or_us = "UK", 15 | formal_or_informal = "informal") { 16 | 17 | day_num <- as.numeric(format(as.Date(date_to_format), "%d")) 18 | 19 | if (!(day_num %% 100 %in% c(11, 12, 13))) { 20 | day_th <- switch(as.character(day_num %% 10), 21 | "1" = {paste0(day_num, "st")}, 22 | "2" = {paste0(day_num, "nd")}, 23 | "3" = {paste0(day_num, "rd")}, 24 | paste0(day_num, "th")) 25 | } else { 26 | day_th <- paste0(day_num, "th") 27 | } 28 | 29 | num_to_use <- ifelse(formal_or_informal == "informal", 30 | day_th, 31 | day_num) 32 | 33 | if(uk_or_us == "UK") { 34 | paste(num_to_use, format(as.Date(date_to_format), "%B %Y")) 35 | } else { 36 | paste0(format(as.Date(date_to_format), "%B"), " ", 37 | num_to_use, ", ", format(as.Date(date_to_format), "%Y")) 38 | } 39 | } 40 | -------------------------------------------------------------------------------- /man/pluralise.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/pluralise.R 3 | \name{pluralise} 4 | \alias{pluralise} 5 | \title{Pluralise words if their accompanying number is not 1} 6 | \usage{ 7 | pluralise( 8 | word, 9 | count, 10 | plural = "s", 11 | add_or_swap = "add", 12 | include_number = TRUE, 13 | sentence_start = FALSE, 14 | zero_or_no = "no", 15 | uk_or_us = "UK", 16 | big_mark = "," 17 | ) 18 | } 19 | \arguments{ 20 | \item{word}{A word which should be returned as plural if \code{count} is not equal to 1.} 21 | 22 | \item{count}{A number to apply to \code{word}} 23 | 24 | \item{plural}{How to make the plural; defaults to an "s" which is added at the end of the word. 25 | Can be anything. See \code{add_or_swap}.} 26 | 27 | \item{add_or_swap}{Choose between \code{add} (add the plural form (e.g. "s") onto the end; e.g. \code{house} 28 | becomes \code{houses}) and \code{swap} (swap for the plural form; e.g. \code{mouse} becomes \code{mice})} 29 | 30 | \item{include_number}{Logical. If \code{TRUE}, the number will be turned into text, as per \code{num_to_text()} (if it is a whole number, )} 31 | 32 | \item{sentence_start}{Logical. Defaults to \code{FALSE}, which results in only numbers 1-10 being written out in full. 33 | If \code{TRUE}, numbers 11-999 are written out in full if included. (If \code{include_number} is \code{FALSE}, the first letter of \code{word} is capitalised.)} 34 | 35 | \item{zero_or_no}{Prefered string to use where count == 0. Defaults to "no". Can be anything.} 36 | 37 | \item{uk_or_us}{Only used if \code{include_number} == \code{TRUE}. Defaults to UK which adds an "and" between "hundred" and other numbers 38 | (e.g. "One hundred and five"). If "US" is chosen, the "and" is removed (e.g. "One hundred five").} 39 | 40 | \item{big_mark}{Passed to \code{num_to_text}. Defaults to "," (e.g. "1,999")} 41 | } 42 | \value{ 43 | A word which is pluralised or not based on the value of \code{count} 44 | } 45 | \description{ 46 | Pluralise words if their accompanying number is not 1 47 | } 48 | \examples{ 49 | pluralise("penguin", 3) 50 | pluralise("bateau", 1234, "x") 51 | pluralise("sheep", 333, "sheep", add_or_swap = TRUE, sentence_start = TRUE) 52 | 53 | } 54 | -------------------------------------------------------------------------------- /R/pluralise.R: -------------------------------------------------------------------------------- 1 | #' Pluralise words if their accompanying number is not 1 2 | #' 3 | #' @param word A word which should be returned as plural if `count` is not equal to 1. 4 | #' @param count A number to apply to `word` 5 | #' @param plural How to make the plural; defaults to an "s" which is added at the end of the word. 6 | #' Can be anything. See `add_or_swap`. 7 | #' @param add_or_swap Choose between `add` (add the plural form (e.g. "s") onto the end; e.g. `house` 8 | #' becomes `houses`) and `swap` (swap for the plural form; e.g. `mouse` becomes `mice`) 9 | #' @param include_number Logical. If `TRUE`, the number will be turned into text, as per `num_to_text()` (if it is a whole number, ) 10 | #' @param sentence_start Logical. Defaults to `FALSE`, which results in only numbers 1-10 being written out in full. 11 | #' If `TRUE`, numbers 11-999 are written out in full if included. (If `include_number` is `FALSE`, the first letter of `word` is capitalised.) 12 | #' @param zero_or_no Prefered string to use where count == 0. Defaults to "no". Can be anything. 13 | #' @param uk_or_us Only used if `include_number` == `TRUE`. Defaults to UK which adds an "and" between "hundred" and other numbers 14 | #' (e.g. "One hundred and five"). If "US" is chosen, the "and" is removed (e.g. "One hundred five"). 15 | #' @param big_mark Passed to `num_to_text`. Defaults to "," (e.g. "1,999") 16 | #' 17 | #' @return A word which is pluralised or not based on the value of `count` 18 | #' @export 19 | #' 20 | #' @examples pluralise("penguin", 3) 21 | #' pluralise("bateau", 1234, "x") 22 | #' pluralise("sheep", 333, "sheep", add_or_swap = TRUE, sentence_start = TRUE) 23 | #' 24 | pluralise <- function(word, 25 | count, 26 | plural = "s", 27 | add_or_swap = "add", 28 | include_number = TRUE, 29 | sentence_start = FALSE, 30 | zero_or_no = "no", 31 | uk_or_us = "UK", 32 | big_mark = ","){ 33 | 34 | if(count == 1) { 35 | output_string <- word 36 | } else { 37 | output_string <- ifelse(add_or_swap == "swap", 38 | plural, 39 | paste0(word, plural)) 40 | } 41 | 42 | if(include_number == FALSE & sentence_start == TRUE) { 43 | output_string <- stringr::str_to_sentence(output_string) 44 | } 45 | 46 | if(include_number == TRUE) { 47 | output_string <- paste( 48 | num_to_text(number = count, 49 | sentence_start = sentence_start, 50 | zero_or_no = zero_or_no, 51 | uk_or_us = uk_or_us, 52 | big_mark = big_mark), 53 | output_string 54 | ) 55 | } 56 | 57 | return(output_string) 58 | 59 | } 60 | -------------------------------------------------------------------------------- /R/num_to_text.R: -------------------------------------------------------------------------------- 1 | #' Spell out numbers if they are smaller than ten 2 | #' 3 | #' @param number Whole number as `numeric` or `integer`, to be turned into text. Numbers 1-10 are always written out in full, 4 | #' regardless of their place in the sentence. Number 11-999 are written out in full if they are at the beginning of a sentence. 5 | #' Numbers greater than 1000 are returned as numerals. 6 | #' @param sentence_start Logical. If `TRUE`, numbers below 100 are written out in full, and their first letter is capitalised. 7 | #' @param zero_or_no Specify what to print when the number is 0. Defaults to "no". Can be any string. 8 | #' @param uk_or_us Defaults to UK which adds an "and" between "hundred" and other numbers (e.g. "One hundred and five"). If "US" 9 | #' is chosen, the "and" is removed (e.g. "One hundred five"). 10 | #' @param big_mark Defaults to "," (e.g. "1,999"). 11 | #' 12 | #' @return A string 13 | #' @export 14 | #' 15 | #' @examples num_to_text(3) 16 | #' num_to_text(333, sentence_start = TRUE) 17 | #' 18 | num_to_text <- function(number, 19 | sentence_start = FALSE, 20 | zero_or_no = "no", 21 | uk_or_us = "UK", 22 | big_mark = ",") { 23 | 24 | # Return numeral if no other conditions are met (x > 10, & not start of sentence or x > 100) 25 | num_to_print <- number 26 | uk_or_us <- toupper(uk_or_us) 27 | 28 | x <- as.numeric(number) 29 | if (is.na(x)) stop(paste0(number, " is not a number.")) 30 | 31 | if(x %% 1 != 0) warning(paste0(number, " is not a whole number. It is kept as a numeral.")) 32 | 33 | if(x %% 1 == 0 & x > 999) { 34 | warning("Numbers greater than 1000 are returned as numerals, regardless of their place in the sentence.") 35 | num_to_print <- format(x, big.mark = big_mark) 36 | } 37 | 38 | ones <- c("one", "two", "three", "four", 39 | "five", "six", "seven", "eight", "nine") 40 | teens <- c("ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", 41 | "sixteen", "seventeen", "eighteen", "nineteen") 42 | tens <- c("twenty", "thirty", "forty", "fifty", 43 | "sixty", "seventy", "eighty", "ninety") 44 | 45 | if(x == 0) num_to_print <- zero_or_no 46 | if(x !=0 & x %% 1 == 0 & x < 10) num_to_print <- ones[x] 47 | if(x == 10) num_to_print <- "ten" 48 | if(x == 100) num_to_print <- "one hundred" 49 | if(x == 1000) num_to_print <- "one thousand" 50 | 51 | if(sentence_start == TRUE & x %in% c(10:19)) { 52 | num_to_print <- teens[x-9] 53 | } 54 | 55 | if(sentence_start == TRUE & x %in% c(20:999)) { 56 | 57 | hundreds <- ifelse(x > 99, 58 | paste(ones[x %/% 100], "hundred"), 59 | "") 60 | if(x %% 100 > 19) { 61 | sub_hundreds <- paste0(tens[(x %% 100 %/% 10) - 1], 62 | ifelse(x %% 10 != 0, "-", ""), 63 | ones[x %% 10]) 64 | } else if (x %% 100 > 9) { 65 | sub_hundreds <- paste0(teens[x %% 100 - 9]) 66 | } else if (x %% 100 > 0) { 67 | sub_hundreds <- ones[x %% 100] 68 | } 69 | 70 | num_to_print <- paste0( 71 | ifelse(x > 99, paste(ones[x %/% 100], "hundred"), ""), 72 | ifelse(x > 99 & x %% 100 != 0 & uk_or_us == "UK", " and ", ""), 73 | ifelse(x %% 100 != 0, 74 | sub_hundreds, 75 | "") 76 | ) 77 | } 78 | 79 | if(sentence_start == TRUE) { 80 | num_to_print <- stringr::str_to_sentence(num_to_print) 81 | } 82 | 83 | return(num_to_print) 84 | 85 | } 86 | -------------------------------------------------------------------------------- /README.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "verbaliseR" 3 | output: github_document 4 | --- 5 | 6 | ![](inst/figures/logo-social.png) 7 | 8 | ## Make your text mighty fine 9 | 10 | **{verbaliseR}** is a collection of functions that make it easier to turn R analysis outputs into sentences. Here's a quick example: 11 | 12 | ```{r, warning=FALSE, message=FALSE} 13 | library(dplyr) 14 | 15 | unique_species <- palmerpenguins::penguins %>% 16 | pull(species) %>% 17 | unique() 18 | 19 | paste0("There are ", 20 | verbaliseR::pluralise(word = "species", 21 | count = length(unique_species), 22 | plural = "species", 23 | add_or_swap = "swap"), 24 | " of penguins in this dataset: ", 25 | verbaliseR::listify(unique_species, 26 | linking_word = "and"), 27 | ".") 28 | ``` 29 | 30 | ## Installation 31 | 32 | Install from GitHub: 33 | 34 | ```{r, eval = FALSE} 35 | # From CRAN 36 | install.packages("verbaliseR") 37 | 38 | # From Github... 39 | # ... if you don't already have the {remotes} package installed: 40 | install.packages("remotes") 41 | 42 | # ... then: 43 | remotes::install_github("cararthompson/verbaliseR") 44 | 45 | ``` 46 | 47 | 48 | ## Main functions 49 | 50 | ### `listify()` 51 | 52 | Takes a vector and returns a string where the items in the vector are listed in prose. The link word can be anything you like, and there is an option to add an Oxford comma if desired. Here are a few examples: 53 | 54 | ```{r} 55 | # The default returns a list with "and" ... 56 | verbaliseR::listify(c("a", "b", "c")) 57 | 58 | # to which you can choose add an Oxford comma 59 | verbaliseR::listify(c("a", "b", "c"), 60 | oxford_comma = TRUE) 61 | 62 | # You can modify the linking word... 63 | verbaliseR::listify(c("a", "b", "c"), 64 | linking_word = "or") 65 | 66 | # ... and get quite creative with it ... 67 | verbaliseR::listify(c(verbaliseR::listify(c("a", "b", "c"), 68 | linking_word = "or"), 69 | "d"), 70 | linking_word = "but most certainly not", 71 | oxford_comma = TRUE) 72 | 73 | # ... in whatever language you choose 74 | verbaliseR::listify(c(verbaliseR::listify(c("a", "b", "c"), 75 | linking_word = "ou"), 76 | "d"), 77 | linking_word = "mais jamais au grand jamais", 78 | oxford_comma = TRUE) 79 | ``` 80 | 81 | ### `prettify_date()` 82 | 83 | Takes a `date` or string formatted as "YYYY_MM_DD" or "YYYY/MM/DD" and returns a string which is the date formatted in prose. Options include UK/US style and formal/informal (without / with the ordinals) 84 | 85 | ```{r} 86 | # Defaults to UK style, informal 87 | verbaliseR::prettify_date(Sys.Date()) 88 | 89 | # Can also do US style 90 | verbaliseR::prettify_date("2022/09/15", 91 | uk_or_us = "US") 92 | 93 | # To remove the ordinals, select formal_or_informal = "formal" 94 | verbaliseR::prettify_date("2022-09-15", 95 | uk_or_us = "US", 96 | formal_or_informal = "formal") 97 | 98 | ``` 99 | 100 | ### `num_to_text()` 101 | 102 | Used within `pluralise()` this function can also be useful on its own. It takes a number (whole number as numeric or integer) and writes it out in full, applying the following rules: 103 | 104 | - Numbers 0-10 are always written out in full, regardless of their place in the sentence 105 | - Numbers 11-1000 are written out in full only if they are at the start of a sentence 106 | - Numbers above 1000 or numbers containing a decimal point are never written out in full, but are formatted for readability with a big mark delimiter (e.g. 12345.67 turns into "1,2345.67") 107 | 108 | The big mark can be modified. 109 | 110 | ```{r} 111 | verbaliseR::num_to_text(3) 112 | 113 | # 0 defaults to "no", but can be changed to anything 114 | verbaliseR::num_to_text(0) 115 | verbaliseR::num_to_text(0, zero_or_no = "none") 116 | 117 | verbaliseR::num_to_text(3, 118 | sentence_start = TRUE) 119 | 120 | # Only whole numbers are returned as text; a warning is issued accordingly 121 | verbaliseR::num_to_text(1.25, 122 | sentence_start = TRUE) 123 | 124 | # Numbers greater than 1000 are not returned as text even if they are at the start of a sentence; 125 | # a warning is issued accordingly 126 | # They are however formatted for readability 127 | verbaliseR::num_to_text(3333, 128 | sentence_start = TRUE) 129 | 130 | # To change the default formatting, specify a custom big_mark 131 | verbaliseR::num_to_text(3333, 132 | sentence_start = TRUE, 133 | big_mark = " ") 134 | 135 | ``` 136 | 137 | 138 | ### `pluralise()` 139 | 140 | Takes a string and turns it into its plural, based on user input. It also retains the number, applying the rules of `num_to_text()` to it, unless specified otherwise. The flexibility of this function means it can be used in any language, but since numbers are currently returned only in English, users of other languages will need to specify `include_number = FALSE` for now if the number is between 1 and 10 or if `sentence_start` is `TRUE`. 141 | 142 | ```{r, warning=FALSE, message=FALSE} 143 | # The default plural is an s tagged onto the end of the word ... 144 | verbaliseR::pluralise("penguin", 3) 145 | 146 | # ... but this can be changed ... 147 | verbaliseR::pluralise("bateau", 3, 148 | plural = "x", 149 | include_number = FALSE) 150 | 151 | # ... or a new word can be substituted 152 | verbaliseR::pluralise("sheep", 3, 153 | plural = "sheep", 154 | add_or_swap = "swap") 155 | 156 | # Numbers below 1001 are written out in full at the start of sentences ... 157 | verbaliseR::pluralise("penguin", 333, 158 | sentence_start = TRUE) 159 | 160 | # ... but not in the middle of sentences 161 | verbaliseR::pluralise("penguin", 333) 162 | 163 | # Numbers above 1000 are never written out in full but are formatted for readability ... 164 | verbaliseR::pluralise("penguin", 33333, 165 | sentence_start = TRUE) 166 | 167 | # ... with a customisable big mark to allow for different conventions 168 | verbaliseR::pluralise("penguin", 33333, 169 | big_mark = " ") 170 | 171 | # Numbers with decimals are always left as numerals and aren't formatted 172 | verbaliseR::pluralise("unit", 12345.67) 173 | 174 | 175 | ``` 176 | 177 | ### `restore_capitals()` 178 | 179 | Takes a string in which some or all capitalisation has been lost, and restores capitals in the specified items. 180 | 181 | ```{r} 182 | x <- "Should i tell c-3po the french call him z-6po?" 183 | 184 | verbaliseR::restore_capitals(x, c("I", "C-3PO", "French", "Z-6PO")) 185 | ``` 186 | 187 | 188 | ## Further information 189 | 190 | - Report bugs or suggest new features [here](https://github.com/cararthompson/verbaliseR/issues). 191 | - Open to PRs from rstats users who want to make `num_to_text` and `prettify_date()` work in different languages. 192 | - Logo by [Jenny Legrand Photography](https://www.jennylegrandphotography.com/) 193 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | verbaliseR 2 | ================ 3 | 4 | 5 | [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/verbaliseR)](https://cran.r-project.org/package=verbaliseR) 6 | ![](http://cranlogs.r-pkg.org/badges/grand-total/verbaliseR?color=#0B3748) 7 | 8 | 9 | ![](inst/figures/logo-social.png) 10 | 11 | ## Make your text mighty fine 12 | 13 | **{verbaliseR}** is a collection of functions that make it easier to 14 | turn R analysis outputs into sentences. Here’s a quick example: 15 | 16 | ``` r 17 | library(dplyr) 18 | 19 | unique_species <- palmerpenguins::penguins %>% 20 | pull(species) %>% 21 | unique() 22 | 23 | paste0("There are ", 24 | verbaliseR::pluralise(word = "species", 25 | count = length(unique_species), 26 | plural = "species", 27 | add_or_swap = "swap"), 28 | " of penguins in this dataset: ", 29 | verbaliseR::listify(unique_species, 30 | linking_word = "and"), 31 | ".") 32 | ``` 33 | 34 | ## [1] "There are three species of penguins in this dataset: Adelie, Gentoo and Chinstrap." 35 | 36 | ## Installation 37 | 38 | Install from GitHub: 39 | 40 | ``` r 41 | # From CRAN 42 | install.packages("verbaliseR") 43 | 44 | # From Github... 45 | # ... if you don't already have the {remotes} package installed: 46 | install.packages("remotes") 47 | 48 | # ... then: 49 | remotes::install_github("cararthompson/verbaliseR") 50 | ``` 51 | 52 | ## Main functions 53 | 54 | ### `listify()` 55 | 56 | Takes a vector and returns a string where the items in the vector are 57 | listed in prose. The link word can be anything you like, and there is an 58 | option to add an Oxford comma if desired. Here are a few examples: 59 | 60 | ``` r 61 | # The default returns a list with "and" ... 62 | verbaliseR::listify(c("a", "b", "c")) 63 | ``` 64 | 65 | ## [1] "a, b and c" 66 | 67 | ``` r 68 | # to which you can choose add an Oxford comma 69 | verbaliseR::listify(c("a", "b", "c"), 70 | oxford_comma = TRUE) 71 | ``` 72 | 73 | ## [1] "a, b, and c" 74 | 75 | ``` r 76 | # You can modify the linking word... 77 | verbaliseR::listify(c("a", "b", "c"), 78 | linking_word = "or") 79 | ``` 80 | 81 | ## [1] "a, b or c" 82 | 83 | ``` r 84 | # ... and get quite creative with it ... 85 | verbaliseR::listify(c(verbaliseR::listify(c("a", "b", "c"), 86 | linking_word = "or"), 87 | "d"), 88 | linking_word = "but most certainly not", 89 | oxford_comma = TRUE) 90 | ``` 91 | 92 | ## [1] "a, b or c, but most certainly not d" 93 | 94 | ``` r 95 | # ... in whatever language you choose 96 | verbaliseR::listify(c(verbaliseR::listify(c("a", "b", "c"), 97 | linking_word = "ou"), 98 | "d"), 99 | linking_word = "mais jamais au grand jamais", 100 | oxford_comma = TRUE) 101 | ``` 102 | 103 | ## [1] "a, b ou c, mais jamais au grand jamais d" 104 | 105 | ### `prettify_date()` 106 | 107 | Takes a `date` or string formatted as “YYYY_MM_DD” or “YYYY/MM/DD” and 108 | returns a string which is the date formatted in prose. Options include 109 | UK/US style and formal/informal (without / with the ordinals) 110 | 111 | ``` r 112 | # Defaults to UK style, informal 113 | verbaliseR::prettify_date(Sys.Date()) 114 | ``` 115 | 116 | ## [1] "15th September 2022" 117 | 118 | ``` r 119 | # Can also do US style 120 | verbaliseR::prettify_date("2022/09/15", 121 | uk_or_us = "US") 122 | ``` 123 | 124 | ## [1] "September 15th, 2022" 125 | 126 | ``` r 127 | # To remove the ordinals, select formal_or_informal = "formal" 128 | verbaliseR::prettify_date("2022-09-15", 129 | uk_or_us = "US", 130 | formal_or_informal = "formal") 131 | ``` 132 | 133 | ## [1] "September 15, 2022" 134 | 135 | ### `num_to_text()` 136 | 137 | Used within `pluralise()` this function can also be useful on its own. 138 | It takes a number (whole number as numeric or integer) and writes it out 139 | in full, applying the following rules: 140 | 141 | - Numbers 0-10 are always written out in full, regardless of their 142 | place in the sentence 143 | - Numbers 11-1000 are written out in full only if they are at the 144 | start of a sentence 145 | - Numbers above 1000 or numbers containing a decimal point are never 146 | written out in full, but are formatted for readability with a big 147 | mark delimiter (e.g. 12345.67 turns into “1,2345.67”) 148 | 149 | The big mark can be modified. 150 | 151 | ``` r 152 | verbaliseR::num_to_text(3) 153 | ``` 154 | 155 | ## [1] "three" 156 | 157 | ``` r 158 | # 0 defaults to "no", but can be changed to anything 159 | verbaliseR::num_to_text(0) 160 | ``` 161 | 162 | ## [1] "no" 163 | 164 | ``` r 165 | verbaliseR::num_to_text(0, zero_or_no = "none") 166 | ``` 167 | 168 | ## [1] "none" 169 | 170 | ``` r 171 | verbaliseR::num_to_text(3, 172 | sentence_start = TRUE) 173 | ``` 174 | 175 | ## [1] "Three" 176 | 177 | ``` r 178 | # Only whole numbers are returned as text; a warning is issued accordingly 179 | verbaliseR::num_to_text(1.25, 180 | sentence_start = TRUE) 181 | ``` 182 | 183 | ## Warning in verbaliseR::num_to_text(1.25, sentence_start = TRUE): 1.25 is not a 184 | ## whole number. It is kept as a numeral. 185 | 186 | ## [1] "1.25" 187 | 188 | ``` r 189 | # Numbers greater than 1000 are not returned as text even if they are at the start of a sentence; 190 | # a warning is issued accordingly 191 | # They are however formatted for readability 192 | verbaliseR::num_to_text(3333, 193 | sentence_start = TRUE) 194 | ``` 195 | 196 | ## Warning in verbaliseR::num_to_text(3333, sentence_start = TRUE): Numbers greater 197 | ## than 1000 are returned as numerals, regardless of their place in the sentence. 198 | 199 | ## [1] "3,333" 200 | 201 | ``` r 202 | # To change the default formatting, specify a custom big_mark 203 | verbaliseR::num_to_text(3333, 204 | sentence_start = TRUE, 205 | big_mark = " ") 206 | ``` 207 | 208 | ## Warning in verbaliseR::num_to_text(3333, sentence_start = TRUE, big_mark = " "): 209 | ## Numbers greater than 1000 are returned as numerals, regardless of their place in 210 | ## the sentence. 211 | 212 | ## [1] "3 333" 213 | 214 | ### `pluralise()` 215 | 216 | Takes a string and turns it into its plural, based on user input. It 217 | also retains the number, applying the rules of `num_to_text()` to it, 218 | unless specified otherwise. The flexibility of this function means it 219 | can be used in any language, but since numbers are currently returned 220 | only in English, users of other languages will need to specify 221 | `include_number = FALSE` for now if the number is between 1 and 10 or if 222 | `sentence_start` is `TRUE`. 223 | 224 | ``` r 225 | # The default plural is an s tagged onto the end of the word ... 226 | verbaliseR::pluralise("penguin", 3) 227 | ``` 228 | 229 | ## [1] "three penguins" 230 | 231 | ``` r 232 | # ... but this can be changed ... 233 | verbaliseR::pluralise("bateau", 3, 234 | plural = "x", 235 | include_number = FALSE) 236 | ``` 237 | 238 | ## [1] "bateaux" 239 | 240 | ``` r 241 | # ... or a new word can be substituted 242 | verbaliseR::pluralise("sheep", 3, 243 | plural = "sheep", 244 | add_or_swap = "swap") 245 | ``` 246 | 247 | ## [1] "three sheep" 248 | 249 | ``` r 250 | # Numbers below 1001 are written out in full at the start of sentences ... 251 | verbaliseR::pluralise("penguin", 333, 252 | sentence_start = TRUE) 253 | ``` 254 | 255 | ## [1] "Three hundred and thirty-three penguins" 256 | 257 | ``` r 258 | # ... but not in the middle of sentences 259 | verbaliseR::pluralise("penguin", 333) 260 | ``` 261 | 262 | ## [1] "333 penguins" 263 | 264 | ``` r 265 | # Numbers above 1000 are never written out in full but are formatted for readability ... 266 | verbaliseR::pluralise("penguin", 33333, 267 | sentence_start = TRUE) 268 | ``` 269 | 270 | ## [1] "33,333 penguins" 271 | 272 | ``` r 273 | # ... with a customisable big mark to allow for different conventions 274 | verbaliseR::pluralise("penguin", 33333, 275 | big_mark = " ") 276 | ``` 277 | 278 | ## [1] "33 333 penguins" 279 | 280 | ``` r 281 | # Numbers with decimals are always left as numerals and aren't formatted 282 | verbaliseR::pluralise("unit", 12345.67) 283 | ``` 284 | 285 | ## [1] "12345.67 units" 286 | 287 | ### `restore_capitals()` 288 | 289 | Takes a string in which some or all capitalisation has been lost, and 290 | restores capitals in the specified items. 291 | 292 | ``` r 293 | x <- "Should i tell c-3po the french call him z-6po?" 294 | 295 | verbaliseR::restore_capitals(x, c("I", "C-3PO", "French", "Z-6PO")) 296 | ``` 297 | 298 | ## [1] "Should I tell C-3PO the French call him Z-6PO?" 299 | 300 | ## Further information 301 | 302 | - Report bugs or suggest new features 303 | [here](https://github.com/cararthompson/verbaliseR/issues). 304 | - Open to PRs from rstats users who want to make `num_to_text` and 305 | `prettify_date()` work in different languages. 306 | - Logo by [Jenny Legrand 307 | Photography](https://www.jennylegrandphotography.com/) 308 | --------------------------------------------------------------------------------