topmod: Topmodel Object
In BMS: Bayesian Model Averaging Library

topmod

R Documentation

Topmodel Object

Description

Create or use an updateable list keeping the best x models it encounters (for advanced users)

Usage

topmod(
  nbmodels,
  nmaxregressors = NA,
  bbeta = FALSE,
  lengthfixedvec = 0,
  liks = numeric(0),
  ncounts = numeric(0),
  modelbinaries = matrix(0, 0, 0),
  betas = matrix(0, 0, 0),
  betas2 = matrix(0, 0, 0),
  fixed_vector = matrix(0, 0, 0)
)

Arguments

`nbmodels`	The maximum number of models to be retained by the topmod object
`nmaxregressors`	The maximum number of covariates the models in the topmod object are allowed to have
`bbeta`	if `bbeta=TRUE`, then first and second moments of model coefficients are stored in addition to basic model statistics (Note: if `bbeta<0` then only the first moments are saved)
`lengthfixedvec`	The length of an optional fixed vector adhering to each model (for instance R-squared, etc). If `lengthfixedvec=0` then no additonal fixed vector will be stored.
`liks`	optional vector of log-likelihoods to initialize topmod object with (length must be `<=nbmodels`) - see example below
`ncounts`	optional vector of MCMC frequencies to initialize topmod object with (same length as `liks`) - see example below
`modelbinaries`	optional matrix whose columns detail model binaries to initialize topmod object with (same nb columns as `liks`, nb rows as `nmaxregressors`) - see example below
`betas`	optional matrix whose columns are coefficients to initialize topmod object with (same dimensions as `modelbinaries`) - see example below
`betas2`	optional matrix whose columns are coefficients' second moments to initialize topmod object with (same dimensions as `modelbinaries`) - see example below
`fixed_vector`	optional matrix whose columns are a fixed vector initialize topmod object with (same `ncol` as `modelbinaries`) - see example below

Details

A 'topmod' object (as created by topmod) holds three basic vectors: lik (for the (log) likelihood of models or similar), bool() for a hexcode presentation of the model binaries (cf. bin2hex) and ncount() for the times the models have been drawn.
All these vectors are sorted descendantly by lik, and are of the same length. The maximum length is limited by the argument nbmodels.

If tmo is a topmod object, then a call to tmo$addmodel (e.g. tmo$addmodel(mylik=4,vec01=c(T,F,F,T)) updates the object tmo by a model represented by vec01 (here the one including the first and fourth regressor) and the marginal (log) likelihood lik (here: 4).

If this model is already part of tmo, then its respective ncount entry is incremented by one; else it is inserted into a position according to the ranking of lik.

In addition, there is the possibility to save (the first moments of) coefficients of a model (betas) and their second moments (betas2), as well as an arbitrary vector of statistics per model (fixed_vector).

is.topmod returns TRUE if the argument is of class 'topmod'

Value

a call to topmod returns a list of class "topmod" with the following elements:

`addmodel(mylik,vec01,vbeta=numeric(0),vbeta2=numeric(0),fixedvec=numeric(0))`	function that adjusts the list of models in the 'topmod' object (see Details). `mylik` is the basic selection criterion (usually log likelihood), `vec01` is the model binary (logical or numeric) indicating which regressors are included. `vbeta` is a vector of length equal to `sum(vec01)`, contianing only the non-zero coefficients (only accounted for if `bbeta!=FALSE`). `vbeta2` is a similar vector of second moments etc. (only accounted for if `bbeta=TRUE`); `fixedvec` is an arbitrary vector of length `lengthfixedvec` (see above)
`lik()`	A numeric vector of the best models (log) likelihoods, in decreasing order
`bool()`	A character vector of hexmode expressions for the model binaries (cf. `bin2hex`), sorted by `lik()`
`ncount()`	A numeric vector of MCMC frequencies for the best models (i.e. how often the respective model was introduced by `addmodel`)
`nbmodels`	Returns the argument `nbmodel`
`nregs`	Returns the argument `nmaxregressors`
`bool_binary()`	Returns a matrix whose columns present the models conforming to `lik()` in binary form
`betas()`	a matrix whose columns are the coefficients conforming to `bool_binary()` (Note that these include zero coefficients due to non-inclusion of covariates); Note: if `bbeta=FALSE` this returns an empty matrix
`betas2()`	similar to `betas` , for the second moments of coefficients Note: if `bbeta<=0`, this returns an empty matrix
`fixed_vector()`	The columns of this matrix return the `fixed_vector` statistics conforming to `lik()` (see Details); Note: if `lengthfixedvec=0` this returns an empty matrix

Note

topmod is rather intended as a building block for programming; it has no direct application for a user of the BMS package.

Examples


#standard use
  tm= topmod(2,4,TRUE,0) #should keep a  maximum two models
  tm$addmodel(-2.3,c(1,1,1,1),1:4,5:8) #update with some model
  tm$addmodel(-2.2,c(0,1,1,1),1:3,5:7) #add another model
  tm$addmodel(-2.2,c(0,1,1,1),1:3,5:7) #add it again -> adjust ncount
  tm$addmodel(-2.5,c(1,0,0,1),1:2,5:6) #add another model
  
  #read out
  tm$lik()
  tm$ncount()
  tm$bool_binary()
  tm$betas()
  
  is.topmod(tm)
  
  #extract a topmod oobject only containing the second best model
  tm2=tm[2]
  
  
  
  #advanced: should return the same result as
  #initialize
  tm2= topmod(2,4,TRUE,0, liks = c(-2.2,-2.3), ncounts = c(2,1), 
          modelbinaries = cbind(c(0,1,1,1),c(1,1,1,1)), betas = cbind(0:3,1:4), 
          betas2 = cbind(c(0,5:7),5:8)) 

  #update 
  tm$addmodel(-2.5,c(1,0,0,1),1:2,5:6) #add another model
  
  #read out
  tm$lik()
  tm$ncount()
  tm$bool_binary()
  tm$betas()

BMS documentation built on Aug. 9, 2022, 5:08 p.m.