Package {thisutils}

Type:	Package
Title:	Reliable Utilities for Reusable Research Workflows
Version:	0.5.0
Date:	2026-08-13
Maintainer:	Meng Xu <mengxu98@qq.com>
Description:	Provides reusable building blocks for research packages across matrix representation, numerical computation, neighborhood evaluation, controlled execution, and runtime interoperability. Core tools preserve declared sparse semantics, expose dense-memory and output boundaries, standardize neighborhood and classification results, and align serial and parallel result and error behavior. Additional helpers support structured messages, optional dependency checks, and common statistical workflows.
License:	MIT + file LICENSE
URL:	https://mengxu98.github.io/thisutils/
BugReports:	https://github.com/mengxu98/thisutils/issues
Depends:	R (≥ 4.1.0)
Imports:	callr (≥ 3.5.0), cli, methods, Matrix, pak, parallel, ps, Rcpp, rlang, stats, utils
Suggests:	BiocNeighbors, knitr, remotes, rmarkdown, testthat (≥ 3.1.7)
LinkingTo:	cli, Rcpp
Config/Needs/website:	mengxu98/thistemplate
Config/testthat/edition:	3
VignetteBuilder:	knitr
Encoding:	UTF-8
RoxygenNote:	7.3.3
Language:	en-US
NeedsCompilation:	yes
Packaged:	2026-08-13 15:23:52 UTC; mx
Author:	Meng Xu [aut, cre], Haoliang Zhu [aut]
Repository:	CRAN
Date/Publication:	2026-08-21 10:40:02 UTC

Reliable Utilities for Reusable Research Workflows

Description

Reusable building blocks for matrix representation, numerically stable and resource-controlled computation, neighborhood and classification evaluation, consistent serial/parallel execution, structured messages, and research-package interoperability.

Author(s)

Xu Meng (Maintainer), mengxu98@qq.com

Source

https://mengxu98.github.io/thisutils/

See Also

Useful links:

• https://mengxu98.github.io/thisutils/

• Report bugs at https://github.com/mengxu98/thisutils/issues

Value selection operator

Description

This operator returns the left side if it's not NULL, otherwise it returns the right side.

Usage

a %ss% b

Arguments

Value

a if it is not NULL, otherwise b.

Examples

NULL %ss% 10
5 %ss% 10

Add a package file and print package information

Description

Add a package file and print package information

Usage

add_pkg_file(
  use_figlet = TRUE,
  figlet_font = "Slant",
  colors = c("red", "yellow", "green", "magenta", "cyan", "yellow", "green", "white",
    "magenta", "cyan"),
  verbose = TRUE
)

Arguments

Value

Creates a file named ⁠R/<pkg_name>-package.R⁠.

Convert matrix into dense/sparse matrix

Description

Convert matrix into dense/sparse matrix

Usage

as_matrix(x, return_sparse = FALSE)

Arguments

Value

A dense or sparse matrix.

Examples

m <- simulate_sparse_matrix(
  1000, 1000,
  decimal = 3
)

a <- as_matrix(m)
a[1:5, 1:5]

b <- as_matrix(m, return_sparse = TRUE)
b[1:5, 1:5]

Capitalize the first letter of each word

Description

Capitalize the first letter of each word

Usage

capitalize(x, force_tolower = FALSE)

Arguments

Examples

x <- c(
  "hello world",
  "hello World"
)
capitalize(x)

Check CI environment

Description

Check CI environment

Usage

check_ci_env()

Value

A logical value.

Check if a package is installed with the specified version

Description

Check if a package is installed with the specified version

Usage

check_pkg_status(pkg, version = NULL, lib = .libPaths()[1])

Arguments

Value

TRUE if the package is installed with the specified version, FALSE otherwise.

Check and install R packages

Description

Check and install R packages

Usage

check_r(
  packages,
  lib = .libPaths()[1],
  dependencies = NA,
  force = FALSE,
  install = TRUE,
  timeout = Inf,
  load = FALSE,
  cores = NULL,
  verbose = TRUE
)

Arguments

Details

GitHub packages are normally installed with pak. If pak cannot parse a GitHub package's DESCRIPTION file, check_r() retries that package with the optional remotes package. This preserves the fast dependency resolution path while supporting legacy repositories with malformed metadata. When PKG_SUBPROCESS_TIMEOUT is unset, the pak subprocess startup window is temporarily increased to 30 seconds and restored before returning.

Value

Package installation status.

Check sparsity of matrix

Description

Check sparsity of matrix

Usage

check_sparsity(x)

Arguments

Value

Sparsity of matrix.

