REPORTO: Stash variables in caller's environment

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

Stash variables in caller's environment

Description

REPORTO is a convenience function for use during model-fitting, when you have a hand-written "objective function" to optimize. Suppose your function obfun computes lots of jolly interesting intermediate quantities, which you would like to preserve somewhere, before the function exits and they vanish. Then, just insert a call eg REPORTO( key_result, fascinating, important) somewhere. You can make multiple calls to REPORTO (with different variables...) and they will all be stashed.

You should probably give obfun an environment before you do this, otherwise the interesting stuff will end up in .GlobalEnv (if you are lucky), resulting in clutter. You can also use environment(obfun) to pre-stash data (i.e., before you invoke the function), so that obfun will be able to just refer directly to it, again without cluttering up .GlobalEnv. That level of self-discipline is worth cultivating. See Examples, and eg ?closure for some kind of intro to R's lexical-scoping rules, on which this all depends. There must be a more reader-friendly help link somewhere, though...

Of course, you can do all this with base-R commands anyway (see below). But a key reason for using REPORTO— at least if you are using the package offarray— is that the package offartmb will automatically translate REPORTO calls into RTMB::REPORT calls, so your code can then run under package RTMB without further modification; see offarray::reclasso. Plus, even in normal R use, the REPORTO( var1, var2) syntax is clearer and easier.

Pedants corner

HaRd-nuts will note that normal-R-use REPORTO is "just" syntactic sugar for the totally-self-explanatory idiom:

  list2env( mget( c( "key_result", "fascinating", "important")),
    envir=environment( sys.function()))

And, yes, of course, in normal-R use you can also achieve the effect via <<- and assign. But the former requires you to pre-create the interesting things in environment( obfun), the latter has pig-ugly syntax, and both require self-discipline, which is hateful to me anyway. However, if you really want to do all that, feel free! (And remember to write your own code to handle the RTMB case.)

Usage

REPORTO(..., names = NULL)

Arguments

...	variables you want to stash— unquoted. Can be empty.
names	A character vector with the names of additional variables to stash.

Thus, REPORTO(myvar) or REPORTO(names="myvar") have identical effects. The names argument is handy if you want to stash, say, all variables whose names begin with "ncomps_"— then REPORTO(names=ls(pattern="^ncomps_").

Value

REPORTO itself returns NULL; it is called for its side-effects.

Examples

rego <- function( beta){
  v1 <- X %*% beta
  v2 <- y-v1
  REPORTO( v1, v2)
  ssq <- sum( v2*v2)
return( ssq)
}
e <- new.env( parent=environment( rego))
e$X <- matrix( 1:6, 3, 2)
e$y <- 7:9
environment( rego) <- e
# Now rego will "know about" X & y...
rego( c( 1.6, 2.4))
# ... and it can stash its results there
e$v1
e$v2

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