Package 'memisc'

Description

Annotations, that is, objects of class "annotation", are character vectors with all their elements named. Only one method is defined for this subclass of character vectors, a method for show, that shows the annotation in a nicely formatted way. Annotations of an object can be obtained via the function annotation(x) and can be set via annotation(x)<-value.

Elements of an annotation with names "description" and "wording" have a special meaning. The first kind can be obtained and set via description(x) and description(x)<-value, the second kind can be obtained via wording(x) and wording(x)<-value. "description" elements are used in way the "variable labels" are used in SPSS and Stata. "wording" elements of annotation objects are meant to contain the question wording of a questionnaire item represented by an "item" objects. These elements of annotations are treated in a special way in the output of the coodbook function.

Usage

annotation(x)
## S4 method for signature 'ANY'
annotation(x)
## S4 method for signature 'item'
annotation(x)
## S4 method for signature 'data.set'
annotation(x)
annotation(x)<-value
## S4 replacement method for signature 'ANY,character'
annotation(x)<-value
## S4 replacement method for signature 'ANY,annotation'
annotation(x)<-value
## S4 replacement method for signature 'item,annotation'
annotation(x)<-value
## S4 replacement method for signature 'vector,annotation'
annotation(x)<-value

description(x)
description(x)<-value

wording(x)
wording(x)<-value

## S4 method for signature 'data.set'
description(x)
## S4 method for signature 'importer'
description(x)
## S4 method for signature 'data.frame'
description(x)
## S4 method for signature 'tbl_df'
description(x)

Arguments

Value

annotation(x) returns an object of class "annotation", which is a named character. description(x) and wording(x) each usually return a character string. If description(x) is applied to a data.set or an importer object, however, a character vector is returned, which is named after the variables in the data set or the external file.

Examples

vote <- sample(c(1,2,3,8,9,97,99),size=30,replace=TRUE)
labels(vote) <- c(Conservatives         =  1,
                    Labour                =  2,
                    "Liberal Democrats"   =  3,
                    "Don't know"          =  8,
                    "Answer refused"      =  9,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99
                    )
missing.values(vote) <- c(97,99)
description(vote) <- "Vote intention"
wording(vote) <- "If a general election would take place next tuesday,
                    the candidate of which party would you vote for?"
annotation(vote)
annotation(vote)["Remark"] <- "This is not a real questionnaire item, of course ..."
codebook(vote)

Description

applyTemplate is called internally by mtable to format coefficients and summary statistics.

Usage

applyTemplate(x,template,float.style=getOption("float.style"),
                      digits=min(3,getOption("digits")),
                      signif.symbols=getOption("signif.symbols"))

Arguments

Details

Character vectors that are used as templates may be arbitrary. However, certain character sequences may form template expressions. A template expression is of the form ($<POS>:<Format spec>), where "($" indicates the start of a template expression, "<POS>" stands for either an index or name that selects an element from x and "<Format spec>" stands for a format specifier. It may contain an letter indicating the style in which the vector element selected by <POS> will be formatted by formatC, it may contain a number as the number of significant digits, a "#" indicating that the number of signifcant digits will be at most that given by getOption("digits"), or * that means that the value will be formatted as a significance symbol.

Value

applyTemplate returns a character vector in which template expressions in template are substituted by formatted values from x. If template is an array then the return value is also an array of the same shape.

Examples

applyTemplate(c(a=.0000000000000304,b=3),template=c("($1:g7#)($a:*)"," (($1:f2)) "))
applyTemplate(c(a=.0000000000000304,b=3),template=c("($a:g7#)($a:*)"," (($b:f2)) "))

Description

The as.array for data frames takes all factors in a data frame and uses them to define the dimensions of the resulting array, and fills the array with the values of the remaining numeric variables.

Currently, the data frame must contain all combinations of factor levels.

Usage

## S4 method for signature 'data.frame'
as.array(x,data.name=NULL,...)

Arguments

Value

An array

Examples

BerkeleyAdmissions <- to.data.frame(UCBAdmissions)
BerkeleyAdmissions
as.array(BerkeleyAdmissions,data.name="Admit")
try(as.array(BerkeleyAdmissions[-1,],data.name="Admit"))

Description

as.symbols and syms are functions potentially useful in connection with foreach and xapply. as.symbols produces a list of symbols from a character vector, while syms returns a list of symbols from symbols given as arguments, but it can be used to construct patterns of symbols.

Usage

as.symbols(x)
syms(...,paste=FALSE,sep="")

Arguments

Value

A list of language symbols (results of as.symbol - not graphical symbols!).

Examples

as.symbols(letters[1:8])
  syms("a",1:3,paste=TRUE)

  sapply(syms("a",1:3,paste=TRUE),typeof)

Description

The %if% operator allows to assign values to a variable only if a condition is met i.e. results in TRUE. It is supposed to be used similar to the replace ... if construct in Stata.

Usage

expr %if% condition
# For example
# (variable <- value) %if% (other_variable == 0)

Arguments

Details

The 'value' that is assigned to the variable in expr should either be a scalar, a vector with as many elements as the condition vector has, or as many elements as the number of elements in the condition vector that are equal (or evaluate to) TRUE.

Examples

(test_var <- 1) %if% (1:7 > 3)

test_var

(test_var <- 2) %if% (1:7 <= 3)
test_var

(test_var <- 100*test_var) %if% (1:7%%2==0)
test_var

# This creates a warning about non-matching lengths.
(test_var <- 500:501) %if% (1:7 <= 3)
test_var

(test_var <- 501:503) %if% (1:7 <= 3)
test_var

(test_var <- 401:407) %if% (1:7 <= 3)
test_var

Description

The operator %#% can be used to attach a description annotation to an object. %##% can be used to attach a character vector of annotations to an object. %@% returns the attribute with the name given as second argument. With %@% it is also possible to assign attributes.

Usage

x %#% descr
  x %##% annot
  x %@% nm
  x %@% nm <- value

Arguments

Examples

test1 <- 1 %#% "One"
# This is equivalent to:
# test <- 1
# description(test) <- "One"
description(test1)
# Results in "One"

# Not that it makes sense, but ...
test2 <- 2 %##% c(
                    Precedessor = 0,
                    Successor   = 2
                 )
# This is equivalent to:
# test2 <- 2
# annotation(test2) <- c(
#                    Precedessor = 0,
#                    Successor   = 2
#                 )
annotation(test2)

# The following examples are equivalent to
# attr(test2,"annotation")
test2 %@% annotation

test2 %@% "annotation"

test2 %@% another.attribute <- 42
# This is equivalent to attr(test2,"another.attribute") <- 42

attributes(test2)

Description

The function By evaluates an expression within subsets of a data frame, where the subsets are defined by a formula.

Usage

By(formula,expr,data=parent.frame())

Arguments

Value

A list of class "by", giving the results for each combination of values of variables in formula.

Examples

berkeley <- Aggregate(Table(Admit,Freq)~.,data=UCBAdmissions)
(Bres <- By(~Dept,glm(cbind(Admitted,Rejected)~Gender,family="binomial"),data=berkeley))
# The results all have 'data' components
str(Bres[[1]]$data)

attach(berkeley)
(Bres <- By(~Dept,glm(cbind(Admitted,Rejected)~Gender,family="binomial")))
detach(berkeley)

Description

cases allows to distinguish several cases defined logical conditions. It can be used to code these cases into a vector. The function can be considered as a multi-condition generalization of ifelse.

Usage