Compute classification metrics

Description

Compute multi-class classification metrics from predicted and true labels, including accuracy, macro-F1, purity, NMI, ARI, and rare-class recall.

Usage

classification_metrics_compute(predicted, truth, rare_threshold = 0.05)

Arguments

Value

A list with the following components:

accuracy

Overall accuracy (scalar).

macro_f1

Macro-averaged F1 score (scalar).

purity

Cluster purity (scalar).

nmi

Normalized Mutual Information (scalar).

ari

Adjusted Rand Index (scalar).

rare_recall

Mean recall on rare classes (scalar, or NA if no rare classes).

class_table

A data frame of per-class precision, recall, F1, and support.

Examples

predicted <- c("A", "A", "B", "B", "C")
truth <- c("A", "B", "B", "B", "C")
classification_metrics_compute(predicted, truth)

Collapse sparse matrix rows by group

Description

Collapse sparse matrix rows by group

Usage

collapse_sparse_rows(matrix, group)

Arguments

Value

A sparse matrix with rows collapsed by 'group'.

Examples

mat <- Matrix::Matrix(
  matrix(c(1, 0, 2, 0, 3, 4), nrow = 3, byrow = TRUE),
  sparse = TRUE
)
collapse_sparse_rows(mat, c("g1", "g1", "g2"))

Compute Local Inverse Simpson's Index (LISI)

Description

Compute per-cell Local Inverse Simpson's Index (LISI) scores for one or more categorical variables. This is a clean-room reimplementation of the immunogenomics/LISI.

Usage

compute_lisi(
  X,
  meta_data,
  label_colnames,
  perplexity = 30,
  tol = 1e-05,
  max_iter = 50,
  knn_algorithm = c("auto", "brute_force", "clustered"),
  n_threads = NULL,
  max_dense_bytes = Inf
)

Arguments

Details

Both nearest-neighbor strategies are exact. Sparse X is converted to a dense matrix before neighbor search; this conversion is included in the max_dense_bytes check.

Value

A data frame with one row per cell and one column per label.

References

Korsunsky I, Millard N, Fan J, et al. Fast, sensitive and accurate integration of single-cell data with Harmony. Nature Methods (2019). https://www.nature.com/articles/s41592-019-0619-0

LISI reference implementation: https://github.com/immunogenomics/LISI

Examples

set.seed(1)
X <- rbind(
  matrix(stats::rnorm(100, mean = -1), ncol = 2),
  matrix(stats::rnorm(100, mean = 1), ncol = 2)
)
meta_data <- data.frame(
  batch = rep(c("A", "B"), each = 50),
  group = sample(c("g1", "g2"), 100, replace = TRUE)
)

res <- compute_lisi(
  X, meta_data,
  c("batch", "group"),
  perplexity = 10
)
head(res)
boxplot(res)

Download file from the Internet

Description

Download file from the Internet

Usage

download(
  url,
  destfile,
  methods = c("auto", "wget", "libcurl", "curl", "wininet", "internal"),
  quiet = FALSE,
  ...,
  max_tries = 2
)

Arguments

Compute row variances

Description

Compute sample or population variances for each row of a dense or sparse matrix without densifying sparse input.

Usage

fast_row_vars(x, unbiased = TRUE)

Arguments

Value

A numeric vector of row variances. Row names are retained when available. Matrices with zero columns return 'NA' for every row. A one-column matrix returns 'NA' for sample variance and '0' for population variance.

Examples

fast_row_vars(matrix(c(1, 2, 3, 4), nrow = 2))

The figlet function

Description

Create ASCII art text using figlet.

Usage

figlet(
  text,
  font = "Slant",
  width = getOption("width", 80),
  justify = "left",
  absolute = FALSE,
  strip = TRUE
)

Arguments

Value

An object of class figlet_text which is a character vector with a handy print method.

References

https://github.com/richfitz/rfiglet, https://github.com/jbkunst/figletr, https://www.figlet.org/

Examples

figlet("thisutils")

Get a figlet font

Description

Get a figlet font

Usage

figlet_font(font)

Arguments

Value

A 'figlet_font' object for use with [figlet]

Keep matrix rows with nonzero variance

Description

Subset a matrix to selected rows and discard rows with missing or zero variance. Sparse input remains sparse.

Usage

filter_nonzero_variance_features(x, features)

Arguments

Value

'x' restricted to selected rows whose variance is positive.

Examples

filter_nonzero_variance_features(
  matrix(c(1, 1, 1, 1, 1, 2), nrow = 2),
  features = 1:2
)

Get a function from a namespace

Description

