From 210a700e9f9106de96733a362b45034e9dfd5ea2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dawid=20Budzy=C5=84ski?= Date: Fri, 30 Oct 2026 08:16:19 +0100 Subject: [PATCH] docs: clarify that p* functions are row-wise, not OpenMP-parallel (#88) --- README.md | 12 +++++++----- _pkgdown.yml | 4 ++-- man/psum.Rd | 2 ++ vignettes/introduction.Rmd | 20 ++++++++++---------- 4 files changed, 21 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 4a5fbc6..870b5fe 100644 --- a/README.md +++ b/README.md @@ -23,16 +23,18 @@ install.packages("kit", repos = "https://fastverse.r-universe.dev") ## Features -### Parallel Statistical Functions +### Row-wise Statistical Functions -Vector-valued functions operating in parallel over vectors or data frames: +Vector-valued functions that combine several vectors or data frame columns element by element: -- **`psum`, `pprod`, `pmean`**: Parallel sum, product, and mean -- **`fpmin`, `fpmax`, `prange`**: (Fast) parallel minimum, maximum, and range -- **`pall`, `pany`**: Parallel all/any operations +- **`psum`, `pprod`, `pmean`**: Row-wise sum, product, and mean +- **`fpmin`, `fpmax`, `prange`**: Row-wise minimum, maximum, and range +- **`pall`, `pany`**: Row-wise all/any operations - **`pcount`, `pcountNA`**: Count occurrences of values or NAs - **`pfirst`, `plast`**: First/last non-missing values +The word "parallel" in their names means they work across several vectors at once, not that they use multiple threads. These functions are single-threaded C code. Only `iif()`, `nswitch()`, `vswitch()`, `psort()`, and `charToFact()` can use OpenMP, and only when you raise `options(kit.nThread)` above its default of 1. + ```r x <- c(1, 3, NA, 5) y <- c(2, NA, 4, 1) diff --git a/_pkgdown.yml b/_pkgdown.yml index 964026c..8991669 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -44,8 +44,8 @@ navbar: reference: -- title: "Parallel Statistical Functions" - desc: "Vector-valued (statistical) functions operating in parallel over vectors passed as arguments, or a single list of vectors/data frame." +- title: "Row-wise Statistical Functions" + desc: "Vector-valued (statistical) functions that combine several vectors passed as arguments, or a single list of vectors/data frame, element by element." - contents: - parallel-funs - title: "Vectorised and Nested Switches" diff --git a/man/psum.Rd b/man/psum.Rd index 7c6e3f5..7a696ca 100644 --- a/man/psum.Rd +++ b/man/psum.Rd @@ -18,6 +18,8 @@ \title{Parallel (Statistical) Functions} \description{ Vector-valued (statistical) functions operating in parallel over vectors passed as arguments, or a single list of vectors (such as a data frame). Similar to \code{\link{pmin}} and \code{\link{pmax}}, except that these functions do not recycle vectors. + +The word "parallel" here means that the functions work across several vectors at once. It does not mean multi-threading: these functions are single-threaded C code. } \usage{ psum(..., na.rm = FALSE) diff --git a/vignettes/introduction.Rmd b/vignettes/introduction.Rmd index b2f5587..aef1572 100644 --- a/vignettes/introduction.Rmd +++ b/vignettes/introduction.Rmd @@ -24,31 +24,31 @@ library(kit) Key features include: -* **Parallel statistical functions**: Row-wise operations (`psum`, `pmean`, `pfirst`) using OpenMP. +* **Row-wise statistical functions**: Operations across several vectors at once (`psum`, `pmean`, `pfirst`). These functions are single-threaded C code. * **Vectorized conditionals**: Fast `if-else` logic (`iif`, `nif`, `vswitch`) that preserves attributes. * **Efficient set operations**: Faster `unique`, `duplicated`, and `count` for vectors and data frames. * **Partial sorting**: Retrieve top N elements without sorting the entire vector (`topn`). * **Factor utilities**: Fast character-to-factor conversion (`charToFact`) and level manipulation (`setlevels`). -Most functions are implemented in C and support multi-threading where applicable, making them significantly faster than their base R equivalents on large datasets. +Most functions are implemented in C, making them significantly faster than their base R equivalents on large datasets. Five functions can use OpenMP when you raise `options(kit.nThread)` above its default of 1: `iif()`, `nswitch()`, `vswitch()`, `psort()`, and `charToFact()`. The other functions, including the `p*` functions, run on one thread. -## Parallel Statistical Functions +## Row-wise Statistical Functions Computing row-wise statistics across multiple vectors or data frame columns is a common task. While base R has `pmin()` and `pmax()`, it lacks efficient equivalents for sum, mean, or product. **kit** fills this gap. ### Row-wise Arithmetic -`psum()`, `pmean()`, and `pprod()` compute parallel sum, mean, and product respectively. They accept multiple vectors or a single list/data frame. +`psum()`, `pmean()`, and `pprod()` compute row-wise sum, mean, and product respectively. They accept multiple vectors or a single list/data frame. ```{r} x <- c(1, 3, NA, 5) y <- c(2, NA, 4, 1) z <- c(3, 4, 4, 1) -# Parallel sum +# Row-wise sum psum(x, y, z, na.rm = TRUE) -# Parallel mean +# Row-wise mean pmean(x, y, z, na.rm = TRUE) ``` @@ -61,20 +61,20 @@ psum(df) ### Row-wise Min, Max, and Range -`fpmin()`, `fpmax()`, and `prange()` compute parallel minimum, maximum, and range (max - min) respectively. They complement base R's `pmin()` and `pmax()`, providing greater performance and the ability to work efficiently with data frames. +`fpmin()`, `fpmax()`, and `prange()` compute row-wise minimum, maximum, and range (max - min) respectively. They complement base R's `pmin()` and `pmax()`, providing greater performance and the ability to work efficiently with data frames. ```{r} x <- c(1, 3, NA, 5) y <- c(2, NA, 4, 1) z <- c(3, 4, 4, 1) -# Parallel minimum +# Row-wise minimum fpmin(x, y, z, na.rm = TRUE) -# Parallel maximum +# Row-wise maximum fpmax(x, y, z, na.rm = TRUE) -# Parallel range (max - min) +# Row-wise range (max - min) prange(x, y, z, na.rm = TRUE) ```