Title:	Supporting Functions for Packages Maintained by 'YuLab-SMU'
Version:	0.2.3
Description:	Miscellaneous functions commonly used by 'YuLab-SMU'.
Depends:	R (≥ 4.2.0)
Imports:	cli, digest, fs, methods, rappdirs, rlang, tools, utils
Suggests:	httr2, jsonlite, openssl, R.utils, testthat (≥ 3.0.0)
ByteCompile:	true
License:	Artistic-2.0
URL:	https://yulab-smu.top/
BugReports:	https://github.com/YuLab-SMU/yulab.utils/issues
Encoding:	UTF-8
RoxygenNote:	7.3.3
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2025-12-15 06:46:29 UTC; HUAWEI
Author:	Guangchuang Yu [aut, cre]
Maintainer:	Guangchuang Yu <guangchuangyu@gmail.com>
Repository:	CRAN
Date/Publication:	2025-12-15 07:10:02 UTC

yulab.utils: Supporting Functions for Packages Maintained by 'YuLab-SMU'

Description

Miscellaneous functions commonly used by 'YuLab-SMU'.

Author(s)

Maintainer: Guangchuang Yu guangchuangyu@gmail.com (ORCID)

See Also

Useful links:

• https://yulab-smu.top/

• Report bugs at https://github.com/YuLab-SMU/yulab.utils/issues

Markdown link to CRAN/Bioconductor

Description

Markdown link to CRAN/Bioconductor

Usage

CRANpkg(pkg)

Biocpkg(pkg)

Arguments

Value

md text string

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: Githubpkg(), get_dependencies(), get_fun_from_pkg(), is.installed(), mypkg(), packageTitle(), pload()

Markdown link to GitHub

Description

Markdown link to GitHub

Usage

Githubpkg(user, pkg)

Arguments

Value

md text string

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), get_dependencies(), get_fun_from_pkg(), is.installed(), mypkg(), packageTitle(), pload()

c2

Description

chunked array

Usage

c2(x, y)

Arguments

Details

concate two vector/chunked_array into a chunked_array object

Value

chunked_array object

Author(s)

Guangchuang Yu

Check if directory exists and is accessible

Description

Validates directory existence and accessibility with options to create if missing

Usage

check_directory(
  path,
  create_if_missing = FALSE,
  check_write_permission = TRUE,
  arg_name = "directory"
)

Arguments

Value

Invisible TRUE if valid, throws error otherwise

See Also

Other validate-utils: check_file(), check_input(), check_packages(), check_range()

Handle file operations with proper error messages

Description

Enhanced file validation with comprehensive checks and better error messages

Usage

check_file(path, operation = "read", must_exist = TRUE)

Arguments

Value

Invisible TRUE if operation can proceed, throws error otherwise

See Also

Other validate-utils: check_directory(), check_input(), check_packages(), check_range()

Validate input with type/length constraints

Description

Enhanced input validation supporting base types and class checks.

Usage

check_input(
  x,
  type = NULL,
  length = NULL,
  min_length = NULL,
  max_length = NULL,
  allow_null = FALSE,
  arg_name = "input"
)

Arguments

Value

Invisible TRUE on success

See Also

Other validate-utils: check_directory(), check_file(), check_packages(), check_range()

Check if required packages are installed with informative errors

Description

Enhanced package checking with better error messages and validation

Usage

check_packages(packages, reason = "for this functionality")

check_pkg(packages, reason = "for this functionality")

Arguments

Value

Invisible TRUE if all packages are available, throws error otherwise

See Also

Other validate-utils: check_directory(), check_file(), check_input(), check_range()

Check if value is within specified range

Description

Validates that a numeric value falls within the specified range

Usage

check_range(x, min = NULL, max = NULL, inclusive = TRUE, arg_name = "value")

Arguments

Value

Invisible TRUE if valid, throws error otherwise

See Also

Other validate-utils: check_directory(), check_file(), check_input(), check_packages()

combinations

Description

all possible combinations of n sets

Usage

combinations(n)

Arguments

Value

a list of all combinations

Process YuLab File Download

Description

Process YuLab File Download

Usage

download_yulab_file(destfile, urls, gzfile = FALSE, appname = NULL)

Arguments

Author(s)

Guangchuang Yu

exec

Description

run system command

Usage

exec(command)

Arguments

Value

An exec instance that stores system command outputs

Author(s)

Guangchuang Yu

See Also

Other os-utils: has_internet(), user_dir()

get_dependencies

Description

Get reverse dependencies

Usage

get_dependencies(pkg, repo = c("CRAN", "BioC"))

Arguments

Value

reverse dependencies

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), Githubpkg(), get_fun_from_pkg(), is.installed(), mypkg(), packageTitle(), pload()