Get a function from a namespace

Usage

get_namespace_fun(pkg, fun)

Arguments

Value

Function.

Get the verbose option

Description

Get the verbose option from the global options or the local argument.

Usage

get_verbose(verbose = NULL)

Arguments

Value

The verbose option.

Examples

get_verbose()
get_verbose(verbose = FALSE)
get_verbose(verbose = TRUE)

options(log_message.verbose = FALSE)
get_verbose()
get_verbose(verbose = TRUE)

options(log_message.verbose = TRUE)
get_verbose()

options(log_message.verbose = NULL)

Invoke a function with a list of arguments

Description

Invoke a function with a list of arguments

Usage

invoke_fun(.fn, .args = list(), ..., .env = rlang::caller_env())

Arguments

Examples

f <- function(x, y) {
  x + y
}
invoke_fun(f, list(x = 1, y = 2))
invoke_fun("f", list(x = 1, y = 2))
invoke_fun("f", x = 1, y = 2)

Check if the system is running on Apple Silicon

Description

Check if the system is running on Apple Silicon

Usage

is_apple_silicon()

Value

A logical value.

Check if the operating system is Linux

Description

Check if the operating system is Linux

Usage

is_linux()

Value

A logical value.

Check if the operating system is macOS

Description

Check if the operating system is macOS

Usage

is_osx()

Value

A logical value.

Detect outliers using MAD (Median Absolute Deviation)

Description

Detect outliers using MAD (Median Absolute Deviation)

Usage

is_outlier(
  x,
  nmads = 2.5,
  constant = 1.4826,
  type = c("both", "lower", "higher")
)

Arguments

Value

Numeric vector of indices indicating the positions of outliers in x.

Examples

x <- c(1, 2, 3, 4, 5, 100)
is_outlier(x) # returns 6

x <- c(3, 4, 5, NA, 6, 7)
is_outlier(x, nmads = 1.5, type = "lower") # returns 4

x <- c(10, 20, NA, 15, 35)
is_outlier(x, nmads = 2, type = "higher") # returns 3, 5

Check if the operating system is Windows

Description

Check if the operating system is Windows

Usage

is_windows()

Value

A logical value.

Print formatted message

Description

Integrate the message printing function with the cli package, and the base::message function. The message could be suppressed by base::suppressMessages.

Usage

log_message(
  ...,
  expr = NULL,
  verbose = NULL,
  message_type = c("info", "success", "warning", "error", "running", "ask"),
  cli_model = TRUE,
  level = 1,
  symbol = "  ",
  text_color = NULL,
  back_color = NULL,
  text_style = NULL,
  multiline_indent = FALSE,
  timestamp = TRUE,
  timestamp_format = paste0("[", format(Sys.time(), "%Y-%m-%d %H:%M:%S"), "] "),
  timestamp_style = FALSE,
  plain_text = FALSE,
  .envir = parent.frame(),
  .frame = .envir
)

Arguments

Value

Formated message, a logical value (TRUE/FALSE/NA) if message_type = "ask", or the evaluated result of expr if expr is supplied.

References

https://cli.r-lib.org/articles/index.html

Examples

# basic usage
log_message("Hello, ", "world!")

log_message("hello, world!")

log_message("Hello, world!", timestamp = FALSE)

log_message(
  "Hello, ", "world!",
  message_type = "success"
)

log_message(
  "Hello, world!",
  message_type = "warning"
)

log_message(
  "Processing data...",
  message_type = "running"
)

log_message(
  "Hello, ", "world!",
  cli_model = FALSE
)


# suppress messages
suppressMessages(log_message("Hello, world!"))
log_message("Hello, world!", verbose = FALSE)
options(log_message.verbose = FALSE)
log_message("Hello, world!")

# for global verbose option
options(log_message.verbose = TRUE)
log_message("Hello, world!", verbose = FALSE)
options(log_message.verbose = NULL)


# cli inline markup
log_message("{.arg abc} is a argument")

## 'message' can not deal with cli inline markup
message("hello, {.code world}!")

log_message("{.val list('abc')} is a {.cls {class(list('abc'))}}")

log_message("{.code lm(y ~ x)} is a code example")

log_message("{.dt List}list('abc')")

log_message("address: {.email example@example.com}")

log_message("{.emph R} is a programming language")

log_message("{.envvar R_HOME}")

log_message("{.file log_message.R} is a file")

log_message("{.fn lm} is a function")

log_message("{.fun lm} is a function")

log_message("{.help lm} to get help")

log_message("... see {.help [{.fun lm}](stats::lm)} to learn more")

