Movatterモバイル変換

fabR: Wrapper Functions Collection Used in Data Pipelines

Description

The goal of this package is to provide wrapper functions in the data cleaning and cleansing processes. These function helps in messages and interaction with the user, keep track of information in pipelines, help in the wrangling, munging, assessment and visualization of data frame-like material.

Author(s)

Maintainer: Guillaume Fabreguijoseph.fabre@gmail.com

Other contributors:

• Maelstrom-Research [funder]

See Also

Useful links:

• https://github.com/GuiFabre/fabR

• Report bugs athttps://github.com/GuiFabre/fabR/issues

Add an index column at the first place of a tibble

Description

Add an index, possibly by group, at the first place of a data frame or atibble The name by default is 'index' but can be named. If 'index' alreadyexists, or the given name, the column can be forced to be created, andreplace the other one.

Usage

add_index(tbl, name_index = "index", start = 1, .force = FALSE)

Arguments

Value

A tibble or a data frame containing one extra first column 'index' orany given name.

Examples

{##### Example 1 -------------------------------------------------------------# add an index for the tibbleadd_index(iris, "my_index")##### Example 2 -------------------------------------------------------------# add an index for the grouped tibblelibrary(tidyr)library(dplyr)my_tbl <- tibble(iris) %>% group_by(Species) %>% slice(1:3)add_index(my_tbl, "my_index")}

Create objects of type "logical".

Description

Create or test for objects of type "logical", and the basic logicalconstants.This function is a wrapper of the functionas.logical() and evaluatesif the object to be coerced can be interpreted as a boolean. Any object :NA, NA_integer, NA_Date_, (...),0, 0L, F, FALSE, false, FaLsE, (...),1, 1L,T, TRUE, true, TrUe, (...),will be converted as NA, FALSE and TRUE. Any other other will return anerror.

Usage

as_any_boolean(x)

Arguments

Value

An logical object of the same size.

See Also

as.logical()

Examples

{library(dplyr)as_any_boolean("TRUE")as_any_boolean(c("1"))as_any_boolean(0L)try(as_any_boolean(c('foo')))as_any_boolean(c(0,1L,0,TRUE,"t","F","FALSE"))tibble(values = c(0,1L,0,TRUE,"t","F","FALSE")) %>%  mutate(bool_values = as_any_boolean(values))}

Create objects of class "Date"

Description

This function takes a character string or a vector. This vector is evaluatesone observation after the other, and casts the best matching date formatfor each of them (independently). The best matching format is tested acrossseven different formats provided by the lubridate library. The user canspecify the wanted matching format (and can be helped usingwhich_any_date() for each value orguess_date_format()for the values as a whole.

Usage

as_any_date(  x = as.character(),  format = c("dmy", "dym", "ymd", "ydm", "mdy", "myd", "my", "ym", "as_date"))

Arguments

Details

Contrary to lubridate library oras.Date(), the function evaluatesthe different possibilities for a date. For example, c('02-03-1982') can beeither March the 2nd or February the 3rd. The function will cast the value asNA, and a warning, since there is an ambiguity that cannot be solved, unlessthe user provides the format to apply.

Value

A R Object of class 'Date'.

See Also

lubridate::ymd(),lubridate::ydm(),lubridate::dmy(),lubridate::myd(),lubridate::mdy(),lubridate::dym(),lubridate::my() ,lubridate::ym(),lubridate::as_date(),as.Date(),guess_date_format(),which_any_date()

Examples

{library(dplyr)library(tidyr)##### Example 1 -------------------------------------------------------------# Ambiguous dates -----------------------------------------------------------as_any_date('19 02 12')as_any_date('19 02 12', format = "ymd")as_any_date('19 02 12', format = "dym")##### Example 2 -------------------------------------------------------------# Non-ambiguous dates -------------------------------------------------------time <-  tibble(time = c(  "1983 07-19",  "14-01-1925",  "12/13/2015",  "2009-09-13",  "17-12-12",  "coucou",  "2025 jan the 30th",  "1809-01-19"))time %>% mutate(new_time = as_any_date(time))}

Create objects of type "integer".

Description

Create or test for objects of type "integer".This function is a wrapper of the functionas.integer() and evaluatesif the object to be coerced can be interpreted as a integer. Any object :NA, NA_integer, NA_Date_, (...),Boolean, such as 0, 0L, F, FALSE, false, FaLsE, (...),Any string "1", "+1", "-1", "1.0000"will be converted as NA or integer. Any other other will return anerror.

Usage

as_any_integer(x)

Arguments

Value

An integer object of the same size.

See Also

as.logical()

Examples

{library(dplyr)as_any_integer("1")as_any_integer(c("1.000","2.0","1","+12","-12"))try(as_any_integer('foo'))tibble(values = c("1.000","2.0","1","+12","-12")) %>%  mutate(bool_values = as_any_integer(values))}

Create objects of type "symbol"

Description

Create or test for objects of type "symbol".

Usage

as_any_symbol(x)

Arguments

Value

Object of type "symbol".

Examples

{as_any_symbol(coucou)as_any_symbol("coucou")}

Open a a web-based bookdown folder in a browser

Description

Opens a previously generated HTML bookdown site from files in the specifiedfolder. This is a shortcut function to access 'index.html' in the specifiedfolder.

Usage

bookdown_open(bookdown_path)

Arguments

Value

Nothing to be returned. The function opens a web page.

See Also

bookdown_template(),bookdown_open()

Examples

{bookdown_path = tempdir()bookdown_template(bookdown_path, overwrite = TRUE)bookdown_render(bookdown_path, overwrite = TRUE)bookdown_open(bookdown_path)}

Render a bookdown into a bookdown site

Description

This helper function renders an existing bookdown folder (containing atleast 'index.Rmd file)

Usage

bookdown_render(bookdown_path, overwrite = FALSE)

Arguments

Value

A folder containing htlm files (in docs, ...) generated from a bookdownreport.

See Also

bookdown_template(),bookdown_open()

Examples

{bookdown_path = tempdir()bookdown_template(bookdown_path, overwrite = TRUE)bookdown_render(bookdown_path, overwrite = TRUE)}

Create a bookdown template.

Description

This helper function creates a template for a bookdown.

Usage

bookdown_template(bookdown_path, overwrite = FALSE)

Arguments

Value

A folder containing all files (Rmd, yml, css) to generate the bookdown.

See Also

bookdown_render(),bookdown_open()

Examples

{bookdown_path = tempdir()bookdown_template(bookdown_path, overwrite = TRUE)}

Collects and Generates documentation of a package in a tibble format.

Description

This function crawls and aggregates roxygen documentation into a tibbleformat. To work properly, elements must be separated with the named fields attitle, at description, at ...), each at will be used as column name. Thecolumn name will also have 80 character to show the margin limit of eachchunk of documentation.

Usage

collect_roxygen(folder_r = "R")

Arguments

Value

A tibble where each line represents a function described in a package, andeach column is documentation field. Most common fields (title, description,details, param, see also, return and examples are placed ahead).

Examples

{library(tidyr)try({tibble(collect_roxygen(tempfile()))}, silent = FALSE)}

Deprecated functions

Description

Usebookdown_template() instead oftemplate_visual_report().

UsefabR_website() instead offabR_help().

Usage

template_visual_report(...)fabR_help(...)

Call to online documentation

Description

Direct call to the online documentation for the package, which includes adescription of the latest version of the package, vignettes, user guides,and a reference list of functions and help pages.

Usage

fabR_website()

Value

Nothing to be returned. The function opens a web page.

Examples

{fabR_website()}

Create an index of files in a folder

Description

Creates a tibble listing files in a specified folder (recursively) with filepath name and other useful metadata. This index can be used to quickly findfiles in the environment. The index also generates script to read files asR objects into the environment. Names for R objects are generatedautomatically from file names (R objects are not created at this step but thecommand line is generated and stored in the column to_eval, ready to beevaluated and generate R objects).

Usage

file_index_create(folder = getwd(), pattern = "^", negate = FALSE)

Arguments

Details

The user must make sure their files are in the folder to be indexed.

Value

A tibble with folder_path, file_path, file_name, extension, file_typecolumns and a last column to_eval which is R code in a character vector toread the file into the environment.

Examples

## Not run: file_index_create(tempdir())## End(Not run)

Read, source and open objects from an index of files

Description

Reads all files from a file index tibble as R objects to generate in theenvironment or R scripts to be sourced. Any other file types will be openedin browser (html files) or in environment. If no index tibble is provided,the function creates one from the working directory. (matching by regex issupported).

Usage

file_index_read(  index,  file_path = "^",  file_name = "^",  extension = "^",  file_type = "^",  assign = FALSE,  .envir = parent.frame())

Arguments

Details

for each file selected,xlsx files will be read using the functionread_excel_allsheets(),csv files will be read using the functionread_csv_any_formats(),spss and sav files will be read using the functionhaven::read_spss(),dta files will be read using the functionhaven::read_dta(),sas7bdat and sas files will be read using the functionhaven::read_sas(),R scripts, Rmd and md files be read using the functionreadLines(),The whole files will be created in a list, which name is the name of thefile.

Value

R objects generated in the environment or R scripts. R object names arecreated automatically from their file names. Otherwise return messagesindicating what objects were created, or files opened, and if any troublesoccurred.

See Also

read_excel_allsheets(),read_csv_any_formats(),haven::read_spss(),haven::read_dta(),haven::read_sas(),readLines()

Examples

## Not run: index <- file_index_create(tempdir())file_index_read(index, file_name = my_file_name)## End(Not run)

Search an index of files

Description

Searches in file index R object (tibble) based on pattern and other queryoptions and provides a table where all the files in a specified folder andcorresponding to the query are listed (recursively). If no index tibble isprovided, the function creates one from the working directory.

Usage

file_index_search(  index,  file_path = "^",  file_name = "^",  extension = "^",  file_type = "^",  show_tree = FALSE)

Arguments

Details

The function displays the tree of your files. You can enable thisfunctionality with 'show_tree = TRUE'

Value

A tibble with indexed information for files matching the query.

Examples

## Not run: index <- file_index_create(tempdir())file_index_search(index, file_name = my_file_name)## End(Not run)

Extract columns that are all 'NA' from a tibble

Description

This helper function extracts the names of the columns in a tibble having NAvalues for all observations.

Usage

get_all_na_cols(tbl)

Arguments

Value

A vector string indicating either that the tibble does not have emptycolumns or the names of the empty columns.

Examples

{##### Example 1 -------------------------------------------------------------# All columns have observationget_all_na_cols(iris)##### Example 2 -------------------------------------------------------------# One column doesn't have any observationslibrary(dplyr)get_all_na_cols(mutate(iris, new_col = NA))}

Extract observations (rows) that have all NA values in a tibble

Description

This helper function extracts the row number(s) having NA value for allcolumns.

Usage

get_all_na_rows(tbl, id_col = NULL)

Arguments

Value

A vector string indicating either that the tibble does not have emptyobservation or the row number of the empty observations.

Examples

{##### Example 1 -------------------------------------------------------------# All rows have observationget_all_na_rows(iris)##### Example 2 -------------------------------------------------------------# One row doesn't have any observationslibrary(dplyr)get_all_na_rows(bind_rows(iris, tibble(Species = c(NA,NA))))get_all_na_rows(  tbl = bind_rows(iris, tibble(Species =  c('id_151', 'id_152'))),  id_col = 'Species')}

Extract columns that have same values in a tibble

Description

This helper function extracts the names of the columns in a tibble havingidentical values for all observations.

Usage

get_duplicated_cols(tbl)

Arguments

Value

A tibble indicating which columns which values is the same in the tibble

Examples

{library(dplyr)tbl <-  mtcars %>%  mutate(   cyl_2 = cyl,   cyl_3 = cyl,   mpg_2 = mpg) get_duplicated_cols(tbl)}

Extract observations (rows) that have same values in a tibble

Description

This helper function extracts the row number (or first column value) in atibble having identical values for all columns. This function can be usedeither on the whole columns or excluding the first column (id) (which can beuseful to identify repeated observation across different ids)

Usage

get_duplicated_rows(tbl, id_col = NULL)

Arguments

Value

A tibble indicating which row which values is the same in the tibble

Examples

{# the row numbers are returned to identify which observations have repeated# valueslibrary(dplyr)get_duplicated_rows(tbl = bind_rows( tbl = mtcars, mtcars[1,]))get_duplicated_rows(  tbl = bind_rows(mtcars,mtcars[1,]) %>%        add_index() %>%        mutate(index = paste0('obs_',index)),  id_col = 'index')}

Get the paths of branches in a list

Description

Function that recursively go through a list object and store in a tibble thepath of each element in the list. The paths can be after that edited andaccessed usingparceval() for example.

Usage

get_path_list(list_obj, .map_list = NULL)

Arguments

Value

A tibble containing all the paths of each element of the list and theclass of each leaf (can be a list, or R objects).

See Also

parceval()

Examples

{library(dplyr)get_path_list(  list(    tibble = iris,    list = list(t1 = mtcars, t2 = tibble(iris)),    char = "foo"))}

Extract columns that have unique values in a tibble

Description

This helper function extracts the names of the columns in a tibble havingunique value for all observations.

Usage

get_unique_value_cols(tbl)

Arguments

Value

A vector string indicating either that the tibble does not have emptycolumns or the names of the empty columns.

Examples

{##### Example 1 -------------------------------------------------------------# All columns have distinct observationget_unique_value_cols(iris)##### Example 2 -------------------------------------------------------------# One column doesn't have distinct observationsget_unique_value_cols(tbl = iris[1:50,])}

Evaluate and gives the best match to any date format using lubridate library

Description

This function takes a tibble and a specific column. This column is evaluatedone observation after the other, and finally gives the best matching dateformat for the whole column. The best matching format is tested across sevendifferent formats provided by the lubridate library. Along with the format,the percentage of matching is given in the output tibble. The information ofthe best matching format can be used to mutate a column usingas_any_date(). The default format is yyyy-mm-dd.

Usage

guess_date_format(tbl, col = NULL)

Arguments

Details

Contrary to lubridate library oras.Date(), the function evaluatesthe column as a whole, and does not cast the column if there is ambiguitybetween values. For example, ('19-07-1983', '02-03-1982') implies that 02refers to the day and 03 refers to the month, since that order works for thefirst element, and doesn't otherwise.

Value

A tibble with information concerning the best matching date format, given anobject to be evaluated.

See Also

lubridate::ymd(),lubridate::ydm(),lubridate::dmy(),lubridate::myd(),lubridate::mdy(),lubridate::dym(),lubridate::my() ,lubridate::ym(),lubridate::as_date(),as.Date(),which_any_date(),as_any_date()

Examples

{library(tidyr)##### Example 1 -------------------------------------------------------------# Non-ambiguous dates ----------------------------------------------------time <-  tibble(time = c(  "2009-09-03",  "1983-07-19",  "2003-01-14",  "2010-09-29",  "2023-12-12",  "1509-11-30",  "1809-01-01"))guess_date_format(time)##### Example 2 -------------------------------------------------------------# Ambiguous dates ----------------------------------------------------time <- tibble(time = c( "1983-19-07", "1983-10-13", "2009-09-03", "1509-11-30"))guess_date_format(time)##### Example 3 -------------------------------------------------------------# Non date format dates --------------------------------------------------time <-  tibble(time = c(  "198-07-19",  "200-01-14",  "201-09-29",  "202-12-12",  "2000-09-03",  "150-11-3d0",  "180-01-01"))guess_date_format(time)}

Shortcut to create beautiful names in a list

Description

Generate a name for an element in a list. This function is targeted forfunctions creations which handle lists. Those lists may need names to gothrough each elements. This function can works withstats::setNames() andallows the user to provide name shorter, more user-friendly in their lists.

Usage

make_name_list(args_list, list_elem)

Arguments

Value

A character string simplified to be used as names in a list.

See Also

stats::setNames()

Examples

{library(tidyr)library(stats)#### Example 1 --------------------------------------------------------------# make_name_list generates names that are informative through a line of code# or function. tibble(iris), iris %>% tibble and# list(iris = tibble(mytibble) %>% select(Species)) will have 'iris' as name.list(tibble(iris), tibble(mtcars)) %>%  setNames(make_name_list(list(tibble(iris), tibble(mtcars)), args_list =    c("IRIS %>% complicated_code","complicated_function(MTCARS)")))#### Example 2 --------------------------------------------------------------# make_name_list can be used when a function uses arguments provided by the# user to generate a list. The name is simplified and given to the list# itselflibrary(dplyr)my_function <- function(df){  .fargs <- as.list(match.call(expand.dots = TRUE))  list_df <-    list(df) %>%    setNames(.,make_name_list(as.character(.fargs['df']),list(df)))  return(list_df)}my_function(tibble(iris))my_function(iris %>% tibble %>% select(Species))}

Shortcut to display a message and acceptation on prompt

Description

Shortcut allowing to provide user a prompt and a message that is to be readand validated before pursuing process. This function is targeted for functioncreators where user interaction is required.

Usage

message_on_prompt(...)

Arguments

Value

Nothing to be returned. The function sends a message as a prompt in theconsole.

Examples

{message_on_prompt("Do you want to continue? Press `enter` or `esc`")}

Shortcut to turn String character into R code

Description

Shortcut toparse() andeval() evaluate R expression in acharacter string, and turns it into actual R code. This function is targetedfor interaction with external files (where expression is stored in textformat) ; for tidy elements where code expression is generated usingdplyr::mutate(), combined withpaste0() ; in for while, map, etc.loops where character string expression can be indexed or iterativelygenerated and evaluated ; objects to be created (using assign, <- or <<- obj)where the name of the R object is stored in a string. Some issues may occurwhen parceval is used in a different environment, such as in a function.Prefer eval(parse(text = ...) instead.

Usage

parceval(...)

Arguments

Value

Any output generated by the evaluation of the string character.

See Also

parse(),eval()

Examples

{##### Example 1 -------------------------------------------------------------# Simple assignation will assign 'b' in parceval environment (which is# associated to a function and different from .GlobalEnv, by definition).# Double assignation will put 'b' in .GlobalEnv.# (similar to assign(x = "b",value = 1,envir = .GlobalEnv))a <- 1parceval("print(a)")##### Example 2 -------------------------------------------------------------# use rowwise to directly use parceval in a tibble, or use a for loop.library(dplyr)library(tidyr)tibble(cars) %>%  mutate(    to_eval = paste0(speed,"/",dist)) %>%  rowwise() %>%  mutate(    eval = parceval(to_eval))##### Example 3 -------------------------------------------------------------# parceval can be parcevaled itself!code_R <-  'as_tibble(cars) %>%  mutate(    to_eval = paste0(speed,"/",dist)) %>%  rowwise() %>%  mutate(    eval = parceval(to_eval))'cat(code_R)parceval(code_R)}

Read a csv file using read_csv and avoid errors

Description

The csv file is read twice to detect the number of lines to use inattributing the column type ('guess_max' parameter of read_csv). This avoidscommon errors when reading csv files.

Usage

read_csv_any_formats(filename)

Arguments

Value

A tibble corresponding to the csv read.

See Also

readr::read_csv(),readr::read_csv2()

Examples

{try(read_csv_any_formats(filename = tempfile()),silent = TRUE)}

Read all Excel sheets usingreadxl::read_excel() recursively

Description

The Excel file is read and the values are placed in a list of tibbles, witheach sheet in a separate element in the list. If the Excel file has only onesheet, the output is a single tibble.

The Excel file is read and the values are placed in a list of tibbles, witheach sheet in a separate element in the list. If the Excel file has only onesheet, the output is a single tibble.

Usage

read_excel_allsheets(filename, sheets = "", keep_as_list = FALSE)read_excel_allsheets(filename, sheets = "", keep_as_list = FALSE)

Arguments

Value

A list of tibbles corresponding to the sheets read, or a single tibbleif the number of sheets is one.

A list of tibbles corresponding to the sheets read, or a single tibbleif the number of sheets is one.

See Also

readxl::read_excel()

readxl::read_excel()

Examples

{try(read_excel_allsheets(filename = tempfile()), silent = TRUE)}{try(read_excel_allsheets(filename = tempfile()), silent = TRUE)}

Shortcut to silently run a code chunk avoiding error, messages and warnings

Description

Shortcut avoiding user to get messages, warnings and being stopped by anerror. The usage is very similar tosuppressWarnings(). This functionis targeted for function creators where user experience enhancement issought.

Usage

silently_run(...)

Arguments

Value

The output of the R code, unless the output is a message, a warning or anerror, nothing will be returned in that case.

See Also

invisible(),suppressWarnings(),suppressMessages()

Examples

{as.integer("text")silently_run(as.integer("text"))}

Evaluates and gives the possible format(s) for an object to be evaluated

Description

This function takes a character string or a vector. This vector is evaluatesone observation after the other, and gives the best matching date formatfor each of them (independently). The best matching format is tested acrossseven different formats provided by the lubridate library. The information ofthe best matching format can be used to mutate a column usingas_any_date().

Usage

which_any_date(  x,  format = c("ymd", "ydm", "dmy", "myd", "mdy", "dym", "my", "ym", "as_date"))

Arguments

Details

Contrary to lubridate library oras.Date(), the function evaluatesthe different possibilities for a date. For example, c('02-03-1982') can beeither March the 2nd or February the 3rd. The function will provide"mdy, dmy" as possible formats. If no format is found, the function returnsNA.

Value

A character string of the possible date formats given a parameter to betested. The length of the vector is the length of the input object.

See Also

lubridate::ymd(),lubridate::ydm(),lubridate::dmy(),lubridate::myd(),lubridate::mdy(),lubridate::dym(),lubridate::my() ,lubridate::ym(),lubridate::as_date(),as.Date(),guess_date_format(),as_any_date()

Examples

{time <- c(  "1983-07-19",  "31 jan 2017",  "1988/12/17",  "31-02-05",  "02-02-02",  "2017 october the 2nd",  "02-07-2012",  "19-07-83",  "19-19-19")which_any_date(time)}

Write all Excel sheets usingwritexl::write_xlsx() recursively

Description

The R objects are read and the values are placed in separated sheets.This function is inspired by the function proposed inhttps://statmethods.wordpress.com/2014/06/19/quickly-export-multiple-r-objects-to-an-excel-workbook/

The R objects are read and the values are placed in separated sheets.This function is inspired by the function proposed inhttps://statmethods.wordpress.com/2014/06/19/quickly-export-multiple-r-objects-to-an-excel-workbook/

Usage

write_excel_allsheets(list, filename)write_excel_allsheets(list, filename)

Arguments

Value

Nothing to be returned. The file is created at the path declared in theenvironment.

Nothing to be returned. The file is created at the path declared in theenvironment.

See Also

writexl::write_xlsx()

writexl::write_xlsx()

Examples

{unlink(  write_excel_allsheets(    list = list(iris = iris, mtcars = mtcars),    filename = tempfile()))}{unlink(  write_excel_allsheets(    list = list(iris = iris, mtcars = mtcars),    filename = tempfile()))}