cases(...,check.xor=c("warn","stop","ignore"),
      .default=NA,.complete=FALSE,
      check.na=c("warn","stop","ignore"),
      na.rm=TRUE)

Arguments

Details

There are two distinct ways to use this function. Either the function can be used to construct a factor that represents several logical cases or it can be used to conditionally evaluate an expression in a manner similar to ifelse.

For the first use, the ... arguments have to be a series of logical expressions. cases then returns a factor with as many levels as logical expressions given as ... arguments. The resulting factor will attain its first level if the first condition is TRUE, otherwise it will attain its second level if the second condition is TRUE, etc. The levels will be named after the conditions or, if name tags are attached to the logical expressions, after the tags of the expressions. Not that the logical expressions all need to evaluate to logical vectors of the same length, otherwise an error condition is raised. If .complete is TRUE then an additional factor level is created for the conditions not satisfied for any of the cases.

For the second use, the ... arguments have to be a series of assignment expression of the type <expression> <- <logical expression> or <logical expression> -> <expression>. For cases in which the first logical expression is TRUE, the result of first expression that appears on the other side of the assignment operator become elements of the vector returned by cases, for cases in which the second logical expression is TRUE, the result of the second expression that appears on the other side of the assignment operator become elements of the vector returned by cases, etc. For cases that do not satisfy any of the given conditions the value of the .default argument is used. Note that the logical expressions also here all need to evaluate to logical vectors of the same length. The expressions on the other side of the assignment operator should also be either vectors of the same length and mode or should scalars of the same mode, otherwise unpredictable results may occur.

Value

If it is called with logical expressions as ... arguments, cases returns a factor, if it is called with assignment expressions the function returns a vector with the same mode as the results of the "assigned" expressions and with the same length as the logical conditions.

Examples

# Examples of the first kind of usage of the function
#
df <- data.frame(x = rnorm(n=20), y = rnorm(n=20))
df <- df[do.call(order,df),]
(df <- within(df,{
  x1=cases(x>0,x<=0)
  y1=cases(y>0,y<=0)
  z1=cases(
    "Condition 1"=x<0,
    "Condition 2"=y<0,# only applies if x >= 0
    "Condition 3"=TRUE
    )
  z2=cases(x<0,(x>=0 & y <0), (x>=0 & y >=0))
  }))
xtabs(~x1+y1,data=df)
dd <- with(df,
  try(cases(x<0,
            x>=0,
            x>1,
            check.xor=TRUE)# let's be fussy
            )
  )
dd <- with(df,
  try(cases(x<0,x>=0,x>1))
  )
genTable(range(x)~dd,data=df)

# An example of the second kind of usage of the function:
# A construction of a non-smooth function
#
fun <- function(x)
  cases(
    x==0      -> 1,
    abs(x)> 1 -> abs(x),
    abs(x)<=1 -> x^2
  )
x <- seq(from=-2,to=2,length=101)
plot(fun(x)~x)

# Demo of the new .default and .complete arguments
x <- seq(from=-2,to=2)
cases(a = x < -1,
      b = x > 1,
      .complete = TRUE)
cases(x < -1,
      x > 1,
      .complete = TRUE)
cases(1 <- x < -1,
      3 <- x > 1,
      .default = 2)

threshhold <- 5
d <- c(1:10, NaN)

d1 <- cases(
  d > threshhold -> 1,
  d <= threshhold -> 2
)

d2 <- cases(
  is.na(d) -> 0,
  d > threshhold -> 1,
  d <= threshhold -> 2
)

# Leads to missing values because some of the conditions result in missing
# even though they could be 'captured'
d3 <- cases(
  is.na(d) -> 0,
  d > threshhold -> 1,
  d <= threshhold -> 2,
  na.rm=FALSE
)

d4 <- cases(
  is.na(d) -> 0,
  d > threshhold +2 -> 1,
  d <= threshhold -> 2,
  na.rm=FALSE
)

cbind(d,d1,d2,d3,d4)

cases(
  d > threshhold,
  d <= threshhold
)

cases(
  is.na(d),
  d > threshhold,
  d <= threshhold
)

cases(
  d > threshhold,
  d <= threshhold,
  .complete=TRUE
)

cases(
  d > threshhold + 2,
  d <= threshhold,
  .complete=TRUE
)

Description

This function uses the base package function chartr to translate characters in variable descriptions (a.k.a variable labels) and value labels of item, data.set, and importer objects.

It will be useful when the encoding of an important data set cannot be fully identified or if the encoding in the data file is incorrect or unknown.

Usage

charTrans(x, old = "", new = "", ...)
## S3 method for class 'annotation'
charTrans(x, old = "", new = "", ...)
## S3 method for class 'data.set'
charTrans(x, old = "", new = "", ...)
## S3 method for class 'importer'
charTrans(x, old = "", new = "", ...)
## S3 method for class 'item'
charTrans(x, old = "", new = "", ...)
## S3 method for class 'value.labels'
charTrans(x, old = "", new = "", ...)

Arguments

Value

charTrans returns a copy of its first argument with character-translated character data or attributes.

See Also

chartr

Examples

## Not run: 
# Locate an SPSS 'portable' file and get info on variables, their labels 
S2601.POR <- spss.portable.file("POR-Files/S2601.POR", encoded = "cp850")
# 'ß' appears to be correctly coded, but 'ä', 'ö', 'ü' are not, so we need to
# to some fine-tuning
S2601.POR <- charTrans(S2601.POR, old="{|}\r", new="äöü ")
# Now labels etc. are correctly encoded.
codebook(S2601.POR)

## End(Not run)

Description

coarsen can be used to obtain a factor from a vector, similar to cut, but with less technical and more "aesthetic" labels of the factor levels.

Usage

coarsen(x,...)
## S3 method for class 'numeric'
coarsen(x,
        n=5,
        pretty=TRUE,
        quantiles=!pretty,
        breaks=NULL,
        brackets=FALSE,
        sep=if(brackets)";"else if(quantiles) "-" else " - ",
        left="[",
        right="]",
        range=FALSE,
        labels=NULL,
        ...)

Arguments

Examples

x <- rnorm(200)

table(coarsen(x))

table(coarsen(x,quantiles=TRUE))

table(coarsen(x,brackets=TRUE))

table(coarsen(x,breaks=c(-1,0,1)))

table(coarsen(x,breaks=c(-1,0,1),
              range=TRUE,labels=letters[1:4]))

Description

Function codebook collects documentation about an item, or the items in a data set or external data file. It returns an object that, when shown, print this documentation in a nicely formatted way.

Usage

codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'item'
codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'atomic'
codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'factor'
codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'data.set'
codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'importer'
codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'data.frame'
codebook(x, weights = NULL, unweighted = TRUE, ...)
## S4 method for signature 'tbl_df'
codebook(x, weights = NULL, unweighted = TRUE, ...)

Arguments

Value

An object of class "codebook", for which a show method exists that produces a nicely formatted output.

Examples

Data <- data.set(
          vote = sample(c(1,2,3,8,9,97,99),size=300,replace=TRUE),
          region = sample(c(rep(1,3),rep(2,2),3,99),size=300,replace=TRUE),
          income = exp(rnorm(300,sd=.7))*2000
          )