log_message(
  "See the {.href [cli homepage](https://cli.r-lib.org)} for details"
)

log_message("press {.kbd ENTER}")

log_message("press {.key ENTER}")

log_message("URL: {.url https://cli.r-lib.org}")

log_message("Some {.field field}")

log_message("{.path /usr/bin/R} is a path")

log_message("{.pkg cli} is a package")

log_message("{.val object} is a variable")

log_message("{.run Rscript log_message.R} is a runnable file")

log_message("{.str object} is a string")

log_message("{.strong abc} is a strong string")

log_message("{.topic stats::lm} is a topic")

log_message("{.vignette cli} is a vignette")


# set indentation
log_message("Hello, world!", level = 2)

log_message("Hello, world!", symbol = "->")

log_message(
  "Hello, world!",
  symbol = "#####",
  level = 3
)

# color formatting
log_message(
  "This is a red message",
  text_color = "#ff9900"
)

log_message(
  "This is a message with background",
  back_color = "#EE4000"
)

log_message(
  "This is a message with both text and background",
  text_color = "white",
  back_color = "cyan"
)

log_message(
  "This is a message with background",
  back_color = "#EE4000",
  cli_model = FALSE
)

log_message(
  "This is a message with both text and background",
  text_color = "red",
  back_color = "cyan",
  cli_model = FALSE
)

log_message(
  "Hex color with {.arg cli_model = FALSE}",
  text_color = "#FF5733",
  cli_model = FALSE
)

log_message(
  "Bright red text",
  text_color = "br_red"
)

log_message(
  "Bright background",
  back_color = "br_yellow"
)

log_message(
  "Combined grey and style",
  text_color = "grey",
  text_style = "bold"
)

# text style formatting
log_message(
  "Bold message",
  text_style = "bold"
)

log_message(
  "Italic message",
  text_style = "italic"
)

log_message(
  "Underlined message",
  text_style = "underline"
)

log_message(
  "Combined styles",
  text_style = c("bold", "underline")
)

log_message(
  "Color and style",
  text_color = "blue",
  text_style = c("bold", "italic")
)

log_message(
  "Hex color and style",
  text_color = "#FF5733",
  text_style = c("bold", "underline")
)


# multiline message
log_message(
  "Line 1\nLine 2\nLine 3",
  multiline_indent = TRUE,
  text_style = "italic"
)

log_message(
  "Multi-line\ncolored\nmessage",
  text_color = "blue",
  text_style = "italic"
)

log_message(
  "Multi-line\ncolored\nmessage",
  text_color = "blue",
  timestamp = FALSE
)

# timestamp styling
log_message(
  "Multi-line message\nwith timestamp styling",
  text_color = "red",
  text_style = "bold",
  timestamp_style = TRUE
)

log_message(
  "Multi-line message\nwithout timestamp styling",
  text_color = "#669999",
  text_style = c("bold", "italic")
)


# combine cli package and log_message
log_message(
  cli::col_green(
    "I am a green line ",
    cli::col_blue(
      cli::style_underline(
        cli::style_bold("with a blue substring")
      )
    ),
    " that becomes green again!"
  )
)

# cli variables
fun <- function(x = 1) {
  log_message("{.val x}")
  log_message("{.val {x}}")
  log_message("{.val {x + 1}}")
}
fun()


# print objects directly
df <- data.frame(
  x = 1:3,
  y = letters[1:3],
  z = c(" a", "b  ", "c")
)
log_message("Content:\n", df)

# interactive prompt
if (interactive()) {
  log_message(
    "Do you want to continue?",
    message_type = "ask"
  )
}

# capture output from another expression
fun <- function() {
  cat("This is standard output\n")
  message("This is a message")
  return(1 + 1)
}
fun()

log_message(
  expr = fun(),
  message_type = "running"
)

Process matrix

Description

Process matrix

Usage

matrix_process(
  matrix,
  method = c("raw", "zscore", "fc", "log2fc", "log1p"),
  ...
)

Arguments

Value

A processed matrix.

Examples

m <- simulate_sparse_matrix(10, 10)
matrix_process(m, method = "raw")
matrix_process(m, method = "zscore")
matrix_process(m, method = "fc")
matrix_process(m, method = "log2fc")
matrix_process(m, method = "log1p")
m <- as_matrix(m)
matrix_process(m, method = function(x) x / rowMeans(x))

Switch matrix to table

Description

Switch matrix to table

Usage

matrix_to_table(
  matrix,
  row_names = NULL,
  col_names = NULL,
  threshold = 0,
  keep_zero = TRUE
)

Arguments

Details