get_fun_from_pkg

Description

load function from package

Usage

get_fun_from_pkg(pkg, fun)

Arguments

Value

function

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), Githubpkg(), get_dependencies(), is.installed(), mypkg(), packageTitle(), pload()

Examples

get_fun_from_pkg('utils', 'zip')

has_internet

Description

test for internect connection via reading lines from a URL

Usage

has_internet(site = "https://www.baidu.com/")

Arguments

Value

logical value

Author(s)

Guangchuang Yu

See Also

Other os-utils: exec(), user_dir()

Cache intermediate data

Description

Utilities to cache intermediate data: initialize items, update items, remove items, and retrieve elements.

Usage

initial_cache()

get_cache()

rm_cache()

initial_cache_item(item)

get_cache_item(item)

rm_cache_item(item)

update_cache_item(item, elements, ttl = NULL)

get_cache_element(item, elements, default = NULL, prune_expired = TRUE)

prune_cache_item(item)

cache_list_items()

cache_size()

cache_save(path)

cache_load(path)

with_cache(item, key, compute, ttl = NULL)

Arguments

Value

Cache environment, item, or selected elements

Examples

## Not run: 
 slow_fib <- function(x) {
     if (x < 2) return(1)
     slow_fib(x-2) + slow_fib(x-1)
 }
 
 fast_fib <- function(x) {
     if (x < 2) return(1)
     res <- get_cache_element('fibonacci', as.character(x))
     if (!is.null(res)) {
         return(res)
     }
     res <- fast_fib(x-2) + fast_fib(x-1)
     e <- list()
     e[[as.character(x)]] <- res
     update_cache_item('fibonacci', e)
     return(res)
 }

 system.time(slow_fib(30))
 system.time(fast_fib(30)) 
    
 
## End(Not run)

install_zip

Description

install R package from zip file of source codes

Usage

install_zip(file, subdir = NULL, args = "--no-build-vignettes")

Arguments

Value

No return value, called for install R package from zip file of source codes

Author(s)

Guangchuang Yu

install_zip_gh

Description

install github package

Usage

install_zip_gh(
  repo,
  ref = "HEAD",
  subdir = NULL,
  args = "--no-build-vignettes"
)

Arguments

Details

it download the zip file first and use install_zip to install it

Value

No return value, called for installing github package

Author(s)

Guangchuang Yu

is.installed

Description

Check whether packages are installed

Usage

is.installed(packages)

Arguments

Value

logical vector

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), Githubpkg(), get_dependencies(), get_fun_from_pkg(), mypkg(), packageTitle(), pload()

Examples

is.installed(c("dplyr", "ggplot2"))

load_OrgDb

Description

load OrgDb

Usage

load_OrgDb(OrgDb)

Arguments

Value

OrgDb object

Author(s)

Guangchuang Yu https://yulab-smu.top

Convert a list of vectors (e.g., gene IDs) to data.frame

Description

Convert a list of vectors to a data.frame

Usage

ls2df(inputList)

Arguments

Value

data.frame

mat2df

Description

convert a matrix to a tidy data frame (from wide to long format as described in the tidyverse concept)

Usage

mat2df(x)

Arguments

Value

a data.frame in long format with the 'value' column stores the original values and 'row' and 'col' columns stored in row and column index as in x

Author(s)

Guangchuang Yu

Examples

x <- matrix(1:15, nrow = 3)
mat2df(x)

mat2list

Description

convert a matrix to a list

Usage

mat2list(x)

Arguments

Value

a list that contains matrix columns as its elements

Examples

x <- matrix(1:15, nrow = 3)
mat2list(x)

mypkg

Description

Markdown link to a package

Usage

mypkg(pkg, url)

Arguments

Value

md text string

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), Githubpkg(), get_dependencies(), get_fun_from_pkg(), is.installed(), packageTitle(), pload()

o

Description

open selected directory or file

Usage

o(file = ".")

Arguments

Value

No return value, called for opening specific directory or file

Author(s)

Guangchuang Yu

See Also

Other io-utils: read.cb(), show_in_excel(), yread_tsv()

Examples

## Not run: 
## to open current working directory
o()

## End(Not run)

packageTitle

Description

Extract package title

Usage

packageTitle(pkg, repo = "CRAN")

Arguments

Value

reverse dependencies

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), Githubpkg(), get_dependencies(), get_fun_from_pkg(), is.installed(), mypkg(), pload()

parse_ratio

Description

Parse character ratio to double, e.g., 1/5 → 0.2

Usage

parse_ratio(ratio)

Arguments

Value

Numeric vector

Author(s)

Guangchuang Yu

pload

Description

Load a package

Usage

pload(package, action = "auto")

Arguments

Details

