## S3 method for class 'mids.1chain'
with(data, expr, ...)
## S3 method for class 'datlist'
with(data, expr, fun, ...)

## S3 method for class 'mids.nmi'
with(data, expr, ...)
## S3 method for class 'nested.datlist'
with(data, expr, fun, ...)
## S3 method for class 'NestedImputationList'
with(data, expr, fun, ...)

## S3 method for class 'datlist'
within(data, expr, ...)
## S3 method for class 'imputationList'
within(data, expr, ...)

## S3 method for class 'nested.datlist'
within(data, expr, ...)
## S3 method for class 'NestedImputationList'
within(data, expr, ...)

withPool_MI(x, ...)

withPool_NMI(x, ...)

## S3 method for class 'mira.nmi'
summary(object, ...)

#############################################################################
# EXAMPLE 1: One chain nhanes data | application of 'with' and 'within'
#############################################################################

library(mice)
data(nhanes, package="mice")
set.seed(9090)

# nhanes data in one chain
imp <- miceadds::mice.1chain( nhanes, burnin=5, iter=40, Nimp=4 )
# apply linear regression
res <- with( imp, expr=stats::lm( hyp ~ age + bmi  ) )
summary(res)
# pool results
summary( mice::pool(res))

# calculate some descriptive statistics
res2 <- with( imp, expr=c("M1"=mean(hyp), "SD_age"=stats::sd(age) ) )
# pool estimates
withPool_MI(res2)

# with method for datlist
imp1 <- miceadds::datlist_create(imp)
res2b <- with( imp1, fun=function(data){
                    dfr <- data.frame("M"=colMeans(data),
                             "Q5"=apply( data, 2, stats::quantile, .05 ),
                             "Q95"=apply( data, 2, stats::quantile, .95 ) )
                    return(dfr)
                        } )
withPool_MI(res2b)

# convert mids object into an object of class imputationList
datlist <- miceadds::mids2datlist( imp )
datlist <- mitools::imputationList(datlist)

## Not run: 
# define formulas for modification of the data frames in imputationList object
datlist2 <- within( datlist, {
                     age.D3 <- 1*(age==3)
                     hyp_chl <- hyp * chl
                        } )
# look at modified dataset
head( datlist2$imputations[[1]] )

# convert into a datlist
datlist2b <- miceadds::datlist_create( datlist2 )

# apply linear model using expression
mod1a <- with( datlist2, expr=stats::lm( hyp ~ age.D3 ) )
# do the same but now with a function argument
mod1b <- with( datlist2, fun=function(data){
                    stats::lm( data$hyp ~ data$age.D3 )
                        } )
# apply the same model for object datlist2b
mod2a <- with( datlist2b, expr=lm( hyp ~ age.D3 ) )
mod2b <- with( datlist2b, fun=function(data){
                    stats::lm( data$hyp ~ data$age.D3 )
                        } )

mitools::MIcombine(mod1a)
mitools::MIcombine(mod1b)
mitools::MIcombine(mod2a)
mitools::MIcombine(mod2b)

#############################################################################
# EXAMPLE 2: Nested multiple imputation and application of with/within methods
#############################################################################

library(BIFIEsurvey)
data(data.timss2, package="BIFIEsurvey" )
datlist <- data.timss2

# remove first four variables
M <- length(datlist)
for (ll in 1:M){
    datlist[[ll]] <- datlist[[ll]][, -c(1:4) ]
                }

# nested multiple imputation using mice
imp1 <- miceadds::mice.nmi( datlist,  m=4, maxit=3 )
summary(imp1)
# apply linear model and use summary method for all analyses of imputed datasets
res1 <- with( imp1, stats::lm( ASMMAT ~ migrant + female ) )
summary(res1)

# convert mids.nmi object into an object of class NestedImputationList
datlist1 <- miceadds::mids2datlist( imp1 )
datlist1 <- miceadds::NestedImputationList( datlist1 )
# convert into nested.datlist object
datlist1b <- miceadds::nested.datlist_create(datlist1)

# use with function
res1b <- with( datlist1, stats::glm( ASMMAT ~ migrant + female ) )
# apply for nested.datlist
res1c <- with( datlist1b, stats::glm( ASMMAT ~ migrant + female ) )

# use within function for data transformations
datlist2 <- within( datlist1, {
                highsc <- 1*(ASSSCI > 600)
                books_dum <- 1*(books>=3)
                rm(scsci)   # remove variable scsci
                    } )

# include random number in each dataset
N <- attr( datlist1b, "nobs")
datlist3 <- within( datlist1b, {
                rn <- stats::runif( N, 0, .5 )
                    } )

#-- some applications of withPool_NMI
# mean and SD
res3a <- with( imp1, c( "m1"=mean(ASMMAT), "sd1"=stats::sd(ASMMAT) ) )
withPool_NMI(res3a)
# quantiles
vars <- c("ASMMAT", "lang", "scsci")
res3b <- with( datlist1b, fun=function(data){
                dat <- data[,vars]
                res0 <- sapply( vars, FUN=function(vv){
                    stats::quantile( dat[,vv], probs=c(.25, .50, .75) )
                                    } )
                t(res0)
                    } )
withPool_NMI(res3b)

## End(Not run)