With keep_zero = FALSE, sparse input is traversed through its stored entries and implicit zeros are not materialized. The backward-compatible default, keep_zero = TRUE, emits every selected matrix position, including implicit sparse zeros, and therefore requires time and output memory proportional to the selected nrow * ncol. When zeros are omitted, an all-zero row or column is absent from the table and cannot be reconstructed by table_to_matrix() without separate dimension metadata.

Value

A table with three columns: row, col, and value.

See Also

table_to_matrix

Examples

test_matrix <- simulate_sparse_matrix(10, 10)
colnames(test_matrix) <- paste0("c", 1:10)
rownames(test_matrix) <- paste0("r", 1:10)
table <- matrix_to_table(test_matrix)
matrix_new <- table_to_matrix(table)
test_matrix <- test_matrix[rownames(matrix_new), colnames(matrix_new)] |>
  as_matrix()
identical(test_matrix, matrix_new)

matrix_to_table(
  test_matrix,
  threshold = 2
)

matrix_to_table(
  test_matrix,
  row_names = c("r1", "r2"),
  col_names = c("c1", "c2")
)

Maximum depth of a list

Description

Maximum depth of a list

Usage

max_depth(x, depth = 0)

Arguments

Examples

x <- list(
  a = list(b = list(c = 1)),
  d = list(e = list(f = 2))
)
max_depth(x)

Maximum P-value

Description

Maximum P-value

Usage

maximump(p, alpha = 0.05, log.p = FALSE)

Arguments

Examples

p <- c(0.01, 0.02, 0.03, 0.04, 0.05)
maximump(p)
maximump(p, alpha = 0.01)
maximump(p, log.p = TRUE)

Mean P-value

Description

Mean P-value

Usage

meanp(p)

Arguments

Examples

p <- c(0.01, 0.02, 0.03, 0.04, 0.05)
meanp(p)

Minimum P-value

Description

Minimum P-value

Usage

minimump(p, alpha = 0.05, log.p = FALSE)

Arguments

Examples

p <- c(0.01, 0.02, 0.03, 0.04, 0.05)
minimump(p)
minimump(p, alpha = 0.01)
minimump(p, log.p = TRUE)

Normalize numeric vector

Description

Normalize numeric vector

Usage

normalization(x, method = "max_min", na_rm = TRUE, ...)

Arguments

Value

Normalized numeric vector.

Examples

x <- c(runif(2), NA, -runif(2))
x
normalization(x, method = "max_min")
normalization(x, method = "maximum")
normalization(x, method = "sum")
normalization(x, method = "softmax")
normalization(x, method = "z_score")
normalization(x, method = "mad")
normalization(x, method = "unit_vector")
normalization(x, method = "unit_vector", na_rm = FALSE)

Parallelize a function

Description

Parallelize a function

Usage

parallelize_fun(
  x,
  fun,
  cores = 1,
  export_fun = NULL,
  clean_result = FALSE,
  throw_error = TRUE,
  progress_bar_width = 10L,
  timestamp_format = paste0("[", format(Sys.time(), "%Y-%m-%d %H:%M:%S"), "] "),
  verbose = TRUE,
  backend = c("auto", "fork", "psock"),
  timeout = Inf,
  total_timeout = Inf,
  seed = NULL,
  progress = verbose
)

Arguments

Value

A list of computed results. If clean_result = FALSE, failed results are included as error objects. If clean_result = TRUE, only successful results are returned.

Examples

parallelize_fun(1:3, function(x) {
  Sys.sleep(0.2)
  x^2
})

parallelize_fun(list(1, 2, 3), function(x) {
  Sys.sleep(0.2)
  x^2
}, cores = 2)

# Examples with error handling
parallelize_fun(1:5, function(x) {
  if (x == 3) stop("Error on element 3")
  x^2
}, clean_result = FALSE)

parallelize_fun(1:5, function(x) {
  if (x == 3) stop("Error on element 3")
  x^2
}, clean_result = TRUE)

# Control error printing
parallelize_fun(1:5, function(x) {
  if (x == 2) stop("Error on element 3")
  if (x == 4) stop("Error on element 4")
  x^2
})

parallelize_fun(1:5, function(x) {
  if (x == 3) stop("Error on element 3")
  x^2
}, throw_error = FALSE)

Parse inline expressions

Description

Parse '' inline expressions and evaluate them in the current environment, while preserving outer formatting markers like '{.val ...}'.

Usage

parse_inline_expressions(text, env = parent.frame())

Arguments

Value

A character string with expressions evaluated but formatting preserved.

Examples

