Package 'thisutils'

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), [email protected]

Source

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

See Also

Useful links:

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

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

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

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⁠.

Description

Aggregate matrix over groups

Usage

aggregate_matrix(x, groups = NULL, fun = "mean")

Arguments

Value

A sparse summary matrix with groups in rows.

Examples

aggregate_matrix(
  matrix(1:6, nrow = 3),
  groups = c("a", "a", "b"),
  fun = "mean"
)

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]

Description

Capitalize the first letter of each word

Usage

capitalize(x, force_tolower = FALSE)

Arguments

Examples

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

Description

Check CI environment

Usage

check_ci_env()

Value

A logical value.

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.

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.

Description

Check sparsity of matrix

Usage

check_sparsity(x)

Arguments

Value

Sparsity of matrix.

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)

Description

Column maxima

Usage

col_maxs(x, na.rm = TRUE)

Arguments

Value

A numeric vector of column maxima. Implicit sparse zeros are treated as zero.

Examples

col_maxs(matrix(c(-2, 0, 3, 1), nrow = 2))

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"))

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)

Description

Detect the number of CPU cores

Usage

detect_cores(
  cores = NULL,
  num_session = NULL,
  max_threads = NULL,
  logical = FALSE
)

Arguments

Value

A single integer, at least 1. A failed or unusable probe falls back to 1 instead of propagating NA.

Examples

detect_cores()
detect_cores(max_threads = 2)
detect_cores(cores = 4, num_session = 8)

Description

Download file from the Internet

Usage

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

Arguments

Description

Fast sparse aggregation

Usage

fast_aggregate(x, groupings = NULL, form = NULL, fun = "sum", ...)

Arguments

Value

A sparse matrix with groups in rows.

Examples

fast_aggregate(
  matrix(1:6, nrow = 3),
  groupings = c("a", "a", "b"),
  fun = "sum"
)

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))

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")

Description

Get a figlet font

Usage

figlet_font(font)

Arguments

Value

A 'figlet_font' object for use with [figlet]

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
)

Description

Fit feature trends

Usage

fit_trends(
  x,
  time,
  method = c("gam", "pretsa"),
  family = "gaussian",
  exposure = rep(1, ncol(x)),
  use_exposure = FALSE,
  reference_exposure = NULL,
  knot = 0,
  max_knot_allowed = 10,
  padjust_method = "fdr",
  return_fitted = TRUE,
  cores = 1,
  verbose = TRUE
)

Arguments

Details

Inputs are not transformed. PreTSA requires finite values; GAM omits unusable observations. Peak/valley times summarize the upper/lower 1% of fitted values, including ties for PreTSA.

Value

A list with statistics, time, and optional fitted, lower, and upper matrices, in input order. Statistics contain feature names, counts above each feature's minimum, fit scores, peak/valley times, P-values and adjusted P-values. Failed GAM fits return NA. GAM bounds use +/- 2 standard errors on the link scale; PreTSA bounds equal fitted values, not confidence intervals.

References

Zhuang and Ji, PreTSA, https://github.com/haotian-zhuang/PreTSA

Examples

t <- seq(0, 1, length.out = 40)
x <- rbind(a = sin(t * 5), b = cos(t * 3))
fit_trends(x, t, method = "pretsa")$statistics

Description

Get a function from a namespace

Usage

get_namespace_fun(pkg, fun)

Arguments

Value

Function.

Description

Resolve options(log_message.verbose). An explicit verbose argument wins. Otherwise the option is used, and the default is TRUE.

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)

Description

Return the left side unless it is NULL or has length zero, otherwise return the right side. Use ⁠%ss%⁠ when only NULL should fall through; that matches the rlang ⁠%||%⁠ operator without masking it.

Usage

a %|||% b

Arguments

Value

a if it is not NULL and has length greater than zero, otherwise b.

Examples

NULL %|||% 10
character(0) %|||% "fallback"
5 %|||% 10

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)

Description

Check if the system is running on Apple Silicon

Usage

is_apple_silicon()

Value

A logical value.

Description

Check if the operating system is Linux

Usage

is_linux()

Value

A logical value.

Description

Check if the operating system is macOS

Usage

is_osx()

Value

A logical value.

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

Description

Check if the operating system is Windows

Usage

is_windows()

Value

A logical value.

Description

Set options(log_message.verbose) for the calling frame, then restore the previous value. Nested get_verbose() calls, including compiled log_message() code, see the temporary value.

Usage

local_verbose(verbose)

Arguments

Value

verbose, invisibly.

Examples

local({
  local_verbose(FALSE)
  get_verbose()
})

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 [email protected]}")

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"
)

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))

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")
)

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)

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)

Description

Mean P-value

Usage

meanp(p)

Arguments

Examples

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

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)

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)

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)

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)

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]

Description

Print logo

Usage

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

Arguments

Value

Print the ASCII logo

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)

Description

Check and remove R packages

Usage

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

Arguments

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)

Description

Row maxima

Usage

row_maxs(x, na.rm = TRUE)

Arguments

Value

A numeric vector of row maxima. Implicit sparse zeros are treated as zero.

Examples

row_maxs(matrix(c(-2, 0, 3, 1), nrow = 2))

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)
}

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)

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().

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")

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.

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")

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)

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))
)

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)

Description

Sum P-value

Usage

sump(p)

Arguments

Examples

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

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)

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()

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)

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)

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)

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)