Data <- within(Data,{
  description(vote) <- "Vote intention"
  description(region) <- "Region of residence"
  description(income) <- "Household income"
  wording(vote) <- "If a general election would take place next tuesday,
                    the candidate of which party would you vote for?"
  wording(income) <- "All things taken into account, how much do all
                    household members earn in sum?"
  foreach(x=c(vote,region),{
    measurement(x) <- "nominal"
    })
  measurement(income) <- "ratio"
  labels(vote) <- c(
                    Conservatives         =  1,
                    Labour                =  2,
                    "Liberal Democrats"   =  3,
                    "Don't know"          =  8,
                    "Answer refused"      =  9,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99)
  labels(region) <- c(
                    England               =  1,
                    Scotland              =  2,
                    Wales                 =  3,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99)
  foreach(x=c(vote,region,income),{
    annotation(x)["Remark"] <- "This is not a real survey item, of course ..."
    })
  missing.values(vote) <- c(8,9,97,99)
  missing.values(region) <- c(97,99)
})

description(Data)

codebook(Data)

codebook(Data)$vote
codebook(Data)[2]

codebook(Data[2])
 
DataFr <- as.data.frame(Data)
DataHv <- as_haven(Data,user_na=TRUE)

codebook(DataFr)
codebook(DataHv)

   
## Not run: 
Write(description(Data),
           file="Data-desc.txt")
Write(codebook(Data),
           file="Data-cdbk.txt")
  
## End(Not run)

Description

The function codeplan() creates a data frame that describes the structure of an item list (a data.set object or an importer object), so that this structure can be stored and and recovered. The resulting data frame has a particular print method that delimits the output to one line per variable.

With setCodeplan an item list structure (as returned by codeplan()) can be applied to a data frame or data set. It is also possible to use an assignment like codeplan(x) <- value to a similar effect.

Usage

codeplan(x)
## S4 method for signature 'item.list'
codeplan(x)
## S4 method for signature 'item'
codeplan(x)
setCodeplan(x,value)
## S4 method for signature 'data.frame,codeplan'
setCodeplan(x,value)
## S4 method for signature 'data.frame,NULL'
setCodeplan(x,value)
## S4 method for signature 'data.set,codeplan'
setCodeplan(x,value)
## S4 method for signature 'data.set,NULL'
setCodeplan(x,value)
## S4 method for signature 'item,codeplan'
setCodeplan(x,value)
## S4 method for signature 'item,NULL'
setCodeplan(x,value)
## S4 method for signature 'atomic,codeplan'
setCodeplan(x,value)
## S4 method for signature 'atomic,NULL'
setCodeplan(x,value)
codeplan(x) <- value
read_codeplan(filename,type)
write_codeplan(x,filename,type,pretty)

Arguments

Value

If applicable, codeplan returns a list with additional S3 class attribute "codeplan". For arguments for which the relevant information does not exist, the function returns NULL.

The list has at least one element or several elements, named after the variable in the "item.list" or "data.set" x. Each list element is a list itself with the following elements:

If codeplan(x)<-value or setCodeplan(x,value) is used and value is NULL, all the special information about annotation, labels, value filters, etc. is removed from the resulting object, which then is usually a mere atomic vector or data frame.

Examples

Data1 <- data.set(
          vote = sample(c(1,2,3,8,9,97,99),size=300,replace=TRUE),
          region = sample(c(rep(1,3),rep(2,2),3,99),size=300,replace=TRUE),
          income = exp(rnorm(300,sd=.7))*2000
          )

Data1 <- within(Data1,{
  description(vote) <- "Vote intention"
  description(region) <- "Region of residence"
  description(income) <- "Household income"
  foreach(x=c(vote,region),{
    measurement(x) <- "nominal"
    })
  measurement(income) <- "ratio"
  labels(vote) <- c(
                    Conservatives         =  1,
                    Labour                =  2,
                    "Liberal Democrats"   =  3,
                    "Don't know"          =  8,
                    "Answer refused"      =  9,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99)
  labels(region) <- c(
                    England               =  1,
                    Scotland              =  2,
                    Wales                 =  3,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99)
  foreach(x=c(vote,region,income),{
    annotation(x)["Remark"] <- "This is not a real survey item, of course ..."
    })
  missing.values(vote) <- c(8,9,97,99)
  missing.values(region) <- c(97,99)
})
cpData1 <- codeplan(Data1)

Data2 <- data.frame(
          vote = sample(c(1,2,3,8,9,97,99),size=300,replace=TRUE),
          region = sample(c(rep(1,3),rep(2,2),3,99),size=300,replace=TRUE),
          income = exp(rnorm(300,sd=.7))*2000
          )
codeplan(Data2) <- cpData1
codeplan(Data2)
codebook(Data2)

# Note the difference between 'as.data.frame' and setting
# the codeplan to NULL:
Data2df <- as.data.frame(Data2)
codeplan(Data2) <- NULL
str(Data2)
str(Data2df)
codeplan(Data2) <- NULL # Does not change anything

# Codeplans of survey items can also be inquired and manipulated:
vote <- Data1$vote
str(vote)
cp.vote <- codeplan(vote)
codeplan(vote) <- NULL
str(vote)
codeplan(vote) <- cp.vote
vote

fn.json <- paste0(tempfile(),".json")
write_codeplan(codeplan(Data1),filename=fn.json)
codeplan(Data2) <- read_codeplan(fn.json)
codeplan(Data2)

Description

collect gathers several objects into one, matching the elements or subsets of the objects by names or dimnames.

Usage

collect(...,names=NULL,inclusive=TRUE)
## Default S3 method:
collect(...,names=NULL,inclusive=TRUE)
## S3 method for class 'array'
collect(...,names=NULL,inclusive=TRUE)
## S3 method for class 'matrix'
collect(...,names=NULL,inclusive=TRUE)
## S3 method for class 'table'
collect(...,names=NULL,sourcename=".origin",fill=0)
## S3 method for class 'data.frame'
collect(...,names=NULL,inclusive=TRUE,
                                  fussy=FALSE,warn=TRUE,
                                  detailed.warnings=FALSE,use.last=FALSE,
                                  sourcename=".origin")
## S3 method for class 'data.set'
collect(...,names=NULL,inclusive=TRUE,
                                  fussy=FALSE,warn=TRUE,
                                  detailed.warnings=FALSE,use.last=FALSE,
                                  sourcename=".origin")

Arguments

Value

If x and all following ... arguments are vectors of the same mode (numeric,character, or logical) the result is a matrix with as many columns as vectors. If argument inclusive is TRUE, then the number of rows equals the number of names that appear at least once in each of the vector names and the matrix is filled with NA where necessary, otherwise the number of rows equals the number of names that are present in all vector names.

If x and all ... arguments are matrices or arrays of the same mode (numeric,character, or logical) and $n$ dimension the result will be a $n+1$ dimensional array or table. The extend of the $n+1$th dimension equals the number of matrix, array or table arguments, the extends of the lower dimension depends on the inclusive argument: either they equal to the number of dimnames that appear at least once for each given dimension and the array is filled with NA where necessary, or they equal to the number of dimnames that appear in all arguments for each given dimension.

If x and all ... arguments are data frames or data sets, the result is a data frame or data set. The number of variables of the resulting data frame or data set depends on the inclusive argument. If it is true, the number of variables equals the number of variables that appear in each of the arguments at least once and variables are filled with NA where necessary, otherwise the number of variables equals the number of variables that are present in all arguments.

Examples

x <- c(a=1,b=2)
y <- c(a=10,c=30)

x
y

collect(x,y)
collect(x,y,inclusive=FALSE)

X <- matrix(1,nrow=2,ncol=2,dimnames=list(letters[1:2],LETTERS[1:2]))
Y <- matrix(2,nrow=3,ncol=2,dimnames=list(letters[1:3],LETTERS[1:2]))
Z <- matrix(3,nrow=2,ncol=3,dimnames=list(letters[1:2],LETTERS[1:3]))