i <- 1
parse_inline_expressions(
  "{.val {i}}"
)

x <- 5
y <- 10
parse_inline_expressions(
  "{.pkg {x + y}}"
)

name <- "testing"
name <- parse_inline_expressions(
  "{.pkg {name}}"
)
name

log_message(name)

Correlation and covariance calculation for sparse matrix

Description

Correlation and covariance calculation for sparse matrix

Usage

pearson_correlation(x, y = NULL, max_dense_bytes = Inf)

Arguments

Details

This lower-level helper deliberately returns dense covariance and correlation matrices and therefore requires memory proportional to 'ncol(x) * ncol(y)'. Prefer [sparse_cor()] when a sparse, blockwise result is sufficient.

Value

A list with covariance and correlation matrices.

Examples

m1 <- simulate_sparse_matrix(
  100, 100
)
m2 <- simulate_sparse_matrix(
  100, 100,
  sparsity = 0.05
)
a <- pearson_correlation(m1, m2)
a$cov[1:5, 1:5]
a$cor[1:5, 1:5]

Print logo

Description

Print logo

Usage

## S3 method for class 'thisutils_logo'
print(x, ...)

Arguments

Value

Print the ASCII logo

Coefficient of determination (R^2)

Description

Coefficient of determination (R^2)

Usage

r_square(y_true, y_pred)

Arguments

Value

The R^2 value.

Examples

y <- rnorm(100)
y_pred <- y + rnorm(100, sd = 0.5)
r_square(y, y_pred)

Check and remove R packages

Description

Check and remove R packages

Usage

remove_r(packages, lib = .libPaths()[1], verbose = TRUE)

Arguments

Remove and normalize spaces

Description

Remove and normalize spaces

Usage

remove_space(
  x,
  trim_start = TRUE,
  trim_end = FALSE,
  collapse_multiple = TRUE,
  preserve_newlines = TRUE
)

Arguments

Value

A character vector with spaces normalized according to the specified parameters.

Examples

x <- c(
  " hello  world ",
  "  test   case  ",
  "no space",
  "   multiple   spaces   "
)
remove_space(x)
remove_space(x, trim_start = FALSE)
remove_space(x, trim_end = TRUE)
remove_space(x, collapse_multiple = FALSE)
remove_space(
  x,
  trim_start = FALSE,
  trim_end = FALSE,
  collapse_multiple = FALSE
)

# with newlines
multiline <- c(
  "hello\n\n  world  ",
  "  first  \n  second  "
)
remove_space(multiline)
remove_space(multiline, preserve_newlines = FALSE)

Find nearest neighbors with BiocNeighbors

Description

Find nearest neighbors within a reference matrix or from a query matrix to a reference matrix. The wrapper standardizes matrix coercion, distance metric, and self-neighbor removal across consumers.

Usage

run_biocneighbors_knn(
  reference,
  query = NULL,
  k,
  metric = c("euclidean", "cosine"),
  exclude_self = FALSE,
  n_threads = 1L
)

Arguments

Value

A list with integer matrix 'idx' and numeric matrix 'dist'.

Examples

if (nzchar(system.file(package = "BiocNeighbors"))) {
  run_biocneighbors_knn(matrix(rnorm(20), ncol = 2), k = 2)
}

Dense matrix top-k selection

Description

For each column or row of a dense numeric matrix, extract the top k elements and their indices. The default returns the largest values; set decreasing = FALSE to retain the smallest values, as in nearest-neighbor selection from a distance matrix.

Usage

run_dense_topk(x, k, by = c("col", "row"), decreasing = TRUE)

Arguments

Value

A list with two components:

idx

Integer matrix of 1-based indices into the opposite dimension.

value

Numeric matrix of corresponding values.

Both matrices have ncol(x) rows when by = "col" and nrow(x) rows when by = "row".

Examples

m <- matrix(rnorm(100), nrow = 10)
run_dense_topk(m, k = 3, by = "col")
run_dense_topk(m, k = 3, by = "row")
run_dense_topk(m, k = 3, by = "col", decreasing = FALSE)

Compatibility wrapper for stored column-wise sparse top-k selection

Description

run_sparse_stored_topk_by_column() preserves the stored-entry column-wise interface used in earlier releases. New code should call run_sparse_topk_stored() with by = "col".

Usage

run_sparse_stored_topk_by_column(x, k, decreasing = TRUE)

Arguments

Value

A list with idx and value matrices as described in run_sparse_topk_stored().

Sparse matrix top-k selection

Description

