| Title: | Supporting Functions for Packages Maintained by 'YuLab-SMU' |
| Version: | 0.2.2 |
| Description: | Miscellaneous functions commonly used by 'YuLab-SMU'. |
| Depends: | R (≥ 4.2.0) |
| Imports: | cli, digest, fs, rappdirs, rlang, tools, utils |
| Suggests: | httr2, jsonlite, openssl |
| 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 |
| NeedsCompilation: | no |
| Packaged: | 2025-12-01 02:40:24 UTC; HUAWEI |
| Author: | Guangchuang Yu 
[aut, cre] |
| Maintainer: | Guangchuang Yu <guangchuangyu@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2025-12-01 06: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:
print md text of package with link to homepage (CRAN or Bioconductor)
Description
print md text of package with link to homepage (CRAN or Bioconductor)
Usage
CRANpkg(pkg)
Biocpkg(pkg)
Arguments
pkg |
package name |
Value
md text string
Author(s)
Guangchuang Yu
print md text of package with link to github repo
Description
print md text of package with link to github repo
Usage
Githubpkg(user, pkg)
Arguments
user |
github user |
pkg |
package name |
Value
md text string
Author(s)
Guangchuang Yu
c2
Description
chunked array
Usage
c2(x, y)
Arguments
x |
a vector or chunked_array object |
y |
a vector or chunked_array object |
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
path |
Directory path |
create_if_missing |
Whether to create directory if it doesn't exist |
check_write_permission |
Whether to verify write permissions |
arg_name |
Name of the argument for error messages |
Value
Invisible TRUE if valid, throws error otherwise
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
path |
File path |
operation |
Operation being performed (read, write, etc.) |
must_exist |
Whether the file must exist |
Value
Invisible TRUE if operation can proceed, throws error otherwise
Check input validity with detailed error messages
Description
Enhanced input validation with support for basic types and improved error messages
Usage
check_input(
x,
type = NULL,
length = NULL,
min_length = NULL,
max_length = NULL,
allow_null = FALSE,
arg_name = "input"
)
Arguments
x |
Object to check |
type |
Expected type (can be basic type like "numeric", "character" or class name) |
length |
Expected length (optional) |
min_length |
Minimum length (optional) |
max_length |
Maximum length (optional) |
allow_null |
Whether NULL is allowed |
arg_name |
Name of the argument for error messages |
Value
Invisible TRUE if valid, throws error otherwise
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")
Arguments
packages |
Character vector of package names |
reason |
Reason why these packages are needed |
Value
Invisible TRUE if all packages are available, throws error otherwise
check_pkg
Description
Check whether the input packages are installed
Usage
check_pkg(pkg, reason = NULL, ...)
Arguments
pkg |
package names |
reason |
the reason to check the pkg. If NULL, it will set the reason to the parent call. |
... |
additional parameters that passed to |
Details
This function check whether the input packages are installed. If not, it asks the user whether to install the missing packages.
Value
see also check_installed
Author(s)
Guangchuang Yu
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
x |
Numeric value to check |
min |
Minimum allowed value (optional) |
max |
Maximum allowed value (optional) |
inclusive |
Whether bounds are inclusive (default: TRUE) |
arg_name |
Name of the argument for error messages |
Value
Invisible TRUE if valid, throws error otherwise
combinations
Description
all possible combinations of n sets
Usage
combinations(n)
Arguments
n |
number of sets |
Value
a list of all combinations
exec
Description
run system command
Usage
exec(command)
Arguments
command |
system command to run |
Value
An exec instance that stores system command outputs
Author(s)
Guangchuang Yu
get_dependencies
Description
get reverse dependencies
Usage
get_dependencies(pkg, repo = c("CRAN", "BioC"))
Arguments
pkg |
package name |
repo |
'CRAN' and/or 'BioC' |
Value
reverse dependencies
Author(s)
Guangchuang Yu
get_fun_from_pkg
Description
load function from package
Usage
get_fun_from_pkg(pkg, fun)
Arguments
pkg |
package |
fun |
function |
Value
function
Author(s)
Guangchuang Yu
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
site |
URL to test connection |
Value
logical value
Author(s)
Guangchuang Yu
cache intermediate data
Description
Yulab provides a set of utilities to cache intermediate data, including initialize the cached item, update cached item and rmove the cached item, etc.
Usage
initial_cache()
get_cache()
rm_cache()
initial_cache_item(item)
get_cache_item(item)
rm_cache_item(item)
update_cache_item(item, elements)
get_cache_element(item, elements)
Arguments
item |
the name of the cached item |
elements |
elements to be cached in the item |
Value
return the cache environment, item or selected elements, depends on the functions.
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
file |
zip file |
subdir |
sub directory that contains R package files, default is NULL |
args |
argument to build package |
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
repo |
github repo |
ref |
github branch, default is HEAD, which means the default branch of the GitHub repo |
subdir |
sub directory that contains R package files, default is NULL |
args |
argument to build package |
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 the input packages are installed
Usage
is.installed(packages)
Arguments
packages |
package names |
Details
This function check whether the input packages are installed
Value
logical vector
Author(s)
Guangchuang Yu
Examples
is.installed(c("dplyr", "ggplot2"))
Convert a list of vector (e.g, gene IDs) to a data.frame object
Description
Convert a list of vector to a data.frame object.
Usage
ls2df(inputList)
Arguments
inputList |
A list of vector |
Value
a data.frame object.
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
x |
the input matrix |
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
x |
the input matrix |
Value
a list that contains matrix columns as its elements
Examples
x <- matrix(1:15, nrow = 3)
mat2list(x)
mypkg
Description
print md text of link to a pakcage
Usage
mypkg(pkg, url)
Arguments
pkg |
package name |
url |
package url |
Value
md text string
Author(s)
Guangchuang Yu
o
Description
open selected directory or file
Usage
o(file = ".")
Arguments
file |
to be open; open working directory by default |
Value
No return value, called for opening specific directory or file
Author(s)
Guangchuang Yu
Examples
## Not run:
## to open current working directory
o()
## End(Not run)
packageTitle
Description
Extract package title
Usage
packageTitle(pkg, repo = "CRAN")
Arguments
pkg |
package name |
repo |
'CRAN' and/or 'BioC' |
Value
reverse dependencies
Author(s)
Guangchuang Yu
pload
Description
loading a package
Usage
pload(package, action = "auto")
Arguments
package |
package name |
action |
function used to install package. If 'action = "auto"', it will try to use 'BiocManager::install()' if it is available. |
Details
The function use 'library()' to load the package. If the package is not installed, the function will try to install it before loading it.
Value
the selected package loaded to the R session
Author(s)
Guangchuang Yu
quiet
Description
Suppress messages and output from x
Usage
quiet(x)
Arguments
x |
some code |
Value
the result of x
rbindlist
Description
rbind a list
Usage
rbindlist(x)
Arguments
x |
a list that have similar elements that can be rbind to a data.frame |
Value
data.frame
Author(s)
Guangchuang Yu
read.cb
Description
read clipboard
Usage
read.cb(reader = read.table, ...)
Arguments
reader |
function to read the clipboard |
... |
parameters for the reader |
Value
clipboard content, output type depends on the output of the reader
Author(s)
Guangchuang Yu
scale-range
Description
normalized data by range
Usage
scale_range(data)
Arguments
data |
the input data. |
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
doi |
doi |
scihub |
scihub website |
download |
whether download the pdf file |
Value
pdf url
Author(s)
Guangchuang Yu
switch regular expression style (PCRE vs TRE)
Description
The set_regexpr_style() allows user to specify which style to be used,
while the auto_set_regexpr_style() automatically set the style depdending on
the operating system (TRE for Windows and PCRE for other OSs (Linux and Mac)).
Usage
set_PCRE()
set_TRE()
use_perl()
set_regexpr_style(style)
auto_set_regexpr_style()
Arguments
style |
one of 'PCRE' or 'TRE' |
Details
set_PCRE() force to use PCRE style while set_TRE() force to use TRE.
Note that all these functions are not change the behavior of gsub() and regexpr().
The functions are just set a global option to store the user's choice of whether using perl = TRUE.
Users can access the option via use_perl() and pass the return value to gusb() or regexpr() to specify the style in use.
Value
logical value of whether use perl
Author(s)
Guangchuang Yu
References
show_in_excel
Description
Open data frame in Excel. It can be used in pipe.
Usage
show_in_excel(.data)
Arguments
.data |
a data frame to be open |
Value
original .data
Author(s)
Guangchuang Yu
str_detect
Description
Detect the presentce/absence of a match
Usage
str_detect(string, pattern, negate = FALSE)
Arguments
string |
input string |
pattern |
pattern to look for |
negate |
if TRUE, inverts the resulting boolen vector |
Value
logical vector
Author(s)
Guangchuang Yu
str_extract
Description
Extract a substring using a pattern
Usage
str_extract(string, pattern)
Arguments
string |
input string |
pattern |
a regular expression to describe the pattern to extracted from the 'string' |
Value
substring
Author(s)
Guangchuang Yu
str_starts
Description
Detect the presence or absence of a pattern at the beginning or end of a string or string vector.
Usage
str_starts(string, pattern, negate = FALSE)
str_ends(string, pattern, negate = FALSE)
Arguments
string |
input string |
pattern |
pattern with which the string starts or ends |
negate |
if TRUE, return non-matching elements |
Value
a logical vector
Author(s)
Guangchuang Yu
str_wrap
Description
wraping long string to multiple lines
Usage
str_wrap(string, width = getOption("width"))
Arguments
string |
input string |
width |
the maximum number of characters before wrapping to a new line |
Value
update strings with new line character inserted
Author(s)
Guangchuang Yu
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
appname |
App name |
appauthor |
App author |
... |
additional parameters |
Value
a directory (created if not exists)
Author(s)
Guangchuang Yu
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
file |
a file or url |
reader |
a function to read the 'file_url' |
params |
a list of parameters that passed to the 'reader' |
cache_dir |
a folder to store cache files. If set to NULL will disable cache. |
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
Standardized error handling function
Description
Standardized error handling function
Usage
yulab_abort(message, class = "yulab_error", ...)
Arguments
message |
Error message to display |
class |
Custom error class for categorization |
... |
Additional context information |
Value
No return value, throws error
Standardized info function
Description
Standardized info function
Usage
yulab_inform(message, class = "yulab_info", ...)
Arguments
message |
Information message to display |
class |
Custom info class for categorization |
... |
Additional context information |
Value
No return value, displays information
yulab_msg
Description
Messages for R package developed by YuLab
Usage
yulab_msg(pkgname = NULL, n = 1)
Arguments
pkgname |
package name |
n |
number of citation messages |
Value
package message
Author(s)
Guangchuang Yu
Standardized warning function
Description
Standardized warning function
Usage
yulab_warn(message, class = "yulab_warning", ...)
Arguments
message |
Warning message to display |
class |
Custom warning class for categorization |
... |
Additional context information |
Value
No return value, issues warning