Uses library() to load package. If not installed, attempts installation via rlang::check_installed() (optionally using BiocManager::install()).

Value

the selected package loaded to the R session

Author(s)

Guangchuang Yu

See Also

Other pkg-utils: CRANpkg(), Githubpkg(), get_dependencies(), get_fun_from_pkg(), is.installed(), mypkg(), packageTitle()

quiet

Description

Suppress messages and output from x

Usage

quiet(x)

Arguments

Value

the result of x

rbindlist

Description

Row-bind a list

Usage

rbindlist(x)

Arguments

Value

data.frame

Author(s)

Guangchuang Yu

read.cb

Description

read clipboard

Usage

read.cb(reader = read.table, ...)

Arguments

Value

clipboard content, output type depends on the output of the reader

Author(s)

Guangchuang Yu

See Also

Other io-utils: o(), show_in_excel(), yread_tsv()

scale-range

Description

normalized data by range

Usage

scale_range(data)

Arguments

Value

normalized data

Author(s)

Guangchuang Yu

download publication via scihub

Description

using scihub to download publication using doi

Usage

scihub_dl(doi, scihub = "sci-hub.tw", download = TRUE)

Arguments

Value

pdf url

Author(s)

Guangchuang Yu

Switch regular expression style (PCRE vs TRE)

Description

• set_regexpr_style() selects the style explicitly.

• auto_set_regexpr_style() chooses based on OS (TRE on Windows; PCRE elsewhere).

• set_PCRE() and set_TRE() force the style.

Usage

set_PCRE()

set_TRE()

use_perl()

set_regexpr_style(style)

auto_set_regexpr_style()

Arguments

Details

These functions do not change the behavior of gsub()/regexpr() directly. They set a global option that you can read via use_perl() and pass to gsub()/regexpr().

Value

Logical indicating whether to use perl

Author(s)

Guangchuang Yu

References

https://stackoverflow.com/questions/47240375/regular-expressions-in-base-r-perl-true-vs-the-default-pcre-vs-tre

show_in_excel

Description

Open data frame in Excel. It can be used in pipe.

Usage

show_in_excel(.data)

Arguments

Value

original .data

Author(s)

Guangchuang Yu

See Also

Other io-utils: o(), read.cb(), yread_tsv()

str_detect

Description

Detect presence/absence of a match

Usage

str_detect(string, pattern, negate = FALSE)

Arguments

Value

Logical vector

Author(s)

Guangchuang Yu

See Also

Other str-utils: str_extract(), str_starts(), str_wrap()

str_extract

Description

Extract a substring using a pattern

Usage

str_extract(string, pattern)

Arguments

Value

Substring

Author(s)

Guangchuang Yu

See Also

Other str-utils: str_detect(), str_starts(), str_wrap()

str_starts

Description

Detect patterns at the beginning or end of strings

Usage

str_starts(string, pattern, negate = FALSE)

str_ends(string, pattern, negate = FALSE)

Arguments

Value

a logical vector

Author(s)

Guangchuang Yu

See Also

Other str-utils: str_detect(), str_extract(), str_wrap()

str_wrap

Description

Wrap long strings to multiple lines

Usage

str_wrap(string, width = getOption("width"))

Arguments

Value

Updated strings with "\n" inserted

Author(s)

Guangchuang Yu

See Also

Other str-utils: str_detect(), str_extract(), str_starts()

user_dir

Description

get the user dir to save app caches, logs and data (a wrapper function of rappdirs::user_cache_dir())

Usage

user_dir(appname = NULL, appauthor = NULL, ...)

Arguments

Value

a directory (created if not exists)

Author(s)

Guangchuang Yu

See Also

Other os-utils: exec(), has_internet()

yread

Description

read file with caching

Usage

yread_tsv(
  file,
  reader = utils::read.delim,
  params = list(),
  cache_dir = tempdir()
)

yread(file, reader = readLines, params = list(), cache_dir = NULL)

Arguments

Details

This function read a file (local or url) and cache the content.

Value

the output of using the 'reader' to read the 'file_url' with parameters specified by the 'params'

Author(s)

Yonghe Xia and Guangchuang Yu

See Also

Other io-utils: o(), read.cb(), show_in_excel()

Other io-utils: o(), read.cb(), show_in_excel()

Standardized error handling

Description

Provides rlang-based wrappers for messaging: yulab_abort(), yulab_warn(), and yulab_inform().

Usage

yulab_abort(message, class = "yulab_error", ...)

yulab_warn(message, class = "yulab_warning", ...)

yulab_inform(message, class = "yulab_info", ...)

Arguments

Value

No return value

yulab_msg

Description

Messages for YuLab packages

Usage

yulab_msg(pkgname = NULL, n = 1)

Arguments

Value

Package message

Author(s)

Guangchuang Yu