For each column or row of a sparse dgCMatrix, extract the top k matrix elements and their indices. By default, unstored positions participate with their matrix value of zero. For column-wise selection, this gives the same semantics as run_dense_topk().

Usage

run_sparse_topk(
  x,
  k,
  by = c("col", "row"),
  decreasing = TRUE,
  include_implicit_zeros = TRUE
)

Arguments

Value

A list with two components:

idx

Integer matrix of 1-based indices into the opposite dimension.

value

Numeric matrix of corresponding values.

Both matrices have ncol(x) rows when by = "col" and nrow(x) rows when by = "row".

Examples

m <- Matrix::rsparsematrix(10, 20, density = 0.3)
run_sparse_topk(m, k = 3, by = "col")
run_sparse_topk(m, k = 3, by = "row")

Compatibility wrapper for column-wise sparse top-k selection

Description

run_sparse_topk_by_column() preserves the column-wise interface used in earlier releases: only explicitly stored entries participate, and missing ranks are padded with NA indices and zero values. New code should call run_sparse_topk() or run_sparse_topk_stored() to select the intended sparse-zero semantics explicitly.

Usage

run_sparse_topk_by_column(x, k, decreasing = TRUE)

Arguments

Value

A list with idx and value matrices. Columns with fewer than k stored entries use NA indices and zero values for the remaining ranks.

Stored sparse entries top-k selection

Description

For each column or row of a sparse dgCMatrix, rank only explicitly stored entries. Unstored zeros never become candidates. This is useful for sparse adjacency matrices, where stored entries represent graph edges rather than samples from a full numeric matrix.

Usage

run_sparse_topk_stored(x, k, by = c("col", "row"), decreasing = TRUE)

Arguments

Value

A list with idx and value matrices as described in run_sparse_topk(). Groups with fewer than k stored entries are padded with NA in both matrices.

Examples

graph <- Matrix::sparseMatrix(
  i = c(1, 3, 2), j = c(1, 1, 2), x = c(1, 3, -2),
  dims = c(3, 2)
)
run_sparse_topk_stored(graph, k = 2, by = "col")

Generate a simulated sparse matrix

Description

This function generates a sparse matrix with a specified number of rows and columns, a given sparsity level, and a distribution function for the non-zero values.

Usage

simulate_sparse_matrix(
  nrow,
  ncol,
  sparsity = 0.95,
  distribution_fun = function(n) stats::rpois(n, lambda = 0.5) + 1,
  decimal = 0,
  seed = 1
)

Arguments

Value

A sparse matrix of class "dgCMatrix".

Examples

simulate_sparse_matrix(1000, 500) |>
  check_sparsity()

simulate_sparse_matrix(10, 10, decimal = 1)
simulate_sparse_matrix(10, 10, decimal = 5)

Resource-controlled sparse correlation

Description

Compute correlations from matrix-like input and return a sparse matrix. Pearson cross-products remain sparse and correlations are evaluated in column blocks so block-local working memory is bounded independently of the full output dimensions.

Usage

sparse_cor(
  x,
  y = NULL,
  method = c("pearson", "spearman", "kendall"),
  allow_neg = TRUE,
  remove_na = TRUE,
  remove_inf = TRUE,
  threshold = 0,
  block_size = 256L,
  max_dense_bytes = Inf,
  max_output_entries = Inf,
  ...
)

Arguments

Details

Pearson input and cross-products remain sparse. Centering, scaling, and thresholding are fused in a column-block scan rather than materializing a dense correlation block. The final sparse result can nevertheless contain up to ncol(x) * ncol(y) stored values when threshold = 0; use threshold and max_output_entries to make this boundary explicit.

Spearman and Kendall correlation require ranking and currently densify the input and full correlation result. Their estimated peak working size is checked against max_dense_bytes before conversion.

Value

A sparse correlation matrix.

Examples

m1 <- simulate_sparse_matrix(
  500, 100
)
m2 <- simulate_sparse_matrix(
  500, 100,
  seed = 2025
)
a <- sparse_cor(m1)
b <- sparse_cor(m1, m2)
c <- as_matrix(
  cor(as_matrix(m1)),
  return_sparse = TRUE
)
d <- as_matrix(
  cor(as_matrix(m1), as_matrix(m2)),
  return_sparse = TRUE
)

a[1:5, 1:5]
c[1:5, 1:5]
all.equal(a, c)

b[1:5, 1:5]
d[1:5, 1:5]
all.equal(b, d)

m1[sample(1:500, 10)] <- NA
m2[sample(1:500, 10)] <- NA

sparse_cor(m1, m2)[1:5, 1:5]

system.time(
  sparse_cor(m1)
)
system.time(
  cor(as_matrix(m1))
)