X
Y
Z

collect(X,Y,Z)
collect(X,Y,Z,inclusive=FALSE)

X <- matrix(1,nrow=2,ncol=2,dimnames=list(a=letters[1:2],b=LETTERS[1:2]))
Y <- matrix(2,nrow=3,ncol=2,dimnames=list(a=letters[1:3],c=LETTERS[1:2]))
Z <- matrix(3,nrow=2,ncol=3,dimnames=list(a=letters[1:2],c=LETTERS[1:3]))

collect(X,Y,Z)
collect(X,Y,Z,inclusive=FALSE)

df1 <- data.frame(a=rep(1,5),b=rep(1,5))
df2 <- data.frame(a=rep(2,5),b=rep(2,5),c=rep(2,5))
collect(df1,df2)
collect(df1,df2,inclusive=FALSE)

data(UCBAdmissions)
Male <- as.table(UCBAdmissions[,1,])
Female <- as.table(UCBAdmissions[,2,])
collect(Male,Female,sourcename="Gender")
collect(unclass(Male),unclass(Female))

Male1 <- as.table(UCBAdmissions[,1,-1])
Female2 <- as.table(UCBAdmissions[,2,-2])
Female3 <- as.table(UCBAdmissions[,2,-3])
collect(Male=Male1,Female=Female2,sourcename="Gender")
collect(Male=Male1,Female=Female3,sourcename="Gender")
collect(Male=Male1,Female=Female3,sourcename="Gender",fill=NA)

f1 <- gl(3,5,labels=letters[1:3])
f2 <- gl(3,6,labels=letters[1:3])
collect(f1=table(f1),f2=table(f2))

ds1 <- data.set(x = 1:3)
ds2 <- data.set(x = 4:9,
                y = 1:6)
collect(ds1,ds2)

Description

This package provides modified versions of contr.treatment and contr.sum. contr.sum gains an optional base argument, analog to the one of contr.treatment, furthermore, the base argument may be the name of a factor level.

contr returns a function that calls either contr.treatment, contr.sum, etc., according to the value given to its first argument.

The contrasts method for "item" objects returns a contrast matrix or a function to produce a contrast matrix for the factor into which the item would be coerced via as.factor or as.ordered. This matrix or function can be specified by using contrasts(x)<-value

Usage

contr(type,...)
contr.treatment(n, base=1,contrasts=TRUE)
contr.sum(n,base=NULL,contrasts=TRUE)
## S4 method for signature 'item'
contrasts(x,contrasts=TRUE,...)
## S4 replacement method for signature 'item'
contrasts(x,how.many) <- value
# These methods are defined implicitely by making 'contrasts' generic.
## S4 method for signature 'ANY'
contrasts(x,contrasts=TRUE,...)
## S4 replacement method for signature 'ANY'
contrasts(x,how.many) <- value

Arguments

Value

contr returns a funtion that calls one of contr.treatment, contr.sum,.... contr.treatment and contr.sum return contrast matrices. contrasts(x) returns the "contrasts" attribute of an object, which may be a function name, a function, a contrast matrix or NULL.

Examples

ctr.t <- contr("treatment",base="c")
ctr.t
ctr.s <- contr("sum",base="c")
ctr.h <- contr("helmert")
ctr.t(letters[1:7])
ctr.s(letters[1:7])
ctr.h(letters[1:7])

x <- factor(rep(letters[1:5],3))
contrasts(x)
x <- as.item(x)
contrasts(x)
contrasts(x) <- contr.sum(letters[1:5],base="c")
contrasts(x)
missing.values(x) <- 5
contrasts(x)
contrasts(as.factor(x))

# Obviously setting missing values after specifying
# contrast matrix breaks the contrasts.
# Using the 'contr' function, however, prevents this:

missing.values(x) <- NULL
contrasts(x) <- contr("sum",base="c")
contrasts(x)
missing.values(x) <- 5
contrasts(x)
contrasts(as.factor(x))

Description

contract() contracts data into pattern-frequency format, similar to a contatenation of table() (or xtabs) and as.data.frame(). Yet it uses much less memory if patterns are sparse, because it does not create rows for patterns that do not occur.

Usage

contract(x,...)
## S3 method for class 'data.frame'
contract(x,by=NULL, weights=NULL,name="Freq",
    force.name=FALSE,sort=FALSE,drop.na=TRUE,...)
## S3 method for class 'data.set'
contract(x,by=NULL, weights=NULL,name="Freq",
    force.name=FALSE,sort=FALSE,drop.na=TRUE,...)

Arguments

Value

If x is a data fame, the value of contract() is also a data frame. If it is a "data.set" object, the result is also a "data.set" object.

Examples

iris_ <- sample(iris,size=nrow(iris),replace=TRUE)
w <- rep(1,nrow(iris_))
contract(iris[4:5])
contract(iris[4:5],sort=TRUE)
contract(iris[4:5],weights=w,sort=TRUE)
contract(iris,by=c(Petal.Width,Species),sort=TRUE)
contract(iris,by=~Petal.Width+Species)
contract(iris,by=w~Species)

library(MASS)
contract(housing,
         by=Sat~Infl+Type+Cont,
         weights=Freq)

contract(housing,
         by=Sat~Infl+Type+Cont,
         weights=Freq,
         name="housing",force.name=TRUE
         )

Description

"data.set" objects are collections of "item" objects, with similar semantics as data frames. They are distinguished from data frames so that coercion by as.data.fame leads to a data frame that contains only vectors and factors. Nevertheless most methods for data frames are inherited by data sets, except for the method for the within generic function. For the within method for data sets, see the details section.

Thus data preparation using data sets retains all informations about item annotations, labels, missing values etc. While (mostly automatic) conversion of data sets into data frames makes the data amenable for the use of R's statistical functions.

dsView is a function that displays data sets in a similar manner as View displays data frames. (View works with data sets as well, but changes them first into data frames.)

Usage

data.set(...,row.names = NULL, check.rows = FALSE, check.names = TRUE,
    stringsAsFactors = FALSE, document = NULL)
as.data.set(x, row.names=NULL, ...)
## S4 method for signature 'list'
as.data.set(x,row.names=NULL,...)
is.data.set(x)
## S3 method for class 'data.set'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)
## S4 method for signature 'data.set'
within(data, expr, ...)

dsView(x)

## S4 method for signature 'data.set'
head(x,n=20,...)
## S4 method for signature 'data.set'
tail(x,n=20,...)

Arguments

Details

The as.data.frame method for data sets is just a copy of the method for list. Consequently, all items in the data set are coerced in accordance to their measurement setting, see as.vector,item-method and measurement.

The within method for data sets has the same effect as the within method for data frames, apart from two differences: all results of the computations are coerced into items if they have the appropriate length, otherwise, they are automatically dropped.

Currently only one method for the generic function as.data.set is defined: a method for "importer" objects.

Value

data.set and the within method for data sets returns a "data.set" object, is.data.set returns a logical value, and as.data.frame returns a data frame.

Examples

Data <- data.set(
          vote = sample(c(1,2,3,8,9,97,99),size=300,replace=TRUE),
          region = sample(c(rep(1,3),rep(2,2),3,99),size=300,replace=TRUE),
          income = exp(rnorm(300,sd=.7))*2000
          )

Data <- within(Data,{
  description(vote) <- "Vote intention"
  description(region) <- "Region of residence"
  description(income) <- "Household income"
  wording(vote) <- "If a general election would take place next tuesday,
                    the candidate of which party would you vote for?"
  wording(income) <- "All things taken into account, how much do all
                    household members earn in sum?"
  foreach(x=c(vote,region),{
    measurement(x) <- "nominal"
    })
  measurement(income) <- "ratio"
  labels(vote) <- c(
                    Conservatives         =  1,
                    Labour                =  2,
                    "Liberal Democrats"   =  3,
                    "Don't know"          =  8,
                    "Answer refused"      =  9,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99)
  labels(region) <- c(
                    England               =  1,
                    Scotland              =  2,
                    Wales                 =  3,
                    "Not applicable"      = 97,
                    "Not asked in survey" = 99)
  foreach(x=c(vote,region,income),{
    annotation(x)["Remark"] <- "This is not a real survey item, of course ..."
    })
  missing.values(vote) <- c(8,9,97,99)
  missing.values(region) <- c(97,99)

  # These to variables do not appear in the
  # the resulting data set, since they have the wrong length.
  junk1 <- 1:5
  junk2 <- matrix(5,4,4)
  
})
# Since data sets may be huge, only a
# part of them are 'show'n
Data

## Not run: 

# If we insist on seeing all, we can use 'print' instead
print(Data)

## End(Not run)

str(Data)
summary(Data)

## Not run: 
# If we want to 'View' a data set we can use 'dsView'
dsView(Data)
# Works also, but changes the data set into a data frame first:
View(Data)

## End(Not run)

Data[[1]]
Data[1,]
head(as.data.frame(Data))

EnglandData <- subset(Data,region == "England")
EnglandData

xtabs(~vote+region,data=Data)
xtabs(~vote+region,data=within(Data, vote <- include.missings(vote)))

Description

Like data frames, data.set objects have subset, unique, cbind, rbind, merge methods defined for them.

The semantics are basically the same as the methods defined for data frames in the base package, with the only difference that the return values are data.set objects. In fact, the methods described here are front-ends to the corresponding methods for data frames, which are constructed such that the "extra" information attached to variables within data.set objects, that is, to item objects.

Usage

## S3 method for class 'data.set'
subset(x, subset, select, drop = FALSE, ...)

## S4 method for signature 'data.set'
unique(x, incomparables = FALSE, ...)

## S3 method for class 'data.set'
cbind(..., deparse.level = 1)

## S3 method for class 'data.set'
rbind(..., deparse.level = 1)

## S4 method for signature 'data.set,data.set'
merge(x,y, ...)

## S4 method for signature 'data.set,data.frame'
merge(x,y, ...)

## S4 method for signature 'data.frame,data.set'
merge(x,y, ...)

Arguments

Examples

ds1 <- data.set(
      a = rep(1:3,5),
      b = rep(1:5,each=3)
  )
ds2 <- data.set(
      a = c(3:1,3,3),
      b = 1:5
  )

ds1 <- within(ds1,{
      description(a) <- "Example variable 'a'"
      description(b) <- "Example variable 'b'"
  })

ds2 <- within(ds2,{
      description(a) <- "Example variable 'a'"
      description(b) <- "Example variable 'b'"
  })

str(ds3 <- rbind(ds1,ds2))
description(ds3)

ds3 <- within(ds1,{
        c <- a
        d <- b
        description(c) <- "Copy of variable 'a'"
        description(d) <- "Copy of variable 'b'"
        rm(a,b)
    })
str(ds4 <- cbind(ds1,ds3))
description(ds4)

ds5 <- data.set(
        c = 1:3,
        d = c(1,1,2)
        )
ds5 <- within(ds5,{
      description(c) <- "Example variable 'c'"
      description(d) <- "Example variable 'd'"
  })
str(ds6 <- merge(ds1,ds5,by.x="a",by.y="c"))

# Note that the attributes of the left-hand variables
# have priority.
description(ds6)

Description

The function deduplicate_labels can be used with "item" objects, "importer" objects or "data.set" objects to deal with duplicate labels, i.e. labels that are attached to more than one code. There are several ways to de-duplicate labels: by combining values that share their label or by making labels duplicate labels distinct.

Usage

deduplicate_labels(x,...)
## S3 method for class 'item'
deduplicate_labels(x,
    method=c("combine codes",
             "prefix values",
             "postfix values"),...)
# Applicable to 'importer' objects and 'data.set' objects
## S3 method for class 'item.list'
deduplicate_labels(x,...)

Arguments

Value

The function deduplicate_labels a copy of x that has unqiue value labels.

Examples

x1 <- as.item(rep(1:5,4),
              labels=c(
                  A = 1,
                  A = 2,
                  B = 3,
                  B = 4,
                  C = 5
              ),
              annotation = c(
                  description="Yet another test"
))
              
x2 <- as.item(rep(1:4,5),
              labels=c(
                  i   = 1,
                  ii  = 2,
                  iii = 3,
                  iii = 4
                  ),
              annotation = c(
                  description="Still another test"
))

x3 <- as.item(rep(1:2,10),
              labels=c(
                  a = 1,
                  b = 2
                  ),
              annotation = c(
                  description="Still another test"
))
                            
codebook(deduplicate_labels(x1))
codebook(deduplicate_labels(x1,method="prefix"))
codebook(deduplicate_labels(x1,method="postfix"))

ds <- data.set(x1,x2,x3)
codebook(deduplicate_labels(ds))
codebook(deduplicate_labels(ds,method="prefix"))
codebook(deduplicate_labels(ds,method="postfix"))

Description

Descriptives(x) gives a vector of sample statistics for use in codebook.

Usage

Descriptives(x,...)
## S4 method for signature 'atomic'
Descriptives(x, weights = NULL, ...)
## S4 method for signature 'item.vector'
Descriptives(x, weights = NULL, ...)

Arguments

Value

A numeric vector of sample statistics, containing the range, the mean, the standard deviation, the skewness and the (excess) kurtosis.

Examples

x <- rnorm(100)
Descriptives(x)

Description

These functions provide an easy way to change the dimnames, rownames or colnames of an array.

Usage

dimrename(x, dim = 1, ..., gsub = FALSE, fixed = TRUE, warn = TRUE)
rowrename(x, ..., gsub = FALSE, fixed = TRUE, warn = TRUE)
colrename(x, ..., gsub = FALSE, fixed = TRUE, warn = TRUE)

Arguments

Details

dimrename changes the dimnames of x along dimension(s) dim according to the remaining arguments. The argument names are the old names, the values are the new names. rowrename is a shorthand for changing the rownames, colrename is a shorthand for changing the colnames of a matrix or matrix-like object.

If gsub is FALSE, argument tags are the old dimnames, the values are the new dimnames. If gsub is TRUE, arguments are substrings of the dimnames that are substituted by the argument values.

Value

Object x with changed dimnames.

Examples

m <- matrix(1,2,2)
rownames(m) <- letters[1:2]
colnames(m) <- LETTERS[1:2]
m
dimrename(m,1,a="first",b="second")
dimrename(m,1,A="first",B="second")
dimrename(m,2,"A"="first",B="second")

rowrename(m,a="first",b="second")
colrename(m,"A"="first",B="second")

# Since version 0.99.22 - the following also works:

dimrename(m,1,a=first,b=second)
dimrename(m,1,A=first,B=second)
dimrename(m,2,A=first,B=second)

Description

The function duplicated_labels can be used with "item" objects, "importer" objects or "data.set" objects to check whether items contain duplicate labels, i.e. labels that are attached to more than one code.

Usage

duplicated_labels(x)
## S3 method for class 'item'
duplicated_labels(x)
# Applicable to 'importer' objects and 'data.set' objects
## S3 method for class 'item.list'
duplicated_labels(x)

Arguments

Value

The function duplicate.labels returns a list with a class attribute, which allows pretty printing of duplicated value labels

Examples

x1 <- as.item(rep(1:5,4),
              labels=c(
                  A = 1,
                  A = 2,
                  B = 3,
                  B = 4,
                  C = 5
              ),
              annotation = c(
                  description="Yet another test"
))
              
x2 <- as.item(rep(1:4,5),
              labels=c(
                  i   = 1,
                  ii  = 2,
                  iii = 3,
                  iii = 4
                  ),
              annotation = c(
                  description="Still another test"
))

x3 <- as.item(rep(1:2,10),
              labels=c(
                  a = 1,
                  b = 2
                  ),
              annotation = c(
                  description="Still another test"
))
                            
duplicated_labels(x1)
ds <- data.set(x1,x2,x3)
duplicated_labels(ds)
codebook(ds)

nes1948.por <- unzip(system.file("anes/NES1948.ZIP",package="memisc"),
                     "NES1948.POR",exdir=tempfile())
nes1948 <- spss.portable.file(nes1948.por)
duplicated_labels(nes1948)

Description

foreach evaluates an expression given as untagged argument by substituting in variables. The expression may also contain assignments, which take effect in the caller's environment.

Usage

foreach(...,.sorted,.outer=FALSE)

Arguments

Examples

x <- 1:3
y <- -(1:3)
z <- c("Uri","Schwyz","Unterwalden")
print(x)
print(y)
print(z)
foreach(var=c(x,y,z),          # assigns names
  names(var) <- letters[1:3]   # to the elements of x, y, and z
  )
print(x)
print(y)
print(z)

ds <- data.set(
        a = c(1,2,3,2,3,8,9),
        b = c(2,8,3,2,1,8,9),
        c = c(1,3,2,1,2,8,8)
      )
print(ds)
ds <- within(ds,{ 
      description(a) <- "First item in questionnaire"
      description(b) <- "Second item in questionnaire"
      description(c) <- "Third item in questionnaire"
      
      wording(a) <- "What number do you like first?"
      wording(b) <- "What number do you like second?"
      wording(c) <- "What number do you like third?"

      foreach(x=a:c,{ # Lazy data documentation:
        labels(x) <- c(    # a,b,c get value labels in one statement
                         one = 1,
                         two = 2,
                       three = 3,
                "don't know" = 8,
         "refused to answer" = 9)
        missing.values(x) <- c(8,9)
        })
      })
      
codebook(ds)

# The colon-operator respects the order of the variables
# in the data set, if .sorted=FALSE
with(ds[c(3,1,2)],
     foreach(x=a:c,
             print(description(x))
            ))

# Since .sorted=TRUE, the colon operator creates a range 
# of alphabetically sorted variables.
with(ds[c(3,1,2)],
     foreach(x=a:c,
             print(description(x)),
             .sorted=TRUE
            ))

# The variables in reverse order
with(ds,
     foreach(x=c:a,
             print(description(x))
            ))

# The colon operator can be combined with the 
# concatenation function
with(ds,
     foreach(x=c(a:b,c,c,b:a),
             print(description(x))
            ))

# Variables can also be selected by regular expressions.
with(ds,
     foreach(x=rx("[a-b]"),
             print(description(x))
            ))

# A demonstration for '.outer=TRUE'
foreach(l=letters[1:2],
        i=1:3,
        cat(paste0(l,i,"\n")),
        .outer=TRUE)

Description

show_html is for showing objects in a convenient way in HTML format. write_html writes them in HTML format into a file. Both functions call the generic format_html for the format conversion.

Usage

show_html(x, output = NULL, ...)
write_html(x, file, ..., standalone = TRUE)

format_html(x, ...)

## S3 method for class 'data.frame'
format_html(x,
    toprule=2,midrule=1,bottomrule=2,
    split.dec=TRUE,
    row.names=TRUE,
    digits=getOption("digits"),
    format="f",
    style=df_format_stdstyle,
    margin="2ex auto", 
    ...)
    
## S3 method for class 'matrix'
format_html(x,
    toprule=2,midrule=1,bottomrule=2,
    split.dec=TRUE,
    formatC=FALSE,
    digits=getOption("digits"),
    format="f",
    style=mat_format_stdstyle,
    margin="2ex auto", 
    ...)

Arguments

Value

format_html character string with code suitable for inclusion into a HTML-file.

Description

This is the method of format_html for "codebook" objects as created by the eponymous function (see codebook)

Usage

## S3 method for class 'codebook'
format_html(x, 
    toprule = 2,
    midrule = 1,
    indent = "3ex",
    style = codebook_format_stdstyle,
    var_tag = "code", 
    varid_prefix = "", title_tag = "p",...)

Arguments

See Also

See Also as format_html, show_html, write_html.

Description

This is the method of format_html for "ftable" objects (i.e. flattened contingency tables)

Usage

## S3 method for class 'ftable'
format_html(x, 
                   show.titles = TRUE, 
                   digits = 0, 
                   format = "f", 
                   toprule = 2, midrule = 1, bottomrule = 2, 
                   split.dec = TRUE, 
                   style = ftable_format_stdstyle,
                   margin="2ex auto", 
                   ...)
## S3 method for class 'ftable_matrix'
format_html(x,
                   show.titles=TRUE,
                   digits=0,
                   format="f",
                   toprule=2,midrule=1,bottomrule=2,
                   split.dec=TRUE,
                   style = ftable_format_stdstyle,
                   margin="2ex auto", 
                   varontop,
                   varinfront,
                   grouprules=1,
                   multi_digits=NULL,
                   ...)

Arguments

See Also

See Also as format_html, show_html, write_html.

Description

format_md is for showing objects in a convenient way in Markdown format. Can be included to Rmarkdown file with the cat() function and the results='asis' code block option. The following example should be runned in a Rmd file with different output formats.

Usage

## S3 method for class 'codebook'
format_md(x, ...)
## S3 method for class 'codebookEntry'
format_md(x, name = "", add_rules = TRUE, ...)

Arguments

Value

format_md character string with code suitable for inclusion into a Markdown-file.

Examples

library(memisc)

Data1 <- data.set(
  vote = sample(c(1,2,3,8,9,97,99),size=300,replace=TRUE),
  region = sample(c(rep(1,3),rep(2,2),3,99),size=300,replace=TRUE),
  income = exp(rnorm(300,sd=.7))*2000
)

Data1 <- within(Data1,{
  description(vote) <- "Vote intention"
  description(region) <- "Region of residence"
  description(income) <- "Household income"
  foreach(x=c(vote,region),{
    measurement(x) <- "nominal"
  })
  measurement(income) <- "ratio"
  labels(vote) <- c(
    Conservatives         =  1,
    Labour                =  2,
    "Liberal Democrats"   =  3,
    "Don't know"          =  8,
    "Answer refused"      =  9,
    "Not applicable"      = 97,
    "Not asked in survey" = 99)
  labels(region) <- c(
    England               =  1,
    Scotland              =  2,
    Wales                 =  3,
    "Not applicable"      = 97,
    "Not asked in survey" = 99)
  foreach(x=c(vote,region,income),{
    annotation(x)["Remark"] <- "This is not a real survey item, of course ..."
  })
  missing.values(vote) <- c(8,9,97,99)
  missing.values(region) <- c(97,99)
})

codebook_data <- codebook(Data1)

codebook_md <- format_md(codebook_data, digits = 2)

writeLines(codebook_md)

## Not run: 
writeLines(codebook_md,con="codebook-example.md")

## End(Not run)

Description

With the method functions described here, flattened (contingency) tables can be combined into more complex objects, of class "ftable_matrix". For objects of these class format and print methods are provided

Usage

## S3 method for class 'ftable'
cbind(..., deparse.level=1)

## S3 method for class 'ftable'
rbind(..., deparse.level=1)

## S3 method for class 'ftable_matrix'
cbind(..., deparse.level=1)

## S3 method for class 'ftable_matrix'
rbind(..., deparse.level=1)

## S3 method for class 'ftable_matrix'
format(x,quote=TRUE,digits=0,format="f",...)

## S3 method for class 'ftable_matrix'
Write(x,
                            file = "",
                            quote = TRUE,
                            append = FALSE,
                            digits = 0,
                            ...)
                            
## S3 method for class 'ftable_matrix'
print(x,quote=FALSE,...)

Arguments

Value

cbind and rbind, when used with "ftable" or "ftable_matrix" objects, return objects of class "ftable_matrix".

Examples

ft1 <- ftable(Sex~Survived,Titanic)
ft2 <- ftable(Age+Class~Survived,Titanic)
ft3 <- ftable(Survived~Class,Titanic)
ft4 <- ftable(Survived~Age,Titanic)
ft5 <- ftable(Survived~Sex,Titanic)

tab10 <- xtabs(Freq~Survived,Titanic)

(c12.10 <- cbind(ft1,ft2,Total=tab10))
(r345.10 <- rbind(ft3,ft4,ft5,Total=tab10))

## Not run: 
tf <- tempfile()
Write(c12.10,file=tf)
file.show(tf)

## End(Not run)

Description

genTable creates a table of arbitrary summaries conditional on given values of independent variables given by a formula.

Aggregate does the same, but returns a data.frame instead.

fapply is a generic function that dispatches on its data argument. It is called internally by Aggregate and genTable. Methods for this function can be used to adapt Aggregate and genTable to data sources other than data frames.

Usage

Aggregate(formula, data=parent.frame(), subset=NULL,
          names=NULL, addFreq=TRUE, drop = TRUE, as.vars=1,
          ...)

genTable(formula, data=parent.frame(), subset=NULL,
         names=NULL, addFreq=TRUE,...)

Arguments

Details

If an expression is given as left hand side of the formula, its value is computed for any combination of values of the values on the right hand side. If the right hand side is a dot, then all variables in data are added to the right hand side of the formula.

If no expression is given as left hand side, then the frequency counts for the respective value combinations of the right hand variables are computed.

If a single factor is on the left hand side, then the left hand side is translated into an appropriate call to table(). Note that also in this case addFreq takes effect.

If a single numeric variable is on the left hand side, frequency counts weighted by this variable are computed. In these cases, genTable is equivalent to xtabs and Aggregate is equivalent to as.data.frame(xtabs(...)).

Value

Aggregate results in a data frame with conditional summaries and unique value combinations of conditioning variables.

genTable returns a table, that is, an array with class "table".

See Also

aggregate.data.frame, xtabs

Examples

ex.data <- expand.grid(mu=c(0,100),sigma=c(1,10))[rep(1:4,rep(100,4)),]
ex.data <- within(ex.data,
                  x<-rnorm(
                    n=nrow(ex.data),
                    mean=mu,
                    sd=sigma
                    )
                  )

Aggregate(~mu+sigma,data=ex.data)
Aggregate(mean(x)~mu+sigma,data=ex.data)
Aggregate(mean(x)~mu+sigma,data=ex.data,name="Average")
Aggregate(c(mean(x),sd(x))~mu+sigma,data=ex.data)
Aggregate(c(Mean=mean(x),StDev=sd(x),N=length(x))~mu+sigma,data=ex.data)
genTable(c(Mean=mean(x),StDev=sd(x),N=length(x))~mu+sigma,data=ex.data)

Aggregate(table(Admit)~.,data=UCBAdmissions)
Aggregate(Table(Admit,Freq)~.,data=UCBAdmissions)
Aggregate(Admit~.,data=UCBAdmissions)
Aggregate(percent(Admit)~.,data=UCBAdmissions)
Aggregate(percent(Admit)~Gender,data=UCBAdmissions)
Aggregate(percent(Admit)~Dept,data=UCBAdmissions)
Aggregate(percent(Gender)~Dept,data=UCBAdmissions)
Aggregate(percent(Admit)~Dept,data=UCBAdmissions,Gender=="Female")
genTable(percent(Admit)~Dept,data=UCBAdmissions,Gender=="Female")

Description

A generic function and methods to collect coefficients and summary statistics from a model object. It is used in mtable

Usage

## S3 method for class 'lm'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'glm'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'merMod'
getSummary(obj, alpha=.05, ...)

# These are contributed by Christopher N. Lawrence
  ## S3 method for class 'clm'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'polr'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'simex'
getSummary(obj, alpha=.05,...)

# These are contributed by Jason W. Morgan
  ## S3 method for class 'aftreg'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'coxph'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'phreg'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'survreg'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'weibreg'
getSummary(obj, alpha=.05,...)

# These are contributed by Achim Zeileis
  ## S3 method for class 'ivreg'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'tobit'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'hurdle'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'zeroinfl'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'betareg'
getSummary(obj, alpha=.05,...)
  ## S3 method for class 'multinom'
getSummary(obj, alpha=.05,...)
  
# A variant that reports exponentiated coefficients.
# The default method calls 'getSummary()' internally and should
# be applicable to all classes for which 'getSummary()' methods exist.
getSummary_expcoef(obj, alpha=.05,...)
  ## Default S3 method:
getSummary_expcoef(obj, alpha=.05,...)

Arguments

Details

The generic function getSummary is called by mtable in order to obtain the coefficients and summaries of model objects. In order to adapt mtable to models of classes other than lm or glm one needs to define getSummary methods for these classes and to set a summary template via setSummaryTemplate

Value

Any method of getSummary must return a list with the following components:

Description

Group creates a grouped variant of an object of class "data.frame" or of class "data.set", for which methods for with and within are defined, so that these well-known functions can be applied "groupwise".

Usage

# Create an object of class "grouped.data" from a
# data frame or a data set.
Groups(data,by,...)
## S3 method for class 'data.frame'
Groups(data,by,...)
## S3 method for class 'data.set'
Groups(data,by,...)
## S3 method for class 'grouped.data'
Groups(data,by,...)

# Recombine grouped data into a data fame or a data set
recombine(x,...)
## S3 method for class 'grouped.data.frame'
recombine(x,...)
## S3 method for class 'grouped.data.set'
recombine(x,...)

# Recombine grouped data and coerce the result appropriately:
## S3 method for class 'grouped.data'
as.data.frame(x,...)
## S4 method for signature 'grouped.data.frame'
as.data.set(x,row.names=NULL,...)
## S4 method for signature 'grouped.data.set'
as.data.set(x,row.names=NULL,...)

# Methods of the generics "with" and "within" for grouped data
## S3 method for class 'grouped.data'
with(data,expr,...)
## S3 method for class 'grouped.data'
within(data,expr,recombine=FALSE,...)

# This is equivalent to with(Groups(data,by),expr,...)
withGroups(data,by,expr,...)
# This is equivalent to within(Groups(data,by),expr,recombine,...)
withinGroups(data,by,expr,recombine=TRUE,...)

Arguments

Details

When applied to a data frame Groups returns an object with class attributes "grouped.data.frame", "grouped.data", and "data.frame", when applied do an object with class "data.set", it returns an object with class attributes "grouped.data.set", "grouped.data", and "data.set".

When applied to objects with class attributed "grouped.data", both the functions with() amd within() evaluate expr separately for each group defined by Groups. with() returns an array composed of the results of expr, while within() returns a modified copy of its data argument, which will be a "grouped.data" object ("grouped.data.frame" or "grouped.data.set"), unless the argument recombine=TRUE is set.

The expression expr may contain references to the variables n_, N_, and i_. n_ is equal to the size of the respective group (the number of rows belonging to it), while N_ is equal to the total number of observations in all groups. The variable i_ equals to the indices of the rows belonging to the respective group of observations.

Examples

some.data <- data.frame(x=rnorm(n=100))
some.data <- within(some.data,{
    f <- factor(rep(1:4,each=25),labels=letters[1:4])
    g <- factor(rep(1:5,each=4,5),labels=LETTERS[1:5])
    y <- x + rep(1:4,each=25) +  0.75*rep(1:5,each=4,5)
})

# For demonstration purposes, we create an
# 'empty' group:
some.data <- subset(some.data,
                       f!="a" | g!="C")

some.grouped.data <- Groups(some.data,
                           ~f+g)    

# Computing the means of y for each combination f and g
group.means <- with(some.grouped.data,
                    mean(y))
group.means

# Obtaining a groupwise centered variant of y
some.grouped.data <- within(some.grouped.data,{
    y.cent <- y - mean(y)
},recombine=FALSE)

# The groupwise centered variable should have zero mean
# whithin each group
group.means <- with(some.grouped.data,
                    round(mean(y.cent),15))
group.means

# The following demonstrates the use of n_, N_, and i_
# An external copy of y
y1 <- some.data$y
group.means.n <- with(some.grouped.data,
                      c(mean(y),  # Group means for y
                        n_,       # Group sizes
                        sum(y)/n_,# Group means for y
                        n_/N_,    # Relative group sizes
                        sum(y1)/N_,# NOT the grand mean
                        sum(y1[i_])/n_)) # Group mean for y1
group.means.n

# Names can be attached to the groupwise results
with(some.grouped.data,
     c(Centered=round(mean(y.cent),15),
       Uncentered=mean(y)))

some.data.ungrouped <- recombine(some.grouped.data)
str(some.data.ungrouped)

# It all works with "data.set" objects
some.dataset <- as.data.set(some.data)
some.grouped.dataset <- Groups(some.dataset,~f+g)

with(some.grouped.dataset,
     c(Mean=mean(y),
       Variance=var(y)))

# The following two expressions are equivalent:
with(Groups(some.data,~f+g),mean(y))
withGroups(some.data,~f+g,mean(y))

# The following two expressions are equivalent:
some.data <- within(Groups(some.data,~f+g),{
    y.cent <- y - mean(y)
    y.cent.1 <- y - sum(y)/n_
})

some.data <- withinGroups(some.data,~f+g,{
    y.cent <- y - mean(y)
    y.cent.1 <- y - sum(y)/n_
})

# Both variants of groupwise centred varaibles should
# have zero groupwise means:
withGroups(some.data,~f+g,{
    c(round(mean(y.cent),15),
      round(mean(y.cent.1),15))
})

Description

The functions described here form building blocks for the format_html methods functions for codebook, ftable, ftable_matrix, and mtable objects, etc.

The most basic of these functions is html, which constructs an object that represents a minimal piece of HTML code and is member of the class "html_elem". Unlike a character string containing HTML code, the resulting code element can relatively easily modified using other functions presented here. The actual code is created when the function as.character is applied to these objects.

Longer sequences of HTML code can be prepared by concatenating them with c, or by html_group, or by applying as.html_group to a list of "html_elem" objects. All these result in objects of class "html_group".

Attributes (such as class, id etc.) of HTML elements can be added to the call to html, but can also later recalled or modified with attribs or setAttribs. An important attribute is the style attribute, which can contain CSS styling. It can be recalled or modified with style or setStyle. Styling strings can also be created with hmtl_style or as.css

Usage

html(tag, ..., .content = NULL, linebreak = FALSE)
html_group(...)
as.html_group(x)

content(x)
content(x)<-value
setContent(x,value)

attribs(x)
attribs(x)<-value
setAttribs(x,...)
## S3 method for class 'character'
setAttribs(x,...)
## S3 method for class 'html_elem'
setAttribs(x,...)
## S3 method for class 'html_group'
setAttribs(x,...)

css(...)
as.css(x)
style(x)
style(x) <- value
setStyle(x,...)
## S3 method for class 'character'
setStyle(x,...)
## S3 method for class 'html_elem'
setStyle(x,...)
## S3 method for class 'html_group'
setStyle(x,...)

Arguments

Details

Objects created with html are lists with class attribute "html_elem" and components

tag

a character string

attributes

a named character vector

content

a character vector, an "html_elem" or "html_group" object, or a list of such.

linebreak

a logical value or vector of length 2.

Objects created with html_group or by concatenation of "html_elem" or "html_group" object are lists of such objects, with class attribute "html_group".

Examples

html("img")
html("img",src="test.png")
html("div",class="element",id="first","Sisyphus")
html("div",class="element",id="first",.content="Sisyphus")

div <- html("div",class="element",id="first",linebreak=c(TRUE,TRUE))
content(div) <- "Sisyphus"
div

tag <- html("tag",linebreak=TRUE)
attribs(tag)["class"] <- "something"
attribs(tag)["class"]
tag

style(tag) <- c(color="#342334")
style(tag)
tag

style(tag)["bg"] <- "white"
tag

setStyle(tag,bg="black")
setStyle(tag,c(bg="black"))

c(div,tag,tag)

c(
  c(div,tag),
  c(div,tag,tag)
)

c(
  c(div,tag),
  div,tag,tag
)

c(
  div,tag,
  c(div,tag,tag)
)

content(div) <- c(tag,tag,tag)
div


css("background-color"="black",
                  color="white")

as.css(c("background-color"="black",
                  color="white"))



Hello <- "Hello World!"
Hello <- html("p",Hello,linebreak=c(TRUE,TRUE))
style(Hello) <- c(color="white",
                  "font-size"="40px",
                  "text-align"="center")
     
Link <- html("a","More examples here ...",
             href="http://elff.eu/software/memisc",
             title="More examples here ...",
             style=css(color="white"),
             linebreak=c(TRUE,FALSE))
Link <- html("p"," (",Link,")",linebreak=c(TRUE,TRUE))
style(Link) <- c(color="white",
                 "font-size"="15px",
                 "text-align"="center")

Hello <- html("div",c(Hello,Link),linebreak=c(TRUE,TRUE))
style(Hello) <- c("background-color"="#160666",
                  padding="20px")
Hello

show_html(Hello)

Description

This function uses the base package function iconv to translate variable descriptions (a.k.a variable labels) and value labels of item, data.set, and importer objects into a specified encoding.

It will be useful in UTF-8 systems when data file come in some ancient encoding like 'Latin-1' as long used by Windows systems.

Usage

Iconv(x,from="",to="",...) 
## S3 method for class 'character'
Iconv(x,from="",to="",...) 
## S3 method for class 'annotation'
Iconv(x,from="",to="",...) 
## S3 method for class 'data.set'
Iconv(x,from="",to="",...) 
## S3 method for class 'importer'
Iconv(x,from="",to="",...) 
## S3 method for class 'item'
Iconv(x,from="",to="",...) 
## S3 method for class 'value.labels'
Iconv(x,from="",to="",...)