mvbutils.utils: Miscellaneous utilities

In mvbutils: General utilities, workspace organization, code and doc editing, live package maintenance, etc

Miscellaneous utilities

Description

Miscellaneous utilities.

Usage

add_list_defaults( l, ...)
as.cat( x)
atts( x, exclude=cq( levels, class, dim, dimnames, names, row.names, tsp))
clamp( x, min, max)
clip( x, n=1)
compacto( x, gap, width, extra)
cq( ...)
deparse.names.parsably( x)
disatt( x, keep_=cq( levels, dim, dimnames, names, row.names, tsp), keep)
eclone( env)
empty.data.frame( ...)
env.name.string( env)
expanded.call( nlocal=sys.parent())
everyth( x, by=1, from=1)
find.funs(pos=1, ..., exclude.mcache = TRUE, mode="function")
find.scriptlets(pos=1, ..., exclude.mcache = TRUE, pattern='[.][rR]$')
find.lurking.envs(obj, delve=FALSE, trace=FALSE)
index( lvector)
integ(expr, lo, hi, what = "x", ..., args.to.integrate = list())
inv.logit( qq)
is.dir( dir)
isF( x)
isT( x)
legal.filename( name)
logit( x)
lsall( ...)
masked( pos)
masking( pos=1)
mkdir( dirlist)
most.recent( lvec)
mwhere( x, cond)
my.all.equal( x, y, ...)
named( x)
nscat( fmt, ..., sep='\n', file='')
nscatn( fmt, ..., sep='\n', file='')
option.or.default( opt.name, default=NULL)
pos( substrs, mainstrs, any.case = FALSE, names.for.output)
put.in.session( ...)
rename.els( ..., ignore.missing=FALSE)
returnList( ...)
rsample( n=length(pop), pop, replace=FALSE, prob=NULL)
safe.rbind( df1, df2) # Deprecated in 2013
scatn( fmt, ..., sep='\n', file='', append=FALSE)
sourceable( f, fname=deparse1( substitute( f)))
sqr( x)
to.regexpr( x)
undent( s)
xfactor( x, exclude=if( is.factor( x) && any( is.na( levels( x)))) NULL else NA)
xgsub( x, pattern, replacement, perl=!fixed, fixed=FALSE, ...)
xsub( x, pattern, replacement, perl=!fixed, fixed=FALSE, ...)
yes.no( prompt, default)

Arguments

l, x, y, n, gap, width, extra, ..., by, keep, keep_, env, from, exclude, exclude.mcache, nlocal, lvector, dir, name, pos, frame, mode, dirlist, lvec, cond, opt.name, default, substrs, mainstrs, any.case, names.for.output, ignore.missing, pop, replace, prob, df1, df2, prompt, obj, delve, trace, fmt, sep, append, file, expr, lo, hi, what, args.to.integrate, qq, s, min, max, pattern, replacement, perl, fixed, f, fname

see "Arguments by function"

Details

add_list_defaults appends its ... argument(s) to its l argument, excluding those where l already has an element with that name. l should be a list.

as.cat makes a character vector print as if it was catted rather than printed (one element per line, no extra quotes or backslashes, no [1] etc prefixes).

atts returns the names of the attributes of x, excluding any that are in exclude.

clamp clamps its 1st argument to the limits specified by the 2nd and 3rd. You can also just supply a range of values in the 2nd arg, and leave the 3rd missing. It's meant for use with pipes; see Examples.

clip removes the last n elements of x. OBSOLETE— use head( x, -n) instead.

compacto gives a matrix an extra S3 class "compacto", which means it will print out with column names/label vertical and optionally no gaps between the columns. gap and width control the latter in fairly obvious ways. extra controls what gets printed to help the eye follow vertical alignment. See Examples; there is a method print.compacto which surely needs little further description.

cq is handy for typing cq( alpha, beta, gamma) instead of cq( "alpha", "beta", "gamma"). Certain strings DO still require quotes around them, e.g. cq( "NULL", "1-2")).

deparse.names.parsably is like deparse except that name objects get wrapped in a call to as.name, so that they won't be evaluated accidentally.

disatt gets rid of most attributes on x. If you want to preserve some, use keep. The usually-default argument keep_, which is merged with keep, ensures that the "basic" attributes are retained; if you want to drop some of those too, you will have to modify keep_. Note that S3 class is dropped by default, because some S3 objects may not make sense without certain attributes.

eclone clones an environment into a new one with the same parent, ie making deep copies of all the (non-environment) members, so that changing their values in the new env won't affect the original values (unlike if you just assign the old env to the new one). Functions whose environment was the original environment, will have their environment reset to the new one. If you don't understand that, then either don't worry be happy, or do more homework on R's environment objects. See also Examples.

empty.data.frame creates a template data frame with 0 rows but with all columns of the appropriate type. Useful for rbinding to later.

env.name.string returns a string naming an environment; its name attribute if there is one, or the name of its path attribute if applicable, concatenated with the first line of what would be shown if you printed the argument. Unlike environmentName, this will always return a non-empty string.

expanded.call returns the full argument list available to its caller, including defaults where arguments were not set explicitly. The arguments may not be those originally passed, if they were modified before the invocation of expanded.call. Default arguments which depend on calculations after the invocation of expanded.call will lead to an error.

everyth extracts every by-th element of x, starting at position from.

find.funs finds "function" objects (or objects of other modes, via the "mode" arg) in one or more environments, optionally matching a pattern.

find.scriptlets is like find.funs but looks for character vectors whose name suggests that they are a "scriptlet" (ie text runnable with eval(parse(text=<scriptlet>))), as per fixr and suitable for mrun or mdrun in the debug package).

find.lurking.envs( myobj) will search through myobj and all its attributes, returning the size of each sub-object. The size of environments is returned as Inf. The search is completely recursive, except for environments and by default the inner workings of functions; attributes of the entire function are always recursed. Changing the delve parameter to TRUE ensures full recursion of function arguments and function bodies, which will show e.g. the srcref structure; try it to see why the default is FALSE. find.lurking.envs can be very useful for working out e.g. why the result of a model-fitting function is taking up 1000000MB of disk space; sometimes this is due to unnecessary environments in well-concealed places.

index returns the position(s) of TRUE elements. Unlike which: attributes are lost; NA elements map to NAs; index(<<length 0 object>>) is numeric(0); index( <<non-logical>>) is NA.

integ is a handy wrapper for integrate, that takes an expression rather than a function— so integ( sin(x), 0, 1) "just works".

is.dir tests for directoriness.

isF and isT test a logical scalar in the obvious way, with NA (and non-logicals) failing the test, to avoid teeeedious repetition of is( !is.na( my.complicated.expression) & my.complicated.expression) .... They are deliberately not vectorized (contrary to some versions of mvbutils documentation); arguments with non-1 length trigger a warning.

legal.filename coerces its character argument into a similar-looking string that is a legal filename on any (?) system.

logit and inv.logit apply those transformations (for those of us who can never remember what the stats package versions are called).

lsall is like ls but coerces all.names=TRUE.

masked checks which objects in search()[pos] are masked by identically-named objects higher in the search path. masking checks for objects mask identically-named objects lower in the search path. Namespaces may make the results irrelevant.

mkdir makes directories; unlike dir.create, it can do several levels at once.

most.recent returns the highest-so-far position of TRUE within a logical vector, or 0 if TRUE has not occurred yet; most.recent( c(F,T,F,T)) returns c(0,2,2,4).

mwhere subsets a data.frame by row, just like %where% (qv); it's for use in pipes, as per Examples.

my.all.equal is like all.equal, except that it returns FALSE in cases where all.equal returns a non-logical-mode result.

named(x) is just names(x) <- as.character( x); x; useful for lapply etc.

nscat, nscatn: see scatn

option.or.default obsolete— use equivalent getOption() instead.

pos is probably to be eschewed in new code, in favour of gregexpr with fixed=TRUE, which is likely faster. (And I should rewrite it to use gregexpr.) It's one of a few legacy functions in mvbutils that pre-date improvements in base R. pos will either search for several literal patterns in a single target, or vice versa– but not both. It returns a matrix showing the positions of the matching substrings, with as many columns as the maximum number of matches. 0 signifies "no match"; there is always at least one column even if there are no matches at all.

rename.els replaces specified names of a vector with new ones.

returnList returns a list corresponding to old-style (pre-R 1.8) return syntax. Briefly: a single argument is returned as itself. Multiple arguments are returned in a list. The names of that list are the argument names if provided; or, for any unnamed argument that is just a symbolic name, that symbolic name; or no name at all, for other unnamed arguments. You can duplicate pre-1.8 behaviour of return(...) via return(returnList(...)).

rsample draws n random samples from pop, according to replace and prob. It is like R's built-in sample but avoids the latter's inconsistent syntax, instead using a syntax similar to all the other r... random variable functions.

safe.rbind ( Deprecated in 2013 ) mimics rbind, but works round an R bug (I reckon) where a column appears to be a numeric in one data.frame but a factor in the other. But I now think you should just sort your column classes/types properly in advance, rather than mixing types and relying on somewhat arbitrary conversion rules.

scatn is just cat( sprintf( fmt, ...), "", file=file, sep=sep). scatn prints a newline afterwards, but not before; nscat does the opposite; nscatn does both. If you're just displaying a "title" before calling print, use nscat.

sqr squares its argument (i.e. multiplies the argument by itself), without the risk that x^2 might incur exponentiation.

to.regexpr converts literal strings to their equivalent regexps, e.g. by doubling backslashes. Useful if you want "fixed=TRUE" to apply only to a portion of your regexp.

undent is handy when you want a slab of multi-line text inside some function you are writing. Raw-string syntax helps a lot (see the final examples of ?Quotes), but indentation is horrible and the first line is out-of-step with the rest. You ideally want your text to appear indented at whatever looks nice inside your code, but for the actual string not to be indented. So, start your raw string with a newline, and wrap the string in undent, and all will be well.

sourceable takes a function and returns a character vector which, when printed with print or writeLines, will probably be amenable to source. Unlike deparse, it keeps the original source text, including comments. It will strip the "<environment:gsd907897gsd>" and "<bytecode:097a0sdg>" verbiage which otherwise often prevents source from working, and which frequently annoy me. But it will try to keep other attributes, such as useful "constants" accessed from within the function's code via eg environment(sys.function())$<usefulconst>. sourceable may be more generally useful than the similar write.sourceable.function because the latter is geared up to dealing directly with the mvbutils function-documentation system, and also actually writes to a file— whereas sourceable returns a character vector (of class cat) which it's up to you to write or whatever.

xfactor either turns a non-factor x into a factor, honouring the exclude argument of factor; or, with a factor x, maps any NA levels to a non-NA level with label "\001" (ASCII 1). ICNR why :)

xsub and xgsub are for pipes. They are just like sub and gsub, except that the x argument comes first, and that there is a default of perl=TRUE (unless you set fixed=TRUE). So you can write eg str |> xsub( "old", "new") rather than str |> sub( "old", "new", x=_) or sub( "old", "new", str). It's just better.

yes.no cats its "prompt" argument and waits for user input. if the user input pmatches "yes" or "YES", then yes.no returns TRUE; if the input pmatches no or NO then yes.no returns FALSE; if the input is ” and default is set, then yes.no returns default; otherwise it repeats the question. You probably want to put a space at the end of prompt.

Value

as.cat	character vector of class cat
clip	vector of the same mode as x
cq	character vector
empty.data.frame	data.frame
env.name.string	a string
expanded.call	a call object
everyth	same type as x
find.funs	a character vector of function names
find.scriptlets	a character vector of scriptlet names
find.lurking.envs	a data.frame with columns "what" and "size"
integ	scalar
inv.logit	numeric vector
is.dir	logical vector
is.nonzero	TRUE or FALSE
isF, isT	TRUE or FALSE
legal.filename	character( 1)
logit	numeric vector
masked	character vector
masking	character vector
mclip	possibly-modified version of x
mkdir	logical vector of success/failure
nscat	NULL
nscatn	NULL
most.recent	integer vector the same length as lvec, with values in the range (0,length(lvec)).
named	vector of the same mode as x
option.or.default	option's value
pos	numeric matrix, one column per match found plus one; at least one column guaranteed
rename.els	whatever the first argument was, with new names
returnList	list or single object
rsample	vector of same type as pop
safe.rbind	data.frame
scatn	NULL
sourceable	character (class cat to print nicely)
sqr	as per input
to.regexpr	character
undent	string
xgsub	character
xsub	character
yes.no	TRUE or FALSE

Arguments by function

add_list_defaults

l: a list. ...: name-value pairs that act as defaults for l if it doesn't already contain elements with those names.

as.cat

x: character vector that you want to be displayed via cat( x, sep="\n")

atts

x: any object; exclude: a character vector whatever quotidian attributes that you are not interested in knowing about

clip

x: a vector or list

clip

n: integer saying how many elements to clip from the end of x

cq

...: quoted or unquoted character strings, to be substituted and then concatenated

deparse.names.parsably

x: any object for deparse- name objects treated specially

eclone

env: an environment

empty.data.frame

...: named length-1 vectors of appropriate mode, e.g. "first.col=”"

env.name.string

env: environment

expanded.call

nlocal: frame to retrieve arguments from. Normally, use the default; see mlocal.

everyth

x: subsettable thing. by: step between values to extract. from: first position.

find.funs, find.scriptlets

...: extra arguments for objects. Usually just "pattern" for regexp searches.

find.funs, find.scriplets

exclude.mcache: if TRUE (default), don't look at mlazy objects

find.funs

mode: "function" to look for functions, "environment" to look for environments, etc

find.scriptlets

pattern: regexp that scriptlet names should match.

find.lurking.envs

delve: whether to recurse into function arguments and function bodies

find.lurking.envs

trace: just a debugging aid– leave as FALSE

index

lvector: vector of TRUE/FALSE/NA

integ

expr: an expression; what: a string, the argument of expr to be integrated over; lo, hi: limits; ...: other variables to be set in the expression; args.to.integrate: a list of other things to pass to integrate

is.dir

dir: character vector of files to check existence and directoriness of.

isF, isT

x: anything, but meant to be a logical scalar

legal.filename

name: character string to be modified

find.funs

pos: list of environments, or vector of char or numeric positions in search path.

lsall

...: as for ls, except that all.names will be coerced to TRUE

masking, masked

pos: position in search path

mclip

x: thing to be clipped (usually numeric, but character should work)— dimensions and other attributes are preserved; min, max: clipping range

mkdir

dirlist: character vector of directories to create

most.recent

logical vector

my.all.equal

x, y: anything; ...: passed to all.equal

named

x: character vector which will become its own names attribute

nscat, nscatn

see scatn

option.or.default

opt.name: character(1)

option.or.default

default: value to be returned if there is no option called "opt.name"

pos

substrs: character vector of patterns (literal not regexpr)

pos

mainstrs: character vector to search for substrs in.

pos

any.case: logical- ignore case?

pos

names.for.output: character vector to label rows of output matrix; optional

put.in.session

...: a named set of objects, to be assigned into the mvb.session.info search environment

rename.els

...: the first argument is the thing to rename. Subsequent args like X=<some expr giving a string result> mean that whichever element of the first arg was called "X", will now be called the result of that expression. ignore.missing=TRUE means that requests to rename non-existent elements will be ignored; otherwise, they will throw an error.

returnList

...: named or un-named arguments, just as for return before R 1.8.

rsample

n: number to draw; pop: values they can take; replace: whether to sample with replacement; prob: weights (must be same length as pop)

safe.rbind

df1, df2: data.frame or list

scatn, nscat

fmt, ...: as per sprintf; file, sep, append: as per cat

sourceable

f: an actual function object

sourceable

fname: what name should the function be assigned to, if the result is fed to source? Default is the name of f itself, which is usually fine.

sqr

x: anything for which * is a valid op.

to.regexpr

x: character vector

undent

s: string, presumably a "raw string".

xfactor

a factor.

xgsub

x, pattern, replacement, perl=!fixed, fixed= FALSE, ...: as per gsub

xsub

as per xgsub

yes.no

prompt: string to put before asking for input

yes.no

default: value to return if user just presses <ENTER>

Author(s)

Mark Bravington

Examples

# add_list_defaults
ll <- list( A='cat', B=c('dog','goldfish'), C='funnelweb')
add_list_defaults( ll, B='rabbit', D='anthrax')
# B does not change, but D is added
# as.cat
ugly.bugly <- c( 'A rose by any other name', 'would annoy taxonomists')
ugly.bugly
#[1] "A rose by any other name"                 "would annoy taxonomists"
as.cat( ugly.bugly) # calls print.cat--- no clutter
#A rose by any other name
#would annoy taxonomists
x <- structure( matrix( 1:4, 2, 2), baggage='purple suitcase')
atts( x) # will not print "dim" since that is in default 'exclude' list
#[1] "baggage"
1:7 |> clamp( 2, 4)
#[1] 2 2 3 4 4 4 4
1:7 |> clamp( 2:4)
#[1] 2 2 3 4 4 4 4
clip( 1:5, 2) # 1:3
cq( alpha, beta) # c( "alpha", "beta")
x <- matrix( 1:4, 2, 2)
compacto( x)
compacto( x, extra='|', width=3) # similar to gap... yet different
colnames( x) <- c( 'Gogol', 'Turgenev')
compacto( x)
x <- 6
attr( x, 'massive') <- 1:1e3 # not that massive; used to have 1e5, but
# ... CRAN checks prints bloody everything!
x
disatt( x)
old_env <- new.env()
evalq( envir=old_env, {
  x <- 3
  fun <- function() x
})
new_env <- eclone( old_env)
new_env$x <- 5
new_env$fun() # 5
lazy_env <- old_env
lazy_env$x <- 4
old_env$x # 4 ! Take care with environments...
old_env$fun() # 4 of course
new_env$x # 5 phew
empty.data.frame( a=1, b="yes")
# data.frame with 0 rows of columns "a" (numeric) and "b" (character)
empty.data.frame( a=1, b=factor( c( "yes", "no")))$b
# factor with levels c( "no", "yes")
everyth( 1:10, 3, 5) # c( 5, 8)
f <- function( a=9, b) expanded.call(); f( 3, 4) # list( a=3, b=4)
find.funs( "package:base", patt="an") # "transform" etc.
e <- new.env()
e$myscript.R <- as.cat( string2charvec( r"{
  # raw strings are great!
  dir()
}"))
find.scriptlets( e) # "myscript.R"
find.lurking.envs( cd)
#                                     what  size
#1                     attr(obj, "source")  5368
#2                                     obj 49556
#3 environment(obj) <: namespace:mvbutils>   Inf
## Don't run:
eapply( .GlobalEnv, find.lurking.envs)
## End don't run
integ( sin(x), 0, 1) # [1] 0.4597
integ( sin(x+a), a=5, 0, 1) # [1] -0.6765; 'a' is "passed" to 'expr'
integ( sin(y+a), what='y', 0, 1, a=0) # [1] 0.4597; arg is 'y' not 'x'
is.dir( getwd()) # TRUE
isF( FALSE) # TRUE
isF( NA) # FALSE
isF( c( FALSE, FALSE)) # FALSE, with a warning
sapply( c( FALSE, NA, TRUE), isF)
# [1]  TRUE FALSE FALSE
sapply( c( FALSE, NA, TRUE), isT)
# [1] FALSE FALSE  TRUE
legal.filename( "a:b\\c/d&f") # "a.b.c.d&f"
most.recent( c( FALSE,TRUE,FALSE,TRUE)) # c( 0, 2, 2, 4)
# mwhere for subsetting: find vowels whose alphetic position is a multiple of 5
df <- data.frame( x=1:10, y=LETTERS[ 1:10])
# Base-R pipes may not exist for the R version being used here
# So, try to parse the expression first...
pp <- try( parse( text=
 'df |> mwhere( x %% 5 == 0) |> mwhere( y %in% cq( A,E,I,O,U))'
))
if( pp %is.not.a% 'try-error') eval( pp[[1]]) # just E-row
rsample( 9, LETTERS[1:3], replace=TRUE)
sapply( named( cq( alpha, beta)), nchar)  # c( alpha=5, beta=4)
pos( cq( quick, lazy), "the quick brown fox jumped over the lazy dog")
# matrix( c( 5, 37), nrow=2)
pos( "quick", c( "first quick", "second quick quick", "third"))
# matrix( c( 7,8,0, 0,14,0), nrow=3)
pos( "quick", "slow") # matrix( 0)
x <- c( Cat='good', Dog='bad')
rename.els( x, Cat='Armadillo')
# Armadillo       Dog
#    "good"     "bad"
try( rename.els( x, Zorilla='Bandicoot'))
# Error in rename.els(x, Zorilla = "Bandicoot") : all(present) is not TRUE
rename.els( x, Zorilla='Bandicoot', ignore.missing=TRUE)
#    Cat    Dog
# "good"  "bad"
f <- function() { a <- 9; return( returnList( a, a*a, a2=a+a)) }
f() # list( a=9, 81, a2=18)
scatn( 'Things %i', 1:3)
nscat( 'Things %i', 1:3)
nscatn( 'Things %i', 1:3)
to.regexpr( "a{{") # "a\\{\\{"
    test <- undent( r"--{
        I can indent this
          howsoever I like.
        New paragraph!
      }--")
as.cat( test)
glurp <- function( x) const + x
attr( glurp, 'const') <- 44
sourceable( glurp)
# To avoid an intermediate file, use
# ... eval(parse(text=<>))) in place of source
oglurp <- glurp
glurp <- eval( parse( text= sourceable( glurp))) # will overwrite klunge
identical( glurp, oglurp) # yes
longstring <- 'Bollocks, then the good stuff, then more bollocks'
longstring |> xsub( ',[^,]*$', '') |> xsub( '.*, *', '')
# "then the good stuff"
## Don't run:
# and i mean REALLY don't, so stop crazy Craniac bypasses...
if( FALSE){ mkdir( "subdirectory.of.getwd")}
if( interactive()) yes.no( "OK (Y/N)? ")
masking( 1)
masked( 5)
## End don't run

mvbutils documentation built on May 25, 2026, 5:09 p.m.