system.time(
  sparse_cor(m1, m2)
)
system.time(
  cor(as_matrix(m1), as_matrix(m2))
)

Split indices.

Description

An optimised version of split for the special case of splitting row indices into groups.

Usage

split_indices(group, n = 0L)

Arguments

Value

A list of vectors of indices.

References

https://github.com/hadley/plyr/blob/d57f9377eb5d56107ba3136775f2f0f005f33aa3/src/split-numeric.cpp#L20

Examples

split_indices(sample(10, 100, rep = TRUE))
split_indices(sample(10, 100, rep = TRUE), 10)

Sum P-value

Description

Sum P-value

Usage

sump(p)

Arguments

Examples

p <- c(0.01, 0.02, 0.03, 0.04, 0.05)
sump(p)

Switch table to matrix

Description

Switch table to matrix

Usage

table_to_matrix(
  table,
  row_names = NULL,
  col_names = NULL,
  threshold = 0,
  return_sparse = FALSE
)

Arguments

Value

A matrix.

See Also

matrix_to_table

Examples

table <- data.frame(
  row = c("r1", "r2", "r3", "r4", "r5", "r6"),
  col = c("c4", "c5", "c6", "c1", "c2", "c3"),
  value = c(0.6, -0.5, -0.4, 0.3, 0.2, 0.1)
)
matrix <- table_to_matrix(table)
table_new <- matrix_to_table(matrix)
identical(table, table_new)

table_to_matrix(table, threshold = 0.3)

table_to_matrix(
  table,
  row_names = c("r1", "r2"),
  col_names = c("c4", "c5")
)

sparse_matrix <- simulate_sparse_matrix(10, 10)
table_sparse <- matrix_to_table(
  sparse_matrix
)
sparse_matrix_new <- table_to_matrix(
  table_sparse,
  return_sparse = TRUE
)
identical(sparse_matrix, sparse_matrix_new)

The logo of thisutils

Description

The thisutils logo, using ASCII or Unicode characters Use cli::ansi_strip to get rid of the colors.

Usage

thisutils_logo(unicode = cli::is_utf8_output())

Arguments

Value

A character vector with class thisutils_logo.

References

https://github.com/tidyverse/tidyverse/blob/main/R/logo.R

Examples

thisutils_logo()

Try to evaluate an expression a set number of times before failing

Description

The function is used as a fail-safe if code sometimes works and sometimes doesn't, usually because it depends on a resource that may be temporarily unavailable. It tries to evaluate the expression max_tries times. If all the attempts fail, it throws an error; if not, the evaluated expression is returned.

Usage

try_get(expr, max_tries = 5, error_message = "", retry_message = "Retrying...")

Arguments

Value

The evaluated expression if successful, otherwise it throws an error if all attempts are unsuccessful.

Examples

f <- function() {
  value <- runif(1, min = 0, max = 1)
  if (value > 0.5) {
    log_message("value is larger than 0.5")
    return(value)
  } else {
    log_message(
      "value is smaller than 0.5",
      message_type = "error"
    )
  }
}
f_evaluated <- try_get(expr = f())
print(f_evaluated)

Unnest a list-column

Description

Implement similar functions to the tidyr::unnest function.

Usage

unnest_fun(data, cols, keep_empty = FALSE)

Arguments

Examples

data <- data.frame(
  id = 1:3,
  x = c("a", "b", "c"),
  stringsAsFactors = FALSE
)
data$data <- list(
  c(1, 2),
  c(3, 4, 5),
  c(6)
)
unnest_fun(data, cols = "data")

data2 <- data.frame(
  id = 1:3,
  x = c("a", "b", "c"),
  stringsAsFactors = FALSE
)
data2$data <- list(
  c(1, 2),
  numeric(0),
  c(6)
)
unnest_fun(data2, cols = "data")
unnest_fun(data2, cols = "data", keep_empty = TRUE)

Vote P-value

Description

Vote P-value

Usage

votep(p, alpha = 0.5)

Arguments

Examples

p <- c(0.01, 0.02, 0.03, 0.04, 0.05)
votep(p)
votep(p, alpha = 0.01)

Wilkinson's P-value

Description

Wilkinson's P-value

Usage

wilkinsonp(p, r = 1, alpha = 0.05, log.p = FALSE)

Arguments

Examples

p <- c(0.01, 0.02, 0.03, 0.04, 0.05)
wilkinsonp(p)
wilkinsonp(p, r = 2)
wilkinsonp(p, alpha = 0.01)
wilkinsonp(p, log.p = TRUE)