| Title: | Fast and Memory-Efficient Base R Table Manipulation |
|---|---|
| Description: | A tabular data manipulation, exploration and validation toolkit with a base R-style interface (subset, transform, aggregate, merge, split) and no external computation dependency. Grouping, joins, ordering, filtering, reshaping and delimited-file reading run in a bundled 'C++' engine that uses multiple threads for the heavier operations. Grouped reducers accumulate in compiled code without materialising intermediate columns, so grouped aggregation and counting allocate close to nothing. Results are returned as an ordinary data frame with a light 'basetable' class. |
| Authors: | Imad El Badisy [aut, cre] |
| Maintainer: | Imad El Badisy <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.4.2 |
| Built: | 2026-09-23 12:01:14 UTC |
| Source: | https://github.com/ielbadisy/basetable |
The basetable package provides a compact set of base-style data manipulation and exploratory data analysis helpers backed by a native C++ table engine.
Core design rules:
exported data verbs take the main data object as their first argument
grouping is explicit with by =
outputs are plain data frames or lists in most cases
interfaces are intended to work naturally in nested calls and native
|> pipelines
Add days to a date
adddays(x, n)adddays(x, n)
x |
An atomic vector. |
n |
Integer count. |
A Date vector.
new but not in old
Rows present in new but not in old
addedrows(old, new, by = NULL)addedrows(old, new, by = NULL)
old |
Baseline data.frame ("before" state). |
new |
Updated data.frame ("after" state), or replacement values when used for value substitution. |
by |
Character vector of column names identifying groups or join keys. |
The added rows.
Add months to a date
addmonths(x, n, invalid = c("previous", "next", "missing", "error"))addmonths(x, n, invalid = c("previous", "next", "missing", "error"))
x |
An atomic vector. |
n |
Integer count. |
invalid |
How to handle an invalid resulting date. |
A Date vector.
Add weeks to a date
addweeks(x, n)addweeks(x, n)
x |
An atomic vector. |
n |
Integer count. |
A Date vector.
Add years to a date
addyears(x, n, invalid = c("previous", "next", "missing", "error"))addyears(x, n, invalid = c("previous", "next", "missing", "error"))
x |
An atomic vector. |
n |
Integer count. |
invalid |
How to handle an invalid resulting date. |
A Date vector.
Compute grouped summaries for one or more value columns. When data is a
single file path, the file is scanned once and only the grouping and value
fields are extracted, without materialising the other columns.
aggregate(data, by, value = NULL, fun, ..., na.rm = FALSE, sort = TRUE)aggregate(data, by, value = NULL, fun, ..., na.rm = FALSE, sort = TRUE)
data |
A data frame, or a single path to a delimited text file for the fused one-pass file mode. |
by |
Character vector of grouping columns. |
value |
Optional character vector of value columns to summarize. |
fun |
Summary function applied to each value column. In file mode this is
one or more of |
... |
Additional arguments passed to |
na.rm |
Whether to remove missing values before summarizing (defaults to
|
sort |
Whether to sort output rows by group. |
A basetable containing one row per group.
Keep rows in x whose keys do not exist in y.
antimerge(x, y, by)antimerge(x, y, by)
x, y
|
Data frames or data tables to compare. |
by |
Character vector of join columns. |
A basetable containing rows from x without matches in y.
Apply a function to each group
applyby(data, by, fun, ..., bind = FALSE, id = ".group")applyby(data, by, fun, ..., bind = FALSE, id = ".group")
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
fun |
Function applied to each element, column, or group. |
... |
Additional arguments (unused, or passed through depending on the function). |
bind |
Combine the per-group results into a single table. |
id |
Optional name for a source identifier column. |
A list of per-group results, or a combined table when bind = TRUE.
Apply a function to selected columns
applycols(data, cols, fun, ...)applycols(data, cols, fun, ...)
data |
A data.frame. |
cols |
Character vector of column names. |
fun |
Function applied to each element, column, or group. |
... |
Additional arguments (unused, or passed through depending on the function). |
data with the selected columns transformed.
as_basetable() turns a data frame, a list of equal-length columns, a
matrix, or anything else as.data.frame() accepts into a basetable: an
ordinary data frame carrying basetable's lightweight class, the same object
every basetable verb returns. Use it when a package or script wants to hand
its own data to basetable explicitly, rather than relying on a verb to stamp
the class.
as_basetable(x, ...) ## S3 method for class 'basetable' as_basetable(x, ...) ## S3 method for class 'data.frame' as_basetable(x, ...) ## Default S3 method: as_basetable(x, ...)as_basetable(x, ...) ## S3 method for class 'basetable' as_basetable(x, ...) ## S3 method for class 'data.frame' as_basetable(x, ...) ## Default S3 method: as_basetable(x, ...)
x |
An object to coerce. |
... |
Passed to |
The data are left unchanged; only the class and the row.names attribute
are normalised. An object that is already a basetable is returned as-is,
and as.data.frame() strips the class again.
A basetable: a data frame with the basetable class.
bt <- as_basetable(data.frame(g = c("a", "b"), x = 1:2)) class(bt) identical(as_basetable(bt), bt) as_basetable(list(g = c("a", "b"), x = 1:2))bt <- as_basetable(data.frame(g = c("a", "b"), x = 1:2)) class(bt) identical(as_basetable(bt), bt) as_basetable(list(g = c("a", "b"), x = 1:2))
Low-level helpers for validating columns and keys or comparing schemas.
assert_cols(data, cols) assert_key(data, by) common_names(x, y) duplicated_keys(data, by)assert_cols(data, cols) assert_key(data, by) common_names(x, y) duplicated_keys(data, by)
data, x, y
|
A |
cols, by
|
Character vectors naming columns. |
assert_cols() and assert_key() return their input invisibly.
common_names() returns a character vector. duplicated_keys()
returns a data frame of duplicated key combinations.
common_names(mtcars, iris) assert_cols(mtcars, c("mpg", "hp")) duplicated_keys(data.frame(id = c(1, 1, 2)), "id")common_names(mtcars, iris) assert_cols(mtcars, c("mpg", "hp")) duplicated_keys(data.frame(id = c(1, 1, 2)), "id")
Assert that columns exist (alias)
assertcols(data, cols)assertcols(data, cols)
data |
A data.frame. |
cols |
Character vector of column names. |
See assert_cols().
Assert that there are no missing values
assertcomplete(data, cols = NULL)assertcomplete(data, cols = NULL)
data |
A data.frame. |
cols |
Character vector of column names. |
data, invisibly, if the assertion passes.
Assert that a key is unique (alias)
assertkey(data, by)assertkey(data, by)
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
See assert_key().
Assert that required column names are present
assertnames(data, names)assertnames(data, names)
data |
A data.frame. |
names |
Required column names. |
data, invisibly, if the assertion passes.
Assert that a column falls within a numeric range
assertrange(data, column, lower, upper)assertrange(data, column, lower, upper)
data |
A data.frame. |
column |
Name of a single column. |
lower |
Lower bound. |
upper |
Upper bound. |
data, invisibly, if the assertion passes.
Assert that a row-wise condition holds for every row
assertrows(data, condition)assertrows(data, condition)
data |
A data.frame. |
condition |
A logical expression evaluated in the context of |
data, invisibly, if the assertion passes.
Assert that a column has an expected class
asserttype(data, column, class)asserttype(data, column, class)
data |
A data.frame. |
column |
Name of a single column. |
class |
Class name to check against. |
data, invisibly, if the assertion passes.
Assert that selected columns are unique
assertunique(data, cols)assertunique(data, cols)
data |
A data.frame. |
cols |
Character vector of column names. |
data, invisibly, if the assertion passes.
Assert that a column only contains allowed values
assertvalues(data, column, allowed)assertvalues(data, column, allowed)
data |
A data.frame. |
column |
Name of a single column. |
allowed |
Vector of permitted values. |
data, invisibly, if the assertion passes.
Test whether a date falls within a range
betweendates(x, start, end)betweendates(x, start, end)
x |
An atomic vector. |
start |
Start bound (inclusive). |
end |
End bound (inclusive). |
A logical vector.
NA
Recode blank strings to NA
blanktona(x)blanktona(x)
x |
An atomic vector. |
x with blanks replaced by NA.
A from-scratch delimited-file reader written in C++: the file is memory mapped, scanned once for row boundaries (RFC 4180 quoting), type-guessed from a bounded sample, and materialised into typed vectors. Numeric columns are filled by a thread pool; character columns are built on the R thread.
btread( file, delim = NULL, header = TRUE, col_names = NULL, col_types = NULL, col_select = NULL, na = c("NA", ""), quote = "\"", comment = "", trim_ws = FALSE, skip = 0, n_max = Inf, guess_max = 10000, lazy = FALSE, n_threads = bt_default_threads(), as = c("data.frame", "basetable") )btread( file, delim = NULL, header = TRUE, col_names = NULL, col_types = NULL, col_select = NULL, na = c("NA", ""), quote = "\"", comment = "", trim_ws = FALSE, skip = 0, n_max = Inf, guess_max = 10000, lazy = FALSE, n_threads = bt_default_threads(), as = c("data.frame", "basetable") )
file |
Path to a delimited text file. |
delim |
Field delimiter. |
header |
Logical; does the first row hold column names? |
col_names |
Optional character vector of names, used only when
|
col_types |
|
col_select |
Optional integer positions or character names of the columns to keep. Other columns are not parsed. |
na |
Character vector of strings to read as |
quote |
Quoting character. |
comment |
Lines beginning with this one-character string are skipped
( |
trim_ws |
Logical; strip leading/trailing spaces and tabs from unquoted fields. |
skip |
Number of raw lines to discard before reading. |
n_max |
Maximum number of data rows to read ( |
guess_max |
Number of rows sampled for type guessing. |
lazy |
Logical; return numeric columns as lazily-parsed ALTREP vectors. |
n_threads |
Number of worker threads for the eager numeric fill. |
as |
Return |
With lazy = TRUE the integer and double columns are returned as ALTREP
vectors that parse their column only the first time it is touched, which
makes "read a few columns from a wide file" close to free.
A data.frame.
p <- tempfile(fileext = ".csv") write.csv(head(iris), p, row.names = FALSE) btread(p)p <- tempfile(fileext = ".csv") write.csv(head(iris), p, row.names = FALSE) btread(p)
A threaded C++ writer: each column is resolved to a plain C array on the R thread, then disjoint row ranges are formatted into private buffers and flushed in order.
btwrite( x, file, delim = ",", na = "NA", col_names = TRUE, quote = "\"", digits = 15, append = FALSE, n_threads = bt_default_threads() )btwrite( x, file, delim = ",", na = "NA", col_names = TRUE, quote = "\"", digits = 15, append = FALSE, n_threads = bt_default_threads() )
x |
A data.frame. |
file |
Output path. |
delim |
Field delimiter. |
na |
String to write for |
col_names |
Logical; write a header row? |
quote |
Quoting character; a field is quoted only if it contains the delimiter, the quote character, or a newline. |
digits |
Significant digits for double columns (passed to |
append |
Logical; append to |
n_threads |
Number of worker threads. |
file, invisibly.
p <- tempfile(fileext = ".csv") btwrite(head(iris), p) btread(p)p <- tempfile(fileext = ".csv") btwrite(head(iris), p) btread(p)
Distinct-value count (or proportion) per column
cardinality(data, cols, prop = FALSE)cardinality(data, cols, prop = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
prop |
Return the proportion of distinct values instead of the count. |
A named numeric vector.
For each position, take the label of the first condition that is TRUE
there. Conditions are a named list of equal-length logical vectors, in the
same shape as collapsevalues()'s groups: the name of an element is the
value used where that element is the first TRUE. Positions matching no
condition get default. NA in a condition counts as not matching.
casewhen(conditions, default = NA)casewhen(conditions, default = NA)
conditions |
A named list of equal-length logical vectors. Each name
is the value returned where its vector is the first |
default |
Value for positions where no condition holds. Default |
A vector as long as the conditions, holding matched labels and
default elsewhere.
x <- c(-3, 0, 4, 25) casewhen(list(neg = x < 0, low = x < 10), default = "high")x <- c(-3, 0, 4, 25) casewhen(list(neg = x < 0, low = x < 10), default = "high")
Round a date up to a unit
ceilingdate(x, unit = c("day", "week", "month", "year"))ceilingdate(x, unit = c("day", "week", "month", "year"))
x |
An atomic vector. |
unit |
Time unit to round to. |
A Date vector.
Center a vector at its mean
center(x)center(x)
x |
An atomic vector. |
A centered numeric vector.
Compare the columns of two tables
changedcols(old, new)changedcols(old, new)
old |
Baseline data.frame ("before" state). |
new |
Updated data.frame ("after" state), or replacement values when used for value substitution. |
See compareschema().
Rows whose key appears in both tables
changedrows(old, new, by = NULL)changedrows(old, new, by = NULL)
old |
Baseline data.frame ("before" state). |
new |
Updated data.frame ("after" state), or replacement values when used for value substitution. |
by |
Character vector of column names identifying groups or join keys. |
The matched rows from both tables, suffixed .old/.new.
Column classes
classes(data)classes(data)
data |
A data.frame. |
A basetable with one row per column giving its class.
Clean column names to a unique, syntactic form
cleannames(data)cleannames(data)
data |
A data.frame. |
data with cleaned column names.
Collapse factor levels into named groups
collapselevels(x, groups)collapselevels(x, groups)
x |
An atomic vector. |
groups |
Named list mapping a replacement label to the values it should collapse. |
A character vector with levels collapsed.
Collapse a vector into a single string
collapsetext(x, sep = "")collapsetext(x, sep = "")
x |
An atomic vector. |
sep |
Separator string. |
A single character string.
Collapse values into named groups
collapsevalues(x, groups)collapsevalues(x, groups)
x |
An atomic vector. |
groups |
Named list mapping a replacement label to the values it should collapse. |
x with values replaced by their group label.
Column names
colnames(data)colnames(data)
data |
A data.frame. |
A character vector of column names.
Column names shared by two tables
commonnames(x, y)commonnames(x, y)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
See common_names().
Remove every NULL element of .x, keeping the rest (including other
falsy-but-not-NULL values like NA, 0, or ""). The common companion
to map() when some calls legitimately return nothing – e.g. an empty
API response – and the NULLs must be dropped before foldr(),
rbindfill(), or similar.
compact(.x)compact(.x)
.x |
A list. |
.x with its NULL elements removed.
compact(list(1, NULL, 2, NULL, 3)) compact(list(a = 1, b = NULL, c = NA))compact(list(1, NULL, 2, NULL, 3)) compact(list(a = 1, b = NULL, c = NA))
Compare dimensions, names, types, missingness, and key overlap for two tables.
compare(x, y, by = NULL)compare(x, y, by = NULL)
x, y
|
Data frames or data tables to compare. |
by |
Optional key columns for overlap checks. |
A list of comparison tables.
Compare the schemas of two tables
compareschema(x, y)compareschema(x, y)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
A basetable describing shared and differing columns/types.
Create all combinations of selected columns and merge them back to the input.
completegrid(data, cols, fill = list())completegrid(data, cols, fill = list())
data |
A data frame or data table. |
cols |
Character vector of columns to complete across. |
fill |
Named list of values used to fill missing cells. |
A basetable containing the completed grid.
Columns with a single distinct non-missing value
constants(data)constants(data)
data |
A data.frame. |
A character vector of constant column names.
Test for a pattern match anywhere in the string
containstext(x, pattern, fixed = FALSE)containstext(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A logical vector.
Convert selected columns with a function
convertcols(data, cols, fun, ...)convertcols(data, cols, fun, ...)
data |
A data.frame. |
cols |
Character vector of column names. |
fun |
Function applied to each element, column, or group. |
... |
Additional arguments (unused, or passed through depending on the function). |
data with the selected columns converted.
Count rows in a table by one or more grouping columns.
count(data, by, sort = TRUE, name = "n", ...)count(data, by, sort = TRUE, name = "n", ...)
data |
A data frame, or a single path to a delimited text file for the fused one-pass file mode. |
by |
Character vector of grouping columns. |
sort |
Whether to sort by descending counts. Ties (groups with the
same count) are broken by ascending group key, so the row order is fully
determined by |
name |
Name of the count column. |
... |
In file mode, reader options such as |
A basetable with one row per group.
Count pattern matches per string
countmatch(x, pattern, fixed = FALSE)countmatch(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
An integer vector.
Return every combination of rows from x and y.
crossmerge(x, y)crossmerge(x, y)
x, y
|
Data frames or data tables to combine. |
A basetable containing the Cartesian product of the rows.
Cumulative mean
cumavg(x)cumavg(x)
x |
An atomic vector. |
A numeric vector.
Cumulative row counter
cumcount(x)cumcount(x)
x |
An atomic vector. |
An integer sequence along x.
Cumulative empirical distribution
cumedist(x)cumedist(x)
x |
An atomic vector. |
A numeric vector.
Difference between two dates
datediff(x, y, units = "days")datediff(x, y, units = "days")
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
units |
Unit used to express the difference. |
A numeric vector of differences.
Sequence of dates
dateseq(from, to, by = "day", length.out = NULL)dateseq(from, to, by = "day", length.out = NULL)
from |
Start date. |
to |
End date, or target range for rescaling. |
by |
Character vector of column names identifying groups or join keys. |
length.out |
Desired sequence length. |
A Date vector.
Extract the day of month
day(x)day(x)
x |
An atomic vector. |
An integer vector.
Dense rank of a vector
denserank(x)denserank(x)
x |
An atomic vector. |
An integer vector of dense ranks.
Summarize a table with basic counts, missingness, distinct values, and descriptive statistics.
describe(data, cols = NULL, top_n = 3)describe(data, cols = NULL, top_n = 3)
data |
A data frame or data table. |
cols |
Optional character vector of columns to describe. |
top_n |
Number of most frequent values to show for non-numeric columns. |
A basetable with one row per column.
Lagged difference
difference(x, lag = 1L)difference(x, lag = 1L)
x |
An atomic vector. |
lag |
Lag used for the difference. |
A numeric vector of differences.
Set difference of rows
diffrows(x, y, by = NULL)diffrows(x, y, by = NULL)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
Rows of x absent from y. With by = NULL, rows are compared
on every column of x, all of which must exist in y.
Return the number of rows and columns in a table.
dims(data)dims(data)
data |
A data frame or data table. |
A one-row data frame with the row and column counts.
Drop columns by name.
drop(data, cols)drop(data, cols)
data |
A data frame or data table. |
cols |
Character vector of column names to remove. |
A basetable with the selected columns removed.
Duplicated key combinations
duplicatekeys(data, by)duplicatekeys(data, by)
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
See duplicated_keys().
Duplicated column names
duplicatenames(data)duplicatenames(data)
data |
A data.frame. |
A character vector of the duplicated names.
Rows involved in a duplicate
duplicaterows(data)duplicaterows(data)
data |
A data.frame. |
A data.frame of the duplicated rows.
Columns that are entirely blank or missing
emptycols(data)emptycols(data)
data |
A data.frame. |
A character vector of column names.
Rows that are entirely blank or missing
emptyrows(data)emptyrows(data)
data |
A data.frame. |
A data.frame of the fully blank rows.
Test whether strings end with a pattern
endswith(x, pattern, fixed = FALSE)endswith(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A logical vector.
Compare two tables for equality
equaldata( x, y, ignoreorder = FALSE, ignorerownames = TRUE, tolerance = sqrt(.Machine$double.eps) )equaldata( x, y, ignoreorder = FALSE, ignorerownames = TRUE, tolerance = sqrt(.Machine$double.eps) )
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
ignoreorder |
Ignore row order when comparing. |
ignorerownames |
Ignore row names when comparing. |
tolerance |
Numeric join/comparison tolerance. |
A single logical value.
Compare two tables' rows for equality
equalrows(x, y, by = NULL)equalrows(x, y, by = NULL)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
A single logical value.
Add levels to a factor
expandlevels(x, levels)expandlevels(x, levels)
x |
An atomic vector. |
levels |
Character vector of factor levels. |
A factor including the additional levels.
Repeat each row of a table according to a count vector.
expandrows(data, times)expandrows(data, times)
data |
A data frame or data table. |
times |
A scalar or row-wise count vector giving repetitions. |
A basetable with repeated rows.
Extract the first pattern match
extract(x, pattern, ...)extract(x, pattern, ...)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
... |
Additional arguments (unused, or passed through depending on the function). |
A character vector of matches.
Extract all pattern matches
extractall(x, pattern, ...)extractall(x, pattern, ...)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
... |
Additional arguments (unused, or passed through depending on the function). |
A list of character vectors of matches.
Extract text between two markers
extractbetween(x, left, right)extractbetween(x, left, right)
x |
An atomic vector. |
left |
Left marker. |
right |
Right marker. |
A character vector.
Extract an integer value from text
extractint(x)extractint(x)
x |
An atomic vector. |
An integer vector.
Extract a numeric value from text
extractnum(x)extractnum(x)
x |
An atomic vector. |
A numeric vector.
Fill missing values both forward and backward within groups
fillboth(data, cols, by = NULL)fillboth(data, cols, by = NULL)
data |
A data.frame. |
cols |
Character vector of column names. |
by |
Character vector of column names identifying groups or join keys. |
data with cols filled in both directions.
Fill missing values in selected columns using the last observed value.
filldown(data, cols, by = NULL)filldown(data, cols, by = NULL)
data |
A data frame or data table. |
cols |
Character vector of columns to fill. |
by |
Optional grouping columns. |
A basetable with missing values filled downward.
Fill missing values in selected columns using the next observed value.
fillup(data, cols, by = NULL)fillup(data, cols, by = NULL)
data |
A data frame or data table. |
cols |
Character vector of columns to fill. |
by |
Optional grouping columns. |
A basetable with missing values filled upward.
First row within each group
firstby(data, by, order = NULL)firstby(data, by, order = NULL)
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
order |
Optional column(s) used to break ties before picking first/last rows. |
One row per group.
Move columns to the front
firstcols(data, cols)firstcols(data, cols)
data |
A data.frame. |
cols |
Character vector of column names. |
data with cols moved first.
n rowsFirst n rows
firstrows(data, n = 1L)firstrows(data, n = 1L)
data |
A data.frame. |
n |
Integer count. |
The first n rows of data.
Round a date down to a unit
floordate(x, unit = c("day", "week", "month", "year"))floordate(x, unit = c("day", "week", "month", "year"))
x |
An atomic vector. |
unit |
Time unit to round to. |
A Date vector.
Reduce .x with the two-argument function .f, associating from the right,
a thin wrapper around base::Reduce() with right = TRUE. With
.accumulate = TRUE the intermediate results are returned as well.
foldr(.x, .f, .init = NULL, .accumulate = FALSE, .simplify = TRUE)foldr(.x, .f, .init = NULL, .accumulate = FALSE, .simplify = TRUE)
.x |
A vector or list. |
.f |
A two-argument reducing function. |
.init |
Optional initial value. |
.accumulate |
Return intermediate accumulated values. |
.simplify |
Simplify accumulated results when possible. |
The folded value, or accumulated values when .accumulate = TRUE.
foldr(1:4, `+`) foldr(letters[1:4], paste0, .accumulate = TRUE)foldr(1:4, `+`) foldr(letters[1:4], paste0, .accumulate = TRUE)
Count the occurrences of values in a column, optionally within groups.
freq(data, column, by = NULL, prop = FALSE, sort = TRUE, ...)freq(data, column, by = NULL, prop = FALSE, sort = TRUE, ...)
data |
A data frame, or a single path to a delimited text file. In file mode the second argument is taken as the grouping column(s). |
column |
Name of the column to tabulate. |
by |
Optional grouping column or columns. |
prop |
Whether to include proportions. |
sort |
Whether to sort rows by descending frequency. |
... |
In file mode, reader options such as |
A basetable containing frequencies, and proportions when requested.
Return the first and last 'n' rows of a table.
headtail(data, n = 3)headtail(data, n = 3)
data |
A data frame or data table. |
n |
Number of rows to show from the start and end. |
A basetable containing the selected rows.
Extract the hour
hour(x)hour(x)
x |
An atomic vector. |
An integer vector.
Set intersection of rows
intersectrows(x, y, by = NULL)intersectrows(x, y, by = NULL)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
Rows of x also present in y. With by = NULL, rows are
compared on every column of x, all of which must exist in y.
Rows that fail a condition
invalidrows(data, condition)invalidrows(data, condition)
data |
A data.frame. |
condition |
A logical expression evaluated in the context of |
The rows of data for which condition is not TRUE.
Rows whose value is not in the allowed set
invalidvalues(data, column, allowed)invalidvalues(data, column, allowed)
data |
A data.frame. |
column |
Name of a single column. |
allowed |
Vector of permitted values. |
The rows of data with disallowed values.
Test whether an object is a basetable
is_basetable(x)is_basetable(x)
x |
An object. |
A single logical.
is_basetable(as_basetable(mtcars)) is_basetable(mtcars)is_basetable(as_basetable(mtcars)) is_basetable(mtcars)
Test for alphabetic-only strings
isalpha(x)isalpha(x)
x |
An atomic vector. |
A logical vector.
Test for alphanumeric-only strings
isalphanumeric(x)isalphanumeric(x)
x |
An atomic vector. |
A logical vector.
Test for blank (missing or empty) values
isblank(x)isblank(x)
x |
An atomic vector. |
A logical vector.
Test whether text looks like an email address
isemail(x)isemail(x)
x |
An atomic vector. |
A logical vector.
Test whether text looks like an integer
isintegertext(x)isintegertext(x)
x |
An atomic vector. |
A logical vector.
Test whether text looks numeric
isnumerictext(x)isnumerictext(x)
x |
An atomic vector. |
A logical vector.
Test whether text looks like a URL
isurl(x)isurl(x)
x |
An atomic vector. |
A logical vector.
Cardinality of a join key relationship
joinrelationship(x, y, by)joinrelationship(x, y, by)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
One of "one-to-one", "one-to-many", "many-to-one", "many-to-many".
Concatenate values element-wise
jointext(...)jointext(...)
... |
Additional arguments (unused, or passed through depending on the function). |
A character vector.
Return rows where selected columns are missing or blank.
keepmissing(data, cols = NULL, mode = c("any", "all"))keepmissing(data, cols = NULL, mode = c("any", "all"))
data |
A data frame or data table. |
cols |
Optional character vector of columns to inspect. |
mode |
Whether any or all selected columns must be missing. |
A basetable containing the matching rows.
Lag a vector
lagvalue(x, n = 1L, default = NA)lagvalue(x, n = 1L, default = NA)
x |
An atomic vector. |
n |
Integer count. |
default |
Value used to fill positions with no lagged observation. |
x shifted forward by n positions.
Last row within each group
lastby(data, by, order = NULL)lastby(data, by, order = NULL)
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
order |
Optional column(s) used to break ties before picking first/last rows. |
One row per group.
Move columns to the back
lastcols(data, cols)lastcols(data, cols)
data |
A data.frame. |
cols |
Character vector of column names. |
data with cols moved last.
n rowsLast n rows
lastrows(data, n = 1L)lastrows(data, n = 1L)
data |
A data.frame. |
n |
Integer count. |
The last n rows of data.
Lead a vector
leadvalue(x, n = 1L, default = NA)leadvalue(x, n = 1L, default = NA)
x |
An atomic vector. |
n |
Integer count. |
default |
Value used to fill positions with no leading observation. |
x shifted backward by n positions.
n charactersFirst n characters
left(x, n)left(x, n)
x |
An atomic vector. |
n |
Integer count. |
A character vector.
Position of the first pattern match
locate(x, pattern, fixed = FALSE)locate(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
An integer vector of match positions (see regexpr()).
Positions of all pattern matches
locateall(x, pattern, fixed = FALSE)locateall(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A list of match positions (see gregexpr()).
Convert to lower case
lower(x)lower(x)
x |
An atomic vector. |
A lower-case character vector.
Lump infrequent values into "Other"
lump(x, n = 5, other = "Other")lump(x, n = 5, other = "Other")
x |
An atomic vector. |
n |
Integer count. |
other |
Label used for values outside the top |
A character vector.
A small base-R-style mapping helper with no external dependency: apply .f
to each element of .x and return the results in a list, like
base::lapply() with a friendlier argument name.
map(.x, .f, ...)map(.x, .f, ...)
.x |
A vector or list. |
.f |
A function or function name. |
... |
Additional arguments passed to |
map() returns a list.
map(1:3, function(x) x + 1)map(1:3, function(x) x + 1)
x whose key is present in y
Rows of x whose key is present in y
matchedkeys(x, y, by)matchedkeys(x, y, by)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
Rows of x whose key is present in y.
Test for a full-string pattern match
matchestext(x, pattern, fixed = FALSE)matchestext(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A logical vector.
Merge two tables using shared keys.
merge(x, y, by = NULL, all = FALSE, all.x = all, all.y = all, sort = FALSE, suffixes = c(".x", ".y"))merge(x, y, by = NULL, all = FALSE, all.x = all, all.y = all, sort = FALSE, suffixes = c(".x", ".y"))
x, y
|
Data frames or data tables to merge. |
by |
Optional character vector of join columns. |
all, all.x, all.y
|
Controls for keeping unmatched rows. |
sort |
Whether to sort the result. |
suffixes |
Suffixes used for overlapping column names. |
A basetable containing the merged rows.
Substring between two positions
middle(x, start, end)middle(x, start, end)
x |
An atomic vector. |
start |
Start bound (inclusive). |
end |
End bound (inclusive). |
A character vector.
Extract the minute
minute(x)minute(x)
x |
An atomic vector. |
An integer vector.
Append logical indicators showing whether selected columns are missing or blank.
missingindicator(data, cols = NULL, prefix = "missing_")missingindicator(data, cols = NULL, prefix = "missing_")
data |
A data frame or data table. |
cols |
Optional character vector of columns to inspect. |
prefix |
Prefix used for the added indicator columns. |
A basetable with logical missingness indicator columns appended.
Summarize missing values by column or row
missingness(data, margin = c("column", "row"))missingness(data, margin = c("column", "row"))
data |
A data.frame. |
margin |
Summarize missingness |
A basetable with one row per column (or per row) describing the count and proportion of missing values.
Return rows where selected columns are missing or blank.
missingrows(data, cols = NULL, mode = c("any", "all"))missingrows(data, cols = NULL, mode = c("any", "all"))
data |
A data frame or data table. |
cols |
Optional character vector of columns to inspect. |
mode |
Whether any or all selected columns must be missing. |
A basetable containing the matching rows.
Extract the month
month(x)month(x)
x |
An atomic vector. |
An integer vector.
Move columns before or after another column
move(data, cols, before = NULL, after = NULL)move(data, cols, before = NULL, after = NULL)
data |
A data.frame. |
cols |
Character vector of column names. |
before |
Column identifying where to insert |
after |
Column identifying where to insert |
data with columns reordered.
NA
Recode matching values to NA
naif(x, values)naif(x, values)
x |
An atomic vector. |
values |
Vector or list of replacement values. |
x with matches replaced by NA.
NA with a valueReplace NA with a value
nato(x, value)nato(x, value)
x |
An atomic vector. |
value |
Value to test, assign, or match against. |
x with missing values replaced.
NA with an empty stringReplace NA with an empty string
natoblank(x)natoblank(x)
x |
An atomic vector. |
x with missing values replaced by "".
Return the number of columns in a table.
ncols(data)ncols(data)
data |
A data frame or data table. |
An integer scalar.
Nearest-key join
nearestmerge(x, y, by, tolerance = Inf)nearestmerge(x, y, by, tolerance = Inf)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
tolerance |
Numeric join/comparison tolerance. |
See rollingmerge().
Nearest string match
nearesttext(x, choices)nearesttext(x, choices)
x |
An atomic vector. |
choices |
Candidate strings to match against. |
A character vector of nearest matches.
nest() collapses the rows of each group into a data frame and stores those
data frames in a single list-column, giving one row per group. Groups appear
in order of first occurrence. Missing values in by form their own group.
nest(data, by, name = "data")nest(data, by, name = "data")
data |
A data frame. |
by |
Character vector of grouping columns. |
name |
Name of the new list-column. |
A basetable with the by columns and one list-column holding the
remaining columns of each group as a data frame.
nested <- nest(data.frame(g = c("a", "a", "b"), x = 1:3), by = "g") nested nested$data[[1]]nested <- nest(data.frame(g = c("a", "a", "b"), x = 1:3), by = "g") nested nested$data[[1]]
Unlike a plain equi-merge, nonequimerge() supports
inequality conditions between columns of x and y (for example,
matching each x row to every y row whose date range contains
x's date), in addition to any exact-match columns in by.
nonequimerge(x, y, by, ...)nonequimerge(x, y, by, ...)
x, y
|
Data frames or data tables to join. |
by |
Character vector of join conditions. A plain column name (present
in both |
... |
Currently ignored; reserved for future join
(e.g. |
A basetable with one row per matching x/y pair (an inner
join: rows of x with no matching y row are dropped).
x <- data.frame(id = 1, date = as.Date("2024-01-15")) y <- data.frame( id = 1, start_date = as.Date(c("2024-01-01", "2024-02-01")), end_date = as.Date(c("2024-01-31", "2024-02-28")), period = c("Jan", "Feb") ) nonequimerge(x, y, by = c("id", "date>=start_date", "date<=end_date"))x <- data.frame(id = 1, date = as.Date("2024-01-15")) y <- data.frame( id = 1, start_date = as.Date(c("2024-01-01", "2024-02-01")), end_date = as.Date(c("2024-01-31", "2024-02-28")), period = c("Jan", "Feb") ) nonequimerge(x, y, by = c("id", "date>=start_date", "date<=end_date"))
Normalize text encoding to UTF-8
normalizeencoding(x)normalizeencoding(x)
x |
An atomic vector. |
A character vector.
Normalize Unicode text
normalizeunicode(x)normalizeunicode(x)
x |
An atomic vector. |
A character vector (currently returned unchanged).
Return the number of rows in a table.
nrows(data)nrows(data)
data |
A data frame or data table. |
An integer scalar.
Drop rows where selected columns are missing or blank.
omitmissing(data, cols = NULL, mode = c("any", "all"))omitmissing(data, cols = NULL, mode = c("any", "all"))
data |
A data frame or data table. |
cols |
Optional character vector of columns to inspect. |
mode |
Whether any or all selected columns must be missing before a row is dropped. |
A basetable without the omitted rows.
Order rows by one or more columns
orderrows(data, by, decreasing = FALSE, na.last = TRUE)orderrows(data, by, decreasing = FALSE, na.last = TRUE)
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
decreasing |
Sort in decreasing order. |
na.last |
Placement of missing values when sorting. |
data sorted by by.
Rows whose value falls outside a range
outofrange(data, column, lower, upper)outofrange(data, column, lower, upper)
data |
A data.frame. |
column |
Name of a single column. |
lower |
Lower bound. |
upper |
Upper bound. |
The rows of data outside [lower, upper].
Join tables by overlapping interval ranges.
overlapmerge(x, y, startx, endx, starty, endy, by = NULL)overlapmerge(x, y, startx, endx, starty, endy, by = NULL)
x, y
|
Data frames or data tables to join. |
startx, endx
|
Interval bounds in |
starty, endy
|
Interval bounds in |
by |
Optional character vector of exact-match grouping columns. |
A basetable containing the overlap matches.
Pad text on both sides
padcenter(x, width, pad = " ")padcenter(x, width, pad = " ")
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
pad |
Padding character. |
A character vector padded to width.
Pad text on the left
padleft(x, width, pad = " ")padleft(x, width, pad = " ")
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
pad |
Padding character. |
A character vector padded to width.
Pad text on the right
padright(x, width, pad = " ")padright(x, width, pad = " ")
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
pad |
Padding character. |
A character vector padded to width.
Parse a currency string as a number
parsecurrency(x, strict = FALSE)parsecurrency(x, strict = FALSE)
x |
An atomic vector. |
strict |
Raise an error if any non-missing value fails to parse. |
A numeric vector.
Parse text as dates, trying multiple formats
parsedate(x, formats, tz = "UTC", strict = FALSE)parsedate(x, formats, tz = "UTC", strict = FALSE)
x |
An atomic vector. |
formats |
Candidate format strings tried in order. |
tz |
Time zone used when parsing. |
strict |
Raise an error if any non-missing value fails to parse. |
A Date vector.
Parse text as date-times, trying multiple formats
parsedatetime(x, formats, tz = "UTC", strict = FALSE)parsedatetime(x, formats, tz = "UTC", strict = FALSE)
x |
An atomic vector. |
formats |
Candidate format strings tried in order. |
tz |
Time zone used when parsing. |
strict |
Raise an error if any non-missing value fails to parse. |
A POSIXct vector.
Rows where parsing failed
parsefailures(x, fun, ...)parsefailures(x, fun, ...)
x |
An atomic vector. |
fun |
Function applied to each element, column, or group. |
... |
Additional arguments (unused, or passed through depending on the function). |
A basetable of the failed indices and values.
Parse text as integers
parseint(x, na = character(), strict = FALSE)parseint(x, na = character(), strict = FALSE)
x |
An atomic vector. |
na |
Values treated as missing before parsing. |
strict |
Raise an error if any non-missing value fails to parse. |
An integer vector.
Parse text as logicals
parselogical(x, na = character(), strict = FALSE)parselogical(x, na = character(), strict = FALSE)
x |
An atomic vector. |
na |
Values treated as missing before parsing. |
strict |
Raise an error if any non-missing value fails to parse. |
A logical vector.
Parse text as numbers
parsenum(x, decimal = ".", grouping = ",", na = character(), strict = FALSE)parsenum(x, decimal = ".", grouping = ",", na = character(), strict = FALSE)
x |
An atomic vector. |
decimal |
Decimal mark used in the input strings. |
grouping |
Thousands-grouping mark used in the input strings. |
na |
Values treated as missing before parsing. |
strict |
Raise an error if any non-missing value fails to parse. |
A numeric vector.
Parse a percentage string as a number
parsepercent(x, strict = FALSE)parsepercent(x, strict = FALSE)
x |
An atomic vector. |
strict |
Raise an error if any non-missing value fails to parse. |
A numeric vector.
Period-over-period percent change
percentchange(x)percentchange(x)
x |
An atomic vector. |
A numeric vector of percent changes.
Percentile rank of a vector
percentrank(x)percentrank(x)
x |
An atomic vector. |
A numeric vector of percentile ranks in [0, 1].
Select columns by name.
pick(data, cols)pick(data, cols)
data |
A data frame or data table. |
cols |
Character vector of column names. |
A basetable containing the selected columns.
Print a concise preview of a table with its row and column counts and a short summary of each variable.
preview(data, width = getOption("width"))preview(data, width = getOption("width"))
data |
A data frame or data table. |
width |
Maximum line width for printed output. |
The input data, invisibly.
Return a compact profile table for the variables in a data set.
profile(data, cols = NULL, top_n = 3)profile(data, cols = NULL, top_n = 3)
data |
A data frame or data table. |
cols |
Optional character vector of columns to profile. |
top_n |
Number of most frequent values to show for non-numeric columns. |
A basetable with one row per column.
Grouped counts with proportions
propcount(data, by, margin = NULL)propcount(data, by, margin = NULL)
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
margin |
Column(s) defining the totals used to compute proportions. |
A basetable of counts (and proportions when margin is supplied).
Bin a vector into quantile groups
quantilegroup(x, n = 5)quantilegroup(x, n = 5)
x |
An atomic vector. |
n |
Integer count. |
A factor of quantile bins.
Extract the calendar quarter
quarter(x)quarter(x)
x |
An atomic vector. |
An integer vector.
For each row of x, keep the row(s) of y whose value
column falls between x's lower and upper bounds
(inclusive), within the exact-match by key.
rangemerge(x, y, by, lower, upper, value)rangemerge(x, y, by, lower, upper, value)
x, y
|
Data frames or data tables to join. |
by |
Character vector of exact-match join columns, present in both
|
lower, upper
|
Single columns in |
value |
Single column in |
A basetable with one row per x row for each y row whose
value falls within [lower, upper] (matching on by); an
x row with no matching y row appears once with NA for
y's columns.
x <- data.frame(id = c(1, 1, 2), lower = c(0, 0, 0), upper = c(10, 10, 20)) y <- data.frame(id = c(1, 1, 2), val = c(5, 15, 5), label = c("a", "b", "c")) rangemerge(x, y, by = "id", lower = "lower", upper = "upper", value = "val")x <- data.frame(id = c(1, 1, 2), lower = c(0, 0, 0), upper = c(10, 10, 20)) y <- data.frame(id = c(1, 1, 2), val = c(5, 15, 5), label = c("a", "b", "c")) rangemerge(x, y, by = "id", lower = "lower", upper = "upper", value = "val")
Combine data frames by row, filling columns that are
missing from some inputs with NA.
rbindfill(..., id = NULL, fill = TRUE, typeconflict = c("error", "coerce"))rbindfill(..., id = NULL, fill = TRUE, typeconflict = c("error", "coerce"))
... |
Data frames to combine, or a single list of them. |
id |
Optional name for a source identifier column recording which input each row came from. |
fill |
Fill missing columns with |
typeconflict |
How to handle a column whose type differs across
inputs. |
A combined basetable.
Recode values by lookup (alias)
recode(x, old, new)recode(x, old, new)
x |
An atomic vector. |
old |
Baseline data.frame ("before" state). |
new |
Updated data.frame ("after" state), or replacement values when used for value substitution. |
See replacevalues().
Fold accented Latin letters to their unaccented ASCII form
("café" -> "cafe"), following ICU's Latin-ASCII mapping: covers the
Latin-1 Supplement and Latin Extended-A blocks, plus a few common extras
(ß -> "ss", Æ -> "AE", Romanian ș/ț). Characters with no
mapping, including non-Latin scripts, pass through unchanged. No Unicode
library dependency.
removeaccents(x)removeaccents(x)
x |
An atomic vector. |
A character vector the same length as x.
transliterate() for Greek and Cyrillic as well.
removeaccents(c("café", "naïve", "Zürich", "Kraków"))removeaccents(c("café", "naïve", "Zürich", "Kraków"))
Remove text matching a pattern (alias)
removeall(x, pattern, fixed = FALSE)removeall(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A character vector.
old but not in new
Rows present in old but not in new
removedrows(old, new, by = NULL)removedrows(old, new, by = NULL)
old |
Baseline data.frame ("before" state). |
new |
Updated data.frame ("after" state), or replacement values when used for value substitution. |
by |
Character vector of column names identifying groups or join keys. |
The removed rows.
Remove duplicate rows, optionally by key
removeduplicates(data, by = NULL, keep = c("first", "last", "none"))removeduplicates(data, by = NULL, keep = c("first", "last", "none"))
data |
A data.frame. |
by |
Character vector of column names identifying groups or join keys. |
keep |
Which duplicate to keep. |
data with duplicates removed.
Remove text matching a pattern
removetext(x, pattern, fixed = FALSE)removetext(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A character vector.
Rename columns using new = old pairs. Old column names may be supplied
as bare names or character strings.
renamecols(data, ...)renamecols(data, ...)
data |
A data.frame. |
... |
Named rename expressions, as |
data with the named columns renamed.
Rename columns with a function
renamewith(data, cols, fun)renamewith(data, cols, fun)
data |
A data.frame. |
cols |
Character vector of column names. |
fun |
Function applied to each element, column, or group. |
data with the selected columns renamed.
Reorder factor levels
reorderlevels(x, by)reorderlevels(x, by)
x |
An atomic vector. |
by |
Character vector of column names identifying groups or join keys. |
A factor with reordered levels.
Repair column names
repairnames(data, method = c("unique", "universal", "minimal"))repairnames(data, method = c("unique", "universal", "minimal"))
data |
A data.frame. |
method |
Cleaning strategy to apply to names. |
data with repaired column names.
Recode values by lookup (alias)
replaceall(x, old, new)replaceall(x, old, new)
x |
An atomic vector. |
old |
Existing value(s) to replace. |
new |
Replacement value(s) matching |
See replacevalues().
Replace selected columns with new values
replacecols(data, cols, values)replacecols(data, cols, values)
data |
A data.frame. |
cols |
Character vector of column names. |
values |
Vector or list of replacement values. |
data with the selected columns replaced.
Replace a pattern with replacement text
replacetext(x, pattern, replacement, fixed = FALSE)replacetext(x, pattern, replacement, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
replacement |
Replacement text. |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A character vector.
Recode values by lookup
replacevalues(x, old, new)replacevalues(x, old, new)
x |
An atomic vector. |
old |
Baseline data.frame ("before" state). |
new |
Updated data.frame ("after" state), or replacement values when used for value substitution. |
x with matched values replaced.
Replace values in selected columns where a condition holds
replacewhere(data, condition, cols, value)replacewhere(data, condition, cols, value)
data |
A data.frame. |
condition |
A logical expression evaluated in the context of |
cols |
Character vector of column names. |
value |
Value to test, assign, or match against. |
data with matching values replaced.
Rescale a vector to a new range
rescale(x, to = c(0, 1))rescale(x, to = c(0, 1))
x |
An atomic vector. |
to |
End date, or target range for rescaling. |
A rescaled numeric vector.
Reverse row order
reverse(data)reverse(data)
data |
A data.frame. |
data with rows in reverse order.
n charactersLast n characters
right(x, n)right(x, n)
x |
An atomic vector. |
n |
Integer count. |
A character vector.
Rolling window apply
rollapply( x, width, FUN, ..., align = c("right", "left", "center"), fill = NA, partial = FALSE )rollapply( x, width, FUN, ..., align = c("right", "left", "center"), fill = NA, partial = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
FUN |
Function applied to each rolling window. |
... |
Additional arguments (unused, or passed through depending on the function). |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
A vector with one result per window.
Join tables using a rolling match on the last key column.
rollingmerge(x, y, by, direction = c("backward", "forward", "nearest"), tolerance = Inf)rollingmerge(x, y, by, direction = c("backward", "forward", "nearest"), tolerance = Inf)
x, y
|
Data frames or data tables to join. |
by |
Character vector of join columns. The last column is treated as the rolling key. |
direction |
Rolling direction: backward, forward, or nearest. With
|
tolerance |
Maximum distance allowed for rolling matches. |
A basetable with rows from x joined to nearest matches in y.
Rolling maximum
rollmax( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollmax( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling maximums.
Rolling mean
rollmean( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollmean( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling means.
Rolling median
rollmedian( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollmedian( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling medians.
Rolling minimum
rollmin( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollmin( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling minimums.
Rolling product
rollprod( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollprod( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling products.
Rolling standard deviation
rollsd( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollsd( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling standard deviations.
Rolling sum
rollsum( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollsum( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling sums.
Rolling variance
rollvar( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )rollvar( x, width, align = c("right", "left", "center"), fill = NA, partial = FALSE, na.rm = FALSE )
x |
An atomic vector. |
width |
Target width, in characters or rolling-window size depending on the function. |
align |
Alignment of the rolling window relative to each position. |
fill |
Value used for positions where no window/result is available. |
partial |
Allow partial windows at the boundaries. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of rolling variances.
Round a date to the nearest unit
rounddate(x, unit = c("day", "week", "month", "year"))rounddate(x, unit = c("day", "week", "month", "year"))
x |
An atomic vector. |
unit |
Time unit to round to. |
A Date vector.
all() across columnsRow-wise all() across columns
rowall(data, cols = NULL, na.rm = FALSE)rowall(data, cols = NULL, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
na.rm |
Drop missing values before computing the result. |
A logical vector.
any() across columnsRow-wise any() across columns
rowany(data, cols = NULL, na.rm = FALSE)rowany(data, cols = NULL, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
na.rm |
Drop missing values before computing the result. |
A logical vector.
Apply a function row-wise
rowapply(data, cols = NULL, fun, ...)rowapply(data, cols = NULL, fun, ...)
data |
A data.frame. |
cols |
Character vector of column names. |
fun |
Function applied to each element, column, or group. |
... |
Additional arguments (unused, or passed through depending on the function). |
The result of fun applied to each row.
Count matches of a value across columns, per row
rowcount(data, cols = NULL, value = TRUE, na.rm = FALSE)rowcount(data, cols = NULL, value = TRUE, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
value |
Value to test, assign, or match against. |
na.rm |
Drop missing values before computing the result. |
An integer vector.
First non-missing value across columns, per row
rowfirst(data, cols = NULL, na.rm = FALSE)rowfirst(data, cols = NULL, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
na.rm |
Drop missing values before computing the result. |
A vector of first values.
Last non-missing value across columns, per row
rowlast(data, cols = NULL, na.rm = FALSE)rowlast(data, cols = NULL, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
na.rm |
Drop missing values before computing the result. |
A vector of last values.
Row-wise maximum across columns
rowmax(data, cols = NULL, na.rm = FALSE)rowmax(data, cols = NULL, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of row maximums.
Row-wise minimum across columns
rowmin(data, cols = NULL, na.rm = FALSE)rowmin(data, cols = NULL, na.rm = FALSE)
data |
A data.frame. |
cols |
Character vector of column names. |
na.rm |
Drop missing values before computing the result. |
A numeric vector of row minimums.
Row names
rownames(data)rownames(data)
data |
A data.frame. |
A character vector of row names.
Row position
rownumber(x)rownumber(x)
x |
An atomic vector. |
An integer sequence along x.
Test whether two tables share the same column names
sameschema(x, y)sameschema(x, y)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
A single logical value.
Sample a fraction of rows without replacement
samplefrac(data, frac, by = NULL)samplefrac(data, frac, by = NULL)
data |
A data.frame. |
frac |
Fraction of rows to sample. |
by |
Optional character vector of grouping columns; sample |
A random sample of rows.
n rows without replacementSample n rows without replacement
samplerows(data, n, by = NULL)samplerows(data, n, by = NULL)
data |
A data.frame. |
n |
Integer count. |
by |
Optional character vector of grouping columns; sample |
A random sample of n rows.
Extract the second
second(x)second(x)
x |
An atomic vector. |
An integer vector.
Keep rows in x whose keys exist in y.
semimerge(x, y, by)semimerge(x, y, by)
x, y
|
Data frames or data tables to compare. |
by |
Character vector of join columns. |
A basetable containing rows from x with matches in y.
Convert to sentence case
sentencecase(x)sentencecase(x)
x |
An atomic vector. |
A sentence-case character vector.
Split one column into several
separate( data, column, into, sep, remove = TRUE, extra = c("warn", "drop", "merge"), fill = c("warn", "left", "right") )separate( data, column, into, sep, remove = TRUE, extra = c("warn", "drop", "merge"), fill = c("warn", "left", "right") )
data |
A data.frame. |
column |
Name of a single column. |
into |
Names of the columns produced by splitting. |
sep |
Separator string. |
remove |
Drop the source column(s) after the operation. |
extra |
How to handle extra pieces beyond |
fill |
Value used for positions where no window/result is available. |
data with column split into into.
Controls the default thread count used by basetable's native reader and
writer when a verb does not receive n_threads explicitly.
setthreads( threads = NULL, restore_after_fork = NULL, percent = NULL, throttle = NULL )setthreads( threads = NULL, restore_after_fork = NULL, percent = NULL, throttle = NULL )
threads |
Integer thread count, or |
restore_after_fork |
Ignored; kept for API compatibility. |
percent |
Percentage of detected logical CPUs to use. |
throttle |
Ignored; kept for API compatibility. |
The previous thread count.
Nearest string match (alias)
similartext(x, choices)similartext(x, choices)
x |
An atomic vector. |
choices |
Candidate strings to match against. |
See nearesttext().
Split a table into pieces by one or more grouping columns. When data
is not a data frame, dispatches to base::split() so the classic
split(vector, factor) idiom keeps working with basetable attached.
split(data, by, drop = FALSE, keep.by = TRUE)split(data, by, drop = FALSE, keep.by = TRUE)
data |
A data frame or data table, or an atomic vector. |
by |
For a data frame, a character vector of grouping columns. For an
atomic vector, a factor (or object coercible to one) the same length as
|
drop |
Whether to drop empty groups. |
keep.by |
Whether to keep grouping columns in each piece. Ignored
when |
A named list of basetables (data frame input) or a named list of vectors
(atomic vector input, matching base::split()).
First piece after splitting on a separator
splitfirst(x, sep, fixed = FALSE)splitfirst(x, sep, fixed = FALSE)
x |
An atomic vector. |
sep |
Separator string. |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A character vector.
Last piece after splitting on a separator
splitlast(x, sep, fixed = FALSE)splitlast(x, sep, fixed = FALSE)
x |
An atomic vector. |
sep |
Separator string. |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A character vector.
Split text on a separator
splittext(x, sep, fixed = FALSE)splittext(x, sep, fixed = FALSE)
x |
An atomic vector. |
sep |
Separator string. |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A list of character vectors.
Trim and collapse internal whitespace
squish(x)squish(x)
x |
An atomic vector. |
A cleaned character vector.
Convert selected columns into long format with an indicator column.
stack(data, select = NULL, drop = FALSE)stack(data, select = NULL, drop = FALSE)
data |
A data frame or data table. |
select |
Optional character vector of columns to stack. |
drop |
Whether to drop rows with missing values. |
A basetable with a stacked value column.
Standardize a vector to mean 0, SD 1
standardize(x)standardize(x)
x |
An atomic vector. |
A standardized numeric vector.
Test whether strings start with a pattern
startswith(x, pattern, fixed = FALSE)startswith(x, pattern, fixed = FALSE)
x |
An atomic vector. |
pattern |
A regular expression (or fixed string when |
fixed |
Use fixed (non-regex) matching instead of regular expressions. |
A logical vector.
Base-faithful table manipulation helpers built around explicit arguments,
returning a basetable. See aggregate, count,
drop, merge, move,
orderrows, pick, renamecols,
split, stack, summaries,
uniquerows, unstack, and within
for the remaining core verbs, each documented on its own page.
subset(data, subset = NULL, select = NULL, drop = FALSE, by = NULL) transform(data, ..., .keep = TRUE, by = NULL) reshape(data, ..., direction)subset(data, subset = NULL, select = NULL, drop = FALSE, by = NULL) transform(data, ..., .keep = TRUE, by = NULL) reshape(data, ..., direction)
data |
A |
subset |
A base-style expression evaluated against columns. |
select, by
|
Character vectors naming columns. For |
drop, .keep
|
Control flags. |
... |
Additional expressions or arguments passed through to helpers. |
direction |
Additional operation-specific controls. |
Most functions return a basetable.
subset(mtcars, cyl == 6, select = c("mpg", "hp")) subset(mtcars, mpg > mean(mpg), by = "cyl") transform(mtcars, power = hp / wt) transform(mtcars, dev_mpg = mpg - mean(mpg), by = "cyl")subset(mtcars, cyl == 6, select = c("mpg", "hp")) subset(mtcars, mpg > mean(mpg), by = "cyl") transform(mtcars, power = hp / wt) transform(mtcars, dev_mpg = mpg - mean(mpg), by = "cyl")
Compute multiple named summary expressions, optionally by group.
summaries(data, by = NULL, ...)summaries(data, by = NULL, ...)
data |
A data frame or data table. |
by |
Optional grouping columns. |
... |
Named summary expressions. |
A basetable containing the requested summaries.
Build a publication-style summary table of one or more variables, optionally stratified by a grouping column, in the manner of a clinical "Table 1".
summarytab( data, vars = NULL, by = NULL, overall = TRUE, p_value = FALSE, digits = 1 )summarytab( data, vars = NULL, by = NULL, overall = TRUE, p_value = FALSE, digits = 1 )
data |
A data.frame. |
vars |
Character vector of variables to summarize. Defaults to every
column other than |
by |
Optional single column name used to stratify the summary. |
overall |
Include an "Overall" column alongside the by-group columns. |
p_value |
Include a column of between-group p-values. Requires |
digits |
Number of decimal places used when formatting numbers. |
A basetable with one row per variable (or variable level), and one
column per stratum plus Overall/p_value as requested.
Pairwise string distances
textdist(x, y)textdist(x, y)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
A numeric distance matrix (see utils::adist()).
Character length
textlen(x)textlen(x)
x |
An atomic vector. |
An integer vector of character counts.
Convert to title case
titlecase(x)titlecase(x)
x |
An atomic vector. |
A title-case character vector.
Reshape columns into key/value rows
tolong( data, cols, names = "variable", values = "value", idcols = NULL, na.rm = FALSE )tolong( data, cols, names = "variable", values = "value", idcols = NULL, na.rm = FALSE )
data |
A data.frame. |
cols |
Character vector of column names. |
names |
Name for the resulting key/value column, depending on the function. |
values |
Vector or list of replacement values. |
idcols |
Columns to keep as row identifiers. |
na.rm |
Drop missing values before computing the result. |
A long-format basetable.
Reshape rows into columns
towide(data, names, values, idcols = NULL, fun = NULL, fill = NA)towide(data, names, values, idcols = NULL, fun = NULL, fill = NA)
data |
A data.frame. |
names |
Column whose values become the new column names. |
values |
Column whose values fill the new columns. |
idcols |
Columns to keep as row identifiers. Defaults to every column
other than |
fun |
Function that reduces the values falling in one cell. When
|
fill |
Value used for cells with no matching row. |
A wide-format basetable.
Like removeaccents(), but also romanises the Greek and Cyrillic blocks
(the Greek and Cyrillic spellings of "Athena" and "Moskva" fold to those
ASCII forms), following ICU's
Any-Latin; Latin-ASCII mapping. Other non-Latin scripts (Han, Kana,
Arabic, Hebrew, Devanagari, Thai, ...) are left unchanged rather than
guessed at. No Unicode library dependency.
transliterate(x)transliterate(x)
x |
An atomic vector. |
A character vector the same length as x.
removeaccents() for Latin only.
# "Zurich", Greek "Athena", Cyrillic "Moskva" (spelt via code points so # this help page stays ASCII) greek <- intToUtf8(c(0x391, 0x3b8, 0x3ae, 0x3bd, 0x3b1)) cyrillic <- intToUtf8(c(0x41c, 0x43e, 0x441, 0x43a, 0x432, 0x430)) transliterate(c("Zurich", greek, cyrillic))# "Zurich", Greek "Athena", Cyrillic "Moskva" (spelt via code points so # this help page stays ASCII) greek <- intToUtf8(c(0x391, 0x3b8, 0x3ae, 0x3bd, 0x3b1)) cyrillic <- intToUtf8(c(0x41c, 0x43e, 0x441, 0x43a, 0x432, 0x430)) transliterate(c("Zurich", greek, cyrillic))
Transpose a table
transpose(data)transpose(data)
data |
A data.frame. |
A transposed basetable.
Call .f once per position across several equal-length vectors or lists,
passing the i-th element of each as a positional argument. The parallel-map
companion to map().
traverse(.l, .f, ...)traverse(.l, .f, ...)
.l |
A list of vectors or lists with a common length. |
.f |
A function or function name. |
... |
Additional arguments passed to |
traverse() returns a list.
traverse(list(a = 1:2, b = 10:11), function(a, b) a + b)traverse(list(a = 1:2, b = 10:11), function(a, b) a + b)
Trim leading and trailing whitespace
trim(x)trim(x)
x |
An atomic vector. |
A trimmed character vector.
Truncate text with an ellipsis
truncate(x, n, ellipsis = "...")truncate(x, n, ellipsis = "...")
x |
An atomic vector. |
n |
Integer count. |
ellipsis |
String appended to truncated text. |
A character vector.
Return the column name, class, and storage type for each variable in a table.
types(data)types(data)
data |
A data frame or data table. |
A data frame with one row per column.
Set union of rows
unionrows(x, y, by = NULL)unionrows(x, y, by = NULL)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
The union of x and y.
Return unique rows, optionally considering only selected columns. With a
single file path as data, it is a fused one-pass scan that returns the
distinct combinations of cols without ever materialising the file as R
vectors (see aggregate()'s file mode).
uniquerows(data, cols = NULL, .keep_all = FALSE, ...)uniquerows(data, cols = NULL, .keep_all = FALSE, ...)
data |
A data.frame, or a single path to a delimited text file. |
cols |
Optional character vector of columns used to determine
uniqueness. Required when |
.keep_all |
Keep all columns when |
... |
For the file form, passed to the file reader ( |
A basetable of the unique rows.
Count of distinct values per column
uniques(data)uniques(data)
data |
A data.frame. |
A named integer vector of distinct-value counts.
Combine several columns into one
unite(data, column, cols, sep = "_", remove = TRUE, na.rm = FALSE)unite(data, column, cols, sep = "_", remove = TRUE, na.rm = FALSE)
data |
A data.frame. |
column |
Name of a single column. |
cols |
Character vector of column names. |
sep |
Separator string. |
remove |
Drop the source column(s) after the operation. |
na.rm |
Drop missing values before computing the result. |
data with cols combined into column.
x absent from y
Distinct keys of x absent from y
unmatchedkeys(x, y, by)unmatchedkeys(x, y, by)
x |
An atomic vector. |
y |
An atomic vector, data.frame, or basetable, depending on the function. |
by |
Character vector of column names identifying groups or join keys. |
Rows of x whose key is not present in y.
unnest() is the inverse of nest(). Each element of a list-column is
expanded into rows, and the other columns are repeated to match. Elements
may be data frames (their columns are added) or atomic vectors (the values
are stored under the list-column's own name). Rows whose element is empty
are dropped.
unnest(data, cols)unnest(data, cols)
data |
A data frame with one or more list-columns. |
cols |
Character vector of list-columns to expand. When several are given, their elements must have matching lengths within each row. |
A basetable with one row per element.
nested <- nest(data.frame(g = c("a", "a", "b"), x = 1:3), by = "g") unnest(nested, "data")nested <- nest(data.frame(g = c("a", "a", "b"), x = 1:3), by = "g") unnest(nested, "data")
Reshape a stacked table back into wide form.
unstack(data, form, ...)unstack(data, form, ...)
data |
A data frame or data table. |
form |
A formula or equivalent description of the reshape. |
... |
Additional arguments passed to the underlying method. |
A basetable reshaped into wide format.
Update matching rows in x from y.
updatemerge(x, y, by, cols = NULL)updatemerge(x, y, by, cols = NULL)
x, y
|
Data frames or data tables. |
by |
Character vector of key columns. |
cols |
Optional columns to update. |
A basetable with selected columns updated from y.
Convert to upper case
upper(x)upper(x)
x |
An atomic vector. |
An upper-case character vector.
Extract the week of year
week(x)week(x)
x |
An atomic vector. |
An integer vector.
Extract the weekday name
weekday(x)weekday(x)
x |
An atomic vector. |
A character vector.
Winsorize a vector at given quantiles
winsorize(x, probs = c(0.01, 0.99))winsorize(x, probs = c(0.01, 0.99))
x |
An atomic vector. |
probs |
Quantile probabilities. |
A winsorized numeric vector.
Evaluate expressions inside a table and return the modified result.
within(data, expr)within(data, expr)
data |
A data frame or data table. |
expr |
An expression evaluated in the data's environment. |
A basetable containing the modified table.
Extract the year
year(x)year(x)
x |
An atomic vector. |
An integer vector.
Extract the day of year
yearday(x)yearday(x)
x |
An atomic vector. |
An integer vector.