...
 
Commits (25)
Package: RaschSampler
Type: Package
Title: Rasch Sampler
Version: 0.8-8
Date: 2015-07-23
Authors@R: c(person(given="Patrick", family="Mair", email="mair@fas.harvard.edu", role=c("cre","aut")),
person(given="Reinhold", family="Hatzinger", role=c("aut")),
person(given=c("Norman", "D."), family="Verhelst", email="norman.verhelst@cito.nl", role=c("aut")))
Imports: stats
Depends: R (>= 3.0.0)
Description: MCMC based sampling of binary matrices with fixed margins as used in exact Rasch model tests.
License: GPL-2
NeedsCompilation: yes
Packaged: 2015-07-23 12:32:11 UTC; patrick
Author: Patrick Mair [cre, aut],
Reinhold Hatzinger [aut],
Norman D. Verhelst [aut]
Maintainer: Patrick Mair <mair@fas.harvard.edu>
Repository: CRAN
Date/Publication: 2015-07-23 15:13:53
0f3a11ff77d31df178fcc6dc3d1918f3 *DESCRIPTION
b0e4b24c80fcfc422df602bafcf89ecb *NAMESPACE
37383b86a5a2d72e3c196556e3eaf09c *R/phi.range.R
da2aaf90411032f77c125a1802a17c9f *R/rsampler.R
58c7acdcb60e5fef2d4bad8ff79f3751 *R/rsctrl.R
96f255d9169d2c9b8b0121c457df43de *R/rserror.R
84af75ad5133358a996b4f1334328453 *R/rsextrmat.R
7b5ffeb67fffbae19d8cea59e7d000e3 *R/rsextrobj.R
f5999b30f71b9b9e1635a2167d217c9d *R/rstats.R
e1414590f20a4138cd04abda1c5066f4 *R/rsunpack.R
ad5211ab843e04ee7e0564032f0a5f1e *R/summary.RSctr.R
bb58a9a1c07452f36f935b101a61e52a *R/summary.RSmpl.R
c164f97f003fe597393346ebc34ed98f *R/summary.RSmplext.R
bac1d538a1aef726f38615aa18f3d48a *data/xmpl.rda
1fc251a885b608884a2e4b3240d92259 *data/xmplbig.rda
d3482a367fc1f9aaa27ec2e1618115c4 *man/RSctr.Rd
a0bfdc2c3a0156ea4cd2bcbdee7dd8e8 *man/RSmpl.Rd
8ce58747a871df82a3bade4e57805245 *man/RaschSampler-package.Rd
37b00ccd880232d2f889b84dc84c5dc8 *man/phi.range.Rd
ade46dd1d3d391419c9bfc573620a3d0 *man/rsampler.Rd
61388178ae969add6843305c46c1d72a *man/rsctrl.Rd
be376726ca2bda6d77acd30bef8d8461 *man/rsextrmat.Rd
7e389f288d5df3a16b605b283b7b36af *man/rsextrobj.Rd
9b4c576feee94237ec6a42cc8842f30e *man/rstats.Rd
afa498436f176dffc611229bd827ecb1 *man/summary.RSctr.Rd
158cee36a240d52bde1e3d9a6f90e53f *man/summary.RSmpl.Rd
3f44b380fea685a7662ffd351a4fe6ac *man/xmpl.Rd
fd59ab36845ad7023f529dbd04660c40 *src/RaschSampler.f90
useDynLib(RaschSampler)
import("stats")
export(rsampler)
export(rstats)
export(rsctrl)
export(rsextrobj)
export(rsextrmat)
export(phi.range)
S3method(summary, RSctr)
S3method(summary, RSmpl)
S3method(summary, RSmplext)
"phi.range" <-
function(mat){
cmat<-cor(mat)+diag(NA,ncol(mat))
ma<-max(cmat,na.rm=TRUE)
mi<-min(cmat,na.rm=TRUE)
RET <- ma-mi
RET
}
"rsampler" <-
function(inpmat,controls=rsctrl()){
if (!(class(controls)=="RSctr"))
stop("controls is not a control object - see help(\"rsctrl\")")
n <- dim(inpmat)[1]
k <- dim(inpmat)[2]
burn_in <- controls$burn_in
n_eff <- controls$n_eff
step <- controls$step
seed <- controls$seed
tfixed <- controls$tfixed
if (seed == 0) {
# generates random seed in the range [536870911,772830910]
seed <- as.integer(as.double(format(Sys.time(), "%H%M%OS3"))*1000)
+ 2**29 - 1
}
# allocation of memory for simulated matrices
vec<-vector( length = (n_eff+1)*n*trunc((k+31)/32) )
ier<-0
# calls the external Fortran subroutine sampler
# simulated matrices are returned in vec
RET<-.Fortran("sampler",
n=as.integer(n),
k=as.integer(k),
inpmat=as.integer(inpmat),
tfixed=as.logical(tfixed),
burn_in=as.integer(burn_in),
n_eff=as.integer(n_eff),
step=as.integer(step),
seed=as.integer(seed),
outvec=as.integer(vec),
ier=as.integer(ier)
)
n_tot <- n_eff+1
if (RET$ier>0) {
rserror(RET$ier)
} else {
RET<-c(RET[1:8],n_tot=n_eff+1,RET[9:10])
class(RET)<-"RSmpl"
RET
}
}
"rsctrl" <-
function(burn_in=100, n_eff=100, step=16,
seed=0, tfixed=FALSE)
{ ier <- 0
if(n_eff < 0 | n_eff > 8191) ier <- ier + 4
if(burn_in < 0) ier <- ier + 8
if(step <= 0) ier <- ier + 16
if(seed < 0 | seed > (2**31-2)) ier <- ier + 128
if (ier>0) rserror(ier)
RET<-list(burn_in=burn_in, n_eff=n_eff, step=step,
seed=seed, tfixed=tfixed)
class(RET)<-"RSctr"
RET
}
"rserror" <-
function(err)
{
bin2int<-function(x){
r<-vector(mode="integer",length=0)
while(x>1){
r<-c(x%%2,r)
x<-floor(x/2)
}
r<-c(1,r)
rev(r)
}
errortxt<-c("\tn < 0 or n > 4096\n",
"\tk < 0 or k > 128\n",
"\tn_eff < 0 or n_eff > 8191\n",
"\tburn_in < 0\n",
"\tstep <= 0\n",
"\tone or more entries in the input matrix are different from 1 or 0\n",
"\tthe input matrix is of Guttman form; the sample space has only one element\n",
"\tseed < 0 or seed > 2147483646\n"
)
if (err == 0) {
cat("\nno error\n")
} else {
x <- bin2int(err)
errstring <- paste("\n",paste(errortxt[(1:length(x))*x],sep="",collapse=""))
stop(errstring, call.=FALSE)
}
invisible(err)
}
"rsextrmat" <-
function(RSobj, mat.no = 1)
{
obj.name <- deparse(substitute(RSobj))
if (!(class(RSobj)=="RSmpl" || class(RSobj)=="RSmplext")){
err.text<-paste(obj.name," is not a sample object - see help(\"rsextrobj\")",sep ="",collapse="")
stop(err.text)
}
if(mat.no > RSobj$n_tot)
stop("\n\tElement ",mat.no," not available (",obj.name," has ", RSobj$n_tot, " elements).")
obj<-rsextrobj(RSobj, start = mat.no, end = mat.no)
RET<-rstats(obj, function(x) matrix(x, nrow = obj$n))[[1]]
RET
}
"rsextrobj" <-
function(RSobj,start=1,end=8192)
{
obj.name <- deparse(substitute(RSobj))
if (!(class(RSobj)=="RSmpl" || class(RSobj)=="RSmplext")){
err.text<-paste(obj.name,"not a sample object - see help(\"rsextrobj\")",sep ="",collapse="")
stop(err.text)
}
n_tot <- RSobj$n_tot
if (end>n_tot) end<-n_tot
n <- RSobj$n
k <- RSobj$k
nwords <- c(trunc((k+31)/32))
objnew <- RSobj
l_one_mat <- n*nwords
b <- (start-1)*l_one_mat+1
e <- end*l_one_mat
objnew$outvec <- RSobj$outvec[b:e]
objnew$n_tot <- end-start+1
if (start==1) {
objnew$n_eff <- objnew$n_tot - 1
} else {
objnew$n_eff <- objnew$n_tot
}
class(objnew)="RSmplext"
RET<-objnew
RET
}
"rstats" <-
function(RSobj,userfunc,...)
{
obj.name <- deparse(substitute(RSobj))
if (!(class(RSobj)=="RSmpl" || class(RSobj)=="RSmplext")){
err.text<-paste(obj.name," is not a sample object - see help(\"rsextrobj\")",sep ="",collapse="")
stop(err.text)
}
# extracts simulated matrices into three dimensional array sim
n_tot <- RSobj$n_tot
n <- RSobj$n
k <- RSobj$k
nwords <- c(trunc((k+31)/32))
# store coded simulated matrices in list with n_eff+1 elements
sim<-split(RSobj$outvec,gl(n_tot,n*nwords))
# decode simulated matrices and apply user function
#RET<-unlist(lapply(sim,rsunpack,n,k,nwords,userfunc))
RET<-lapply(sim,rsunpack,n,k,nwords,userfunc,...)
RET
}
"rsunpack" <-
function(x,n,k,nwords,userfunc,...){
# check for NAs (-2^31 not defined in R) in simulated matrices
# set value to 0
nas<-FALSE
if (k>=32) {
idx<-(1:length(x))[is.na(x)] # indexvector for NAs
nas<-(length(idx)>0)
x[idx]<-0
}
t<-vector(length=n*k)
# calls unpacking routine
out<-.Fortran("unpack",
as.integer(x),
as.integer(nwords),
mat=as.integer(t),
as.integer(n),
as.integer(k)
)
m<-matrix(out$mat,nrow=n)
# replace NAs with bitpattern corresponding to -2^31,
# i.e., 0 0 0.... 0 1
if (nas) {
idx1 <- ceiling(idx/nwords) # index for rows
targetbyte <- idx%%nwords # which byte in row is affected
last <- k%%32 # last column in targetbyte
idx2 <- (targetbyte - 1*(last!=0))*32 + last # index for column
m[idx1,idx2]<-1
}
# calls user function to calculate statistic(s)
RET<-userfunc(m,...)
RET
}
"summary.RSctr" <-
function(object,...)
{
cat("\nCurrent sampler control specifications in ",deparse(substitute(object)),":\n", sep="")
cat("\tburn_in =",object$burn_in,"\n")
cat("\tn_eff =",object$n_eff,"\n")
cat("\tstep =",object$step,"\n")
cat("\tseed =",object$seed,"\n")
cat("\ttfixed =",object$tfixed,"\n\n")
invisible(object)
}
"summary.RSmpl" <-
function(object,...)
{
cat("\nStatus of object",deparse(substitute(object)),"after call to RSampler:\n")
cat("\tn =",object$n,"\n")
cat("\tk =",object$k,"\n")
cat("\tburn_in =",object$burn_in,"\n")
cat("\tn_eff =",object$n_eff,"\n")
cat("\tstep =",object$step,"\n")
cat("\tseed =",object$seed,"\n")
cat("\ttfixed =",object$tfixed,"\n")
cat("\tn_tot =",object$n_tot,"\n")
cat("\toutvec contains",length(object$outvec),"elements\n\n")
}
"summary.RSmplext" <-
function(object,...)
{
cat("\nStatus of extracted object ",deparse(substitute(object)),":\n", sep="")
cat("\tn =",object$n,"\n")
cat("\tk =",object$k,"\n")
cat("\tburn_in =",object$burn_in,"\n")
cat("\tn_eff =",object$n_eff,"\n")
cat("\tstep =",object$step,"\n")
cat("\tseed =",object$seed,"\n")
cat("\ttfixed =",object$tfixed,"\n")
cat("\tn_tot =",object$n_tot,"\n")
cat("\toutvec contains",length(object$outvec),"elements\n\n")
}
File added
Explanation for binary files inside source package according to
https://lists.debian.org/debian-devel/2013/09/msg00332.html
Files: data/xmplbig.rda
Documented: man/xmpl.Rd
Example Data
Files: data/xmpl.rda
Documented: man/xmpl.Rd
Example Data
-- Andreas Tille <tille@debian.org> Thu, 21 Jun 2018 16:19:46 +0200
r-cran-raschsampler (0.8-8-2) unstable; urgency=medium
* Team upload.
* debhelper 11
* Maintainer: Debian R Packages Maintainers <r-pkg-team@alioth-
lists.debian.net>
* Point Vcs fields to salsa.debian.org
* dh-update-R to update Build-Depends
* Secure URI in watch file
* Document example data
-- Andreas Tille <tille@debian.org> Thu, 21 Jun 2018 16:20:42 +0200
r-cran-raschsampler (0.8-8-1) unstable; urgency=medium
* New upstream version
* Take over packaging into Debian Science team
* Consistent naming between source and binary package
* cme fix dpkg-control
* Convert to dh-r
* Canonical homepage for CRAN
* DEP5 fixes
* debhelper 10
* d/watch: version=4
* drop gfortran from Build-Depends since it is installed due to rdepends
-- Andreas Tille <tille@debian.org> Mon, 12 Dec 2016 11:39:24 +0100
raschsampler (0.8-6-1) unstable; urgency=low
* New upstream release; changes appear to be cosmetic only
-- Julian Gilbey <jdg@debian.org> Fri, 18 Oct 2013 08:06:38 +0100
raschsampler (0.8-5-4) unstable; urgency=low
* Update the control file to Build-Depend on plain r-base-dev and to
Depend on ${R:Depends}
-- Julian Gilbey <jdg@debian.org> Sun, 07 Apr 2013 09:40:42 +0100
raschsampler (0.8-5-3) unstable; urgency=low
* Update the control file to show the correct R dependencies
-- Julian Gilbey <jdg@debian.org> Sat, 06 Apr 2013 21:53:41 +0100
raschsampler (0.8-5-2) unstable; urgency=low
* Rebuild for R 3.0.0
-- Julian Gilbey <jdg@debian.org> Fri, 05 Apr 2013 13:32:58 +0000
raschsampler (0.8-5-1) unstable; urgency=low
* New upstream release
* Updated standard version to 3.9.3.
* Converted copyright file to copyright-format 1.0
-- Julian Gilbey <jdg@debian.org> Sun, 18 Mar 2012 12:29:20 +0000
raschsampler (0.8-4-1) unstable; urgency=low
* Initial Debian release; needed for bug #544402 as eRm depends upon
this package
-- Julian Gilbey <jdg@debian.org> Mon, 10 May 2010 22:29:13 +0100
Source: r-cran-raschsampler
Maintainer: Debian R Packages Maintainers <r-pkg-team@alioth-lists.debian.net>
Uploaders: Julian Gilbey <jdg@debian.org>
Section: gnu-r
Testsuite: autopkgtest-pkg-r
Priority: optional
Build-Depends: debhelper (>= 11~),
dh-r,
r-base-dev
Standards-Version: 4.1.4
Vcs-Browser: https://salsa.debian.org/r-pkg-team/r-cran-raschsampler
Vcs-Git: https://salsa.debian.org/r-pkg-team/r-cran-raschsampler.git
Homepage: https://cran.r-project.org/package=RaschSampler
Package: r-cran-raschsampler
Architecture: any
Depends: ${R:Depends},
${shlibs:Depends},
${misc:Depends}
Recommends: ${R:Recommends}
Suggests: ${R:Suggests}
Description: GNU R package for sampling binary matrices with fixed margins
This package implements an MCMC algorithm for sampling of binary
matrices with fixed margins complying to the Rasch model. Its
stationary distribution is uniform. The algorithm also allows
for square matrices with fixed diagonal.
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: RaschSampler
Upstream-Contact: Reinhold Hatzinger <reinhold.hatzinger@wu.ac.at>
Source: https://cran.r-project.org/package=RaschSampler
Files: *
Copyright: 2006-2015 Reinhold Hatzinger, Patrick Mair and Norman Verhelst
License: GPL-2
Files: src/RaschSampler.f90
Copyright: 2006 Norman Verhelst
License: GPL-2
Files: debian/*
Copyright: 2010-2014 Julian Gilbey <jdg@debian.org>
License: GPL-2+
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
.
You should have received a copy of the GNU General Public
License along with this package; if not, write to the Free
Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA 02110-1301 USA.
.
On Debian systems, the full text of the GNU General Public
License version 2 can be found in the file
`/usr/share/common-licenses/GPL-2'.
License: GPL-2
This program is free software; you can redistribute it
and/or modify it under the terms of version 2 of the GNU
General Public License as published by the Free Software
Foundation.
.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
.
You should have received a copy of the GNU General Public
License along with this package; if not, write to the Free
Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA 02110-1301 USA.
.
On Debian systems, the full text of the GNU General Public
License version 2 can be found in the file
`/usr/share/common-licenses/GPL-2'.
#!/usr/bin/make -f
%:
dh $@ --buildsystem R
version=4
https://cran.r-project.org/src/contrib/RaschSampler_([-0-9\.]*).tar.gz
\name{RSctr}
\alias{RSctr}
\title{Control Object}
\description{
The object of class \code{RSctr} represents the control parameter
specification for the sampling function \code{\link{rsampler}}.
}
\value{
A legitimate \code{\link{RSctr}} object is a list with components
\item{burn_in}{
the number of matrices to be sampled to
come close to a stationary distribution.
}
\item{n_eff}{
the number of effective matrices, i.e.,
the number of matrices
to be generated by the sampling function \code{\link{rsampler}}.
}
\item{step}{
controls the number number of void matrices generated in the the burn in
process and when effective matrices are generated (see note
in \code{\link{rsctrl}}). }
\item{seed}{
is the indicator for the seed of the random number generator.
If the value of seed at equals zero, a seed is generated
by the sampling function \code{\link{rsampler}}
}
\item{tfixed}{
\code{TRUE} or \code{FALSE}. \code{tfixed = TRUE} has no effect
if the input matrix is not quadratic,
i.e., all matrix elements are considered free (unrestricted).
If the input matrix is quadratic, and \code{tfixed = TRUE},
the main diagonal of the matrix is considered as fixed.
}
}
\section{Generation}{
This object is returned from function
\code{rsctrl}.
}
\section{Methods}{
This class has a method for the generic \code{summary}
function.
}
\seealso{\code{\link{rsctrl}} }
\keyword{misc}
\name{RSmpl}
\alias{RSmpl}
\alias{RSmplext}
\title{Sample Objects}
\description{
The objects of class \code{RSmpl} and \code{RSmplext} contain
the original input matrix, the generated (encoded) random matrices, and
some information about the sampling process.
}
\value{
A list of class \code{RSmpl} or \code{RSmplext} with components
\item{n}{number of rows of the input matrix}
\item{k}{number of columns of the input matrix}
\item{inpmat}{the input matrix}
\item{tfixed}{\code{TRUE}, if diagonals of \code{inpmat} are fixed}
\item{burn_in}{length of the burn in process}
\item{n_eff}{number of generated matrices (effective matrices)}
\item{step}{controls the number number of void matrices generated in the the burn in
process and when effective matrices are generated (see note
in \code{\link{rsctrl}}). }
\item{seed}{starting value for the random number generator}
\item{n_tot}{number of matrices in \code{outvec}.}
\item{outvec}{vector of encoded random matrices}
\item{ier}{error code (see below)}
}
\note{By default, all generated matrices plus
the original matrix (in position 1) are contained in
\code{outvec}, thus \code{n_tot = n_eff + 1}. If
the original matrix is not in \code{outvec} then
\code{n_tot = n_eff}.\cr\cr
If \code{ier} is 0, no error was detected. Otherwise use
the error function \code{rserror(ier)} to obtain some informations.\cr\cr
For saving and loading objects
of class \code{RSmpl} or \code{RSmplext}
see the example in \code{\link{rsextrobj}}.
}
\section{Generation}{
These classes of objects are returned from
\code{rsampler} and \code{rsextrobj}.
}
\section{Methods}{
Both classes have methods for the generic \code{summary}
function.
}
\seealso{\code{\link{rsampler}}, \code{\link{rsextrobj}} }
\keyword{misc}
\name{RaschSampler-package}
\alias{RaschSampler}
\docType{package}
\title{Rasch Sampler Package}
\description{
The package implements an MCMC algorithm for sampling of
binary matrices with fixed margins complying to the Rasch model.
Its stationary distribution is uniform. The algorithm also allows
for square matrices with fixed diagonal.\cr
Parameter estimates in the Rasch model only depend on the marginal totals of
the data matrix that is used for the estimation. From this it follows that, if the
model is valid, all binary matrices with the same marginals as the observed one
are equally likely. For any statistic of the data matrix, one can approximate
the null distribution, i.e., the distribution if the Rasch model is valid, by taking
a random sample from the collection of equally likely data matrices and constructing
the observed distribution of the statistic.
One can then simply determine the exceedence probability of the statistic in the
observed sample, and thus construct a non-parametric test of the Rasch model.
The main purpose of this package is the implementation of a methodology to build nonparametric
tests for the Rasch model. \cr
In the context of social network theories, where the structure of binary asymmetric
relations is studied, for example,
person \eqn{a} esteems person \eqn{b}, which correponds to a 1 in cell \eqn{(a, b)}
of the associated adjacency matrix. If one wants to study
the distribution of a statistic defined on the adjacency matrix and conditional
on the marginal totals, one has to exclude the diagonal cells from consideration, i.e.,
by keeping the diagonal cells fixed at an arbitrary value. The \code{RaschSampler} package
has implemented an appropriate option, thus it can be also used for sampling random adjacency
matrices with given marginal totals.
}
\details{
\tabular{ll}{%
Package:\tab RaschSampler\cr
Type: \tab Package\cr
Version:\tab 0.8-8\cr
Date: \tab 2015-07-23\cr
License:\tab GNU GPL 2, June 1991\cr%
}
The user has to supply a binary input matrix. After defining appropriate control
parameters using \code{\link{rsctrl}} the sampling function \code{\link{rsampler}}
may be called to obtain an object of class \code{\link{RSmpl}} which contains the
generated random matrices in encoded form. After defining an appropriate function
to operate on a binary matrix (e.g., calculate a statistic such as \code{\link{phi.range}})
the application of this function to the sampled matrices is performed
using \code{\link{rstats}}. Prior to applying the user defined function, \code{\link{rstats}}
decodes the matrices packed in the \code{\link{RSmpl}}-object.\cr
The package also defines a utility function \code{\link{rsextrobj}} for extracting certains parts from
the \code{\link{RSmpl}}-object resulting in an object of class \code{\link{RSmplext}}.
Both types of objects can be saved and reloaded for later use.\cr
Summary methods are available to print information on these objects, as well as
on the control object \code{\link{RSctr}} which is obtained from using
\code{\link{rsctrl}} containing the specification for the sampling routine.
}
\author{Reinhold Hatzinger, Patrick Mair, Norman D. Verhelst
Maintainer: <mair@fas.harvard.edu>
}
\references{
Verhelst, N. D. (2008) An Efficient MCMC Algorithm to Sample Binary Matrices with Fixed Marginals. Psychometrika, Volume 73, Number 4\cr
Verhelst, N. D., Hatzinger, R., and Mair, P. (2007) The Rasch Sampler. Journal of Statistical Software, Vol. 20, Issue 4, Feb 2007
}
\note{The current implementation allows for data matrices up to 4096 rows and 128 columns.
This can be changed by setting \code{nmax} and \code{kmax} in \code{RaschSampler.f90}
to values which are a power of 2. These values should also be changed in \code{rserror.R}.
For convenience, we reuse the Fortran code of package version 0.8-1 which cicumvents the
compiler bug in Linux distributions of GCC 4.3. In case of compilation errors (due to a bug in Linux distributions of GCC 4.3) please use
\code{RaschSampler.f90} from package version 0.8-1 and change \code{nmax} and \code{kmax}
accordingly (or use GCC 4.4).}
\keyword{package}
\name{phi.range}
\alias{phi.range}
\title{ Example User Function }
\description{
Calculates the \eqn{R_\phi} statistic, i.e., the range of
the inter-column correlations (\eqn{\phi}-coefficients) for
a binary matrix.
}
\usage{
phi.range(mat)
}
\arguments{
\item{mat}{ a binary matrix }
}
\value{
the range of the inter-column correlations
}
\examples{
ctr <- rsctrl(burn_in = 10, n_eff = 5, step=10, seed = 123, tfixed = FALSE)
mat <- matrix(sample(c(0,1), 50, replace = TRUE), nr = 10)
rso <- rsampler(mat, ctr)
rso_st <- rstats(rso,phi.range)
print(unlist(rso_st))
}
\keyword{misc}
\name{rsampler}
\alias{rsampler}
\title{Sampling Binary Matrices}
\description{
The function implements an MCMC algorithm for sampling of binary
matrices with fixed margins complying to the Rasch model.
Its stationary distribution is
uniform. The algorithm also allows for square matrices with
fixed diagonal.
}
\usage{
rsampler(inpmat, controls = rsctrl())
}
\arguments{
\item{inpmat}{ A binary (data) matrix with \eqn{n} rows and \eqn{k} columns.}
\item{controls}{An object of class \code{\link{RSctr}}. If not specified, the default
parameters as returned by function \code{\link{rsctrl}} are
used.}
}
\details{
\code{rsampler} is a wrapper function for a Fortran routine to generate binary random matrices based
on an input matrix.
On output the generated binary matrices are integer encoded. For further
processing of the generated matrices use the function \code{\link{rstats}}.
}
\value{
A list of class \code{\link{RSmpl}} with components
\item{n}{number of rows of the input matrix}
\item{k}{number of columns of the input matrix}
\item{inpmat}{the input matrix}
\item{tfixed}{\code{TRUE}, if diagonals of \code{inpmat} are fixed}
\item{burn_in}{length of the burn in process}
\item{n_eff}{number of generated matrices (effective matrices)}
\item{step}{controls the number number of void matrices generated in the the burn in
process and when effective matrices are generated (see note
in \code{\link{rsctrl}}). }
\item{seed}{starting value for the random number generator}
\item{n_tot}{number of matrices in \code{outvec}, \code{n_tot = n_eff + 1}}
\item{outvec}{vector of encoded random matrices}
\item{ier}{error code}
}
\references{Verhelst, N. D. (2008) An Efficient MCMC Algorithm to Sample Binary
Matrices with Fixed Marginals. Psychometrika, Volume 73, Number 4}
\author{Reinhold Hatzinger, Norman Verhelst}
\note{
An element of \code{outvec} is a four byte (or 32 bits) integer. The matrices
to be output are stored bitwise (some bits
are unused, since a integer is used for every row of a matrix. So
the number of integers per row needed equals (k+31)/32 (integer division),
which is one to four in the present implementation since the number of columns
and rows must not exceed 128 and 4096, respectively.\cr
The summary method (\code{\link{summary.RSmpl}}) prints
information on the content of the output object.
}
\seealso{\code{\link{rsctrl}}, \code{\link{rstats}} }
\examples{
data(xmpl)
ctr<-rsctrl(burn_in=10, n_eff=5, step=10, seed=0, tfixed=FALSE)
res<-rsampler(xmpl,ctr)
summary(res)
}
\keyword{misc}
\name{rsctrl}
\alias{rsctrl}
\title{Controls for the Sampling Function}
\description{
Various parameters that control aspects of
the random generation of binary matrices.
}
\usage{
rsctrl(burn_in = 100, n_eff = 100, step = 16, seed = 0, tfixed = FALSE)
}
\arguments{
\item{burn_in}{
the number of sampled matrices to
come close to a stationary distribution.
The default is \code{burn_in = 100}.
(The actual number is \code{2 * burn_in * step}.)
}
\item{n_eff}{
the number of effective matrices, i.e.,
the number of matrices
to be generated by the sampling function \code{\link{rsampler}}.
\code{n_eff} must be positive and not larger than 8191
(2\eqn{\mbox{\textasciicircum}}{^}13-1).
The default is \code{n_eff = 100}.
}
\item{step}{controls the number number of void matrices generated in the the burn in
process and when effective matrices are generated (see note
below). The default is \code{step = 16}. }
\item{seed}{
is the indicator for the seed of the random number generator.
Its value must be in the range 0 and 2147483646 (2**31-2).
If the value of seed equals zero, a seed is generated
by the sampling function \code{\link{rsampler}}
(dependent on the system's clock) and its value is returned
in the output. If seed is not equal to zero, its
value is used as the seed of the random number generator.
In that case its value is unaltered at output.
The default is \code{seed = 0}.
}
\item{tfixed}{logical, -- specifies if in case of a quadratic input
matrix the diagonal is considered fixed (see note below).
The default is \code{tfixed = FALSE}.
}
}
\value{
A list of class \code{RSctr} with components
\code{burn_in}, \code{n_eff}, \code{step},
\code{seed}, \code{tfixed}.,
}
\note{
If one of the components is incorrectly specified
the error function \code{rserror}
is called and some informations are printed. The ouput object
will not be defined.\cr\cr
The specification of \code{step} controls the sampling algorithm as follows:
If , e.g., \code{burn_in = 10}, \code{n_eff = 5}, and \code{step = 2},
then during the burn in period \code{step * burn_in = 2 * 10}
matrices are generated. After that, \code{n_eff * step = 5 * 2} matrices
are generated and every second matrix of these last ten is returned from
\code{link{rsampler}}.\cr\cr
\code{tfixed} has no effect if the input matrix is not quadratic,
i.e., all matrix elements are considered free (unrestricted).
If the input matrix is quadratic, and \code{tfixed = TRUE},
the main diagonal of the matrix is considered as fixed.
On return from \code{link{rsampler}} all diagonal elements
of the generated matrices are set to zero.
This specification applies, e.g.,
to analyzing square incidence matrices
representing binary asymmetric relation
in social network theory.\cr\cr
The summary method (\code{\link{summary.RSctr}}) prints
the current definitions. \cr
}
\seealso{\code{\link{rsampler}} }
\examples{
ctr <- rsctrl(n_eff = 1, seed = 987654321) # specify new controls
summary(ctr)
\dontrun{
ctr2 <- rsctrl(step = -3, n_eff = 10000) # incorrect specifications
}
}
\keyword{misc}
\name{rsextrmat}
\alias{rsextrmat}
\title{Extracting a Matrix}
\description{
Convenience function to extract a matrix.
}
\usage{
rsextrmat(RSobj, mat.no = 1)
}
\arguments{
\item{RSobj}{object as obtained from using \code{rsampler} or \code{rsextrobj}}
\item{mat.no}{number of the matrix to extract from the sample object.}
}
\value{
One of the matrices (either the original or a sampled matrix)
}
\seealso{\code{\link{rsampler}}, \code{\link{rsextrobj}},\code{\link{rstats}},}
\examples{
ctr <- rsctrl(burn_in = 10, n_eff = 3, step=10, seed = 0, tfixed = FALSE)
mat <- matrix(sample(c(0,1), 50, replace = TRUE), nr = 10)
all_m <- rsampler(mat, ctr)
summary(all_m)
# extract the third sampled matrix (here the fourth)
third_m <- rsextrmat(all_m, 4)
head(third_m)
}
\keyword{misc}
\name{rsextrobj}
\alias{rsextrobj}
\title{Extracting Encoded Sample Matrices}
\description{
Utility function to extract some of the generated matrices, still in encoded form.
}
\usage{
rsextrobj(RSobj, start = 1, end = 8192)
}
\arguments{
\item{RSobj}{object as obtained from using \code{rsampler}}
\item{start}{number of the matrix to start with. When specifying 1
(the default value) the original input matrix is
included in the output object.
}
\item{end}{last matrix to be extracted. If \code{end}
is not specified, all matrices from \code{RSobj}
are extracted (the maximal value is 8192, see
\code{rsctrl}). If \code{end} is larger than
the number of matrices stored in \code{RSobj},
\code{end} is set to the highest possible value
(i.e., \code{n_tot}).
}
}
\value{
A list of class \code{\link{RSmpl}} with components
\item{n}{number of rows of the input matrix}
\item{k}{number of columns of the input matrix}
\item{inpmat}{the input matrix}
\item{tfixed}{\code{TRUE}, if diagonals of \code{inpmat} are fixed}
\item{burn_in}{length of the burn in process}
\item{n_eff}{number of generated matrices (effective matrices)}
\item{step}{controls the number number of void matrices generated in the burn in
process and when effective matrices are generated (see note
in \code{\link{rsctrl}}). }
\item{seed}{starting value for the random number generator}
\item{n_tot}{number of matrices in \code{outvec}.}
\item{outvec}{vector of encoded random matrices}
\item{ier}{error code}
}
\note{By default, all generated matrices plus
the original matrix (in position 1) are contained in
\code{outvec}, thus \code{n_tot = n_eff + 1}. If
the original matrix is not in \code{outvec} then
\code{n_tot = n_eff}.\cr
For saving and loading objects
of class \code{RSobj} see the example below.
For extracting a decoded (directly usable) matrix use \code{\link{rsextrmat}}.
}
\seealso{\code{\link{rsampler}}, \code{\link{rsextrmat}} }
\examples{
ctr <- rsctrl(burn_in = 10, n_eff = 3, step=10, seed = 0, tfixed = FALSE)
mat <- matrix(sample(c(0,1), 50, replace = TRUE), nr = 10)
all_m <- rsampler(mat, ctr)
summary(all_m)
some_m <- rsextrobj(all_m, 1, 2)
summary(some_m)
\dontrun{
save(some_m, file = "some.RSobj")
some_new <- load("some.RSobj")
summary(some_new)
}
}
\keyword{misc}
\name{rstats}
\alias{rstats}
\title{Calculating Statistics for the Sampled Matrices}
\description{
This function is used to calculate user defined statistics for the
(original and) sampled matrices. A user defined function has to
be provided.
}
\usage{
rstats(RSobj, userfunc, ...)
}
\arguments{
\item{RSobj}{object as obtained from using \code{\link{rsampler}}
or \code{\link{rsextrobj}} }
\item{userfunc}{a user defined function which performs operations
on the (original and) sampled matrices. The first argument in the definition
of the user function must be an object of type matrix.}
\item{...}{further arguments, that are passed to the user function}
}
\value{
A list of objects as specified in the user supplied function
}
\note{The encoded matrices that are contained in the
input object \code{RSobj} are decoded and passed to the user function in turn.
If \code{RSobj} is not an object obtained from either \code{\link{rsampler}}
or \code{\link{rsextrobj}} or
no user function is specified an error message is printed.
A simple user function, \code{\link{phi.range}}, is included in
the RaschSampler package for demonstration purposes.\cr
\code{rstats} can be used to obtain the 0/1 values for any
of the sampled matrices (see second example below). Please note,
that the output from the user function is stored in a list where
the number of components corresponds to the number of matrices passed
to the user function (see third example).
}
\seealso{\code{\link{rsampler}}, \code{\link{rsextrobj}} }
\examples{
ctr <- rsctrl(burn_in = 10, n_eff = 5, step=10, seed = 12345678, tfixed = FALSE)
mat <- matrix(sample(c(0,1), 50, replace = TRUE), nr = 10)
rso <- rsampler(mat, ctr)
rso_st <- rstats(rso,phi.range)
unlist(rso_st)
# extract the third generated matrix
# (here, the first is the input matrix)
# and decode it into rsmat
rso2 <- rsextrobj(rso,4,4)
summary(rso2)
rsmat <- rstats(rso2, function(x) matrix(x, nr = rso2$n))
print(rsmat[[1]])
# extract only the first r rows of the third generated matrix
mat<-function(x, nr = nr, r = 3){
m <- matrix(x, nr = nr)
m[1:r,]
}
rsmat2 <- rstats(rso2, mat, nr=rso$n, r = 3)
print(rsmat2[[1]])
# apply a user function to the decoded object
print(phi.range(rsmat[[1]]))
}
\keyword{misc}
\name{summary.RSctr}
\alias{summary.RSctr}
\title{Summary Method for Control Objects}
\description{
Prints the current definitions for the sampling function.
}
\usage{
\method{summary}{RSctr}(object, ...)
}
\arguments{
\item{object}{ object of class \code{RSctr} as obtained from \code{\link{rsctrl}} }
\item{\dots}{ potential further arguments (ignored) }
}
\seealso{ \code{\link{rsctrl}} }
\examples{
ctr <- rsctrl(n_eff = 1, seed = 123123123) # specify controls
summary(ctr)
}
\keyword{misc}
\name{summary.RSmpl}
\alias{summary.RSmpl}
\alias{summary.RSmplext}
\title{Summary Methods for Sample Objects}
\description{
Prints a summary list for sample objects of class \code{\link{RSmpl}}
and \code{\link{RSmplext}}.
}
\usage{
\method{summary}{RSmpl}(object, ...)
\method{summary}{RSmplext}(object, ...)
}
\arguments{
\item{object}{object as obtained from \code{rsampler} or \code{rsextrobj} }
\item{\dots}{ potential further arguments (ignored) }
}
\details{
Describes the status of an sample object.
}
\seealso{\code{\link{rsampler}}, \code{\link{rsextrobj}} }
\examples{
ctr <- rsctrl(burn_in = 10, n_eff = 3, step=10, seed = 0, tfixed = FALSE)
mat <- matrix(sample(c(0,1), 50, replace = TRUE), nr = 10)
all_m <- rsampler(mat, ctr)
summary(all_m)
some_m <- rsextrobj(all_m, 1, 2)
summary(some_m)
}
\keyword{misc}
\name{xmpl}
\alias{xmpl}
\alias{xmplbig}
\docType{data}
\title{Example Data}
\description{
Ficitious data sets - matrices with binary responses
}
\usage{data(xmpl)}
\format{
The format of \code{xmpl} is:\cr
300 rows (referring to subjects) \cr
30 columns (referring to items) \cr
The format of \code{xmplbig} is:\cr
4096 rows (referring to subjects) \cr
128 columns (referring to items) \cr
\code{xmplbig} has the maximum dimensions that the RaschSampler package
can handle currently.
}
\examples{
data(xmpl)
print(head(xmpl))
}
\keyword{datasets}
This diff is collapsed.