[Depmix-commits] r153 - in trunk: . man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Jun 11 00:01:03 CEST 2008
Author: ingmarvisser
Date: 2008-06-11 00:01:03 +0200 (Wed, 11 Jun 2008)
New Revision: 153
Modified:
trunk/NEWS
trunk/man/depmix-methods.Rd
trunk/man/depmix.Rd
trunk/man/depmix.fit.Rd
trunk/man/depmix.fitted-class.Rd
trunk/man/depmixS4-package.Rd
trunk/man/response.Rd
Log:
Documentation updates (added cross links and the like)
Modified: trunk/NEWS
===================================================================
--- trunk/NEWS 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/NEWS 2008-06-10 22:01:03 UTC (rev 153)
@@ -4,8 +4,12 @@
o restructured R and Rd files
- o
+ o added function simulate to generate new data from a (fitted) model
+ o added function forwardbackward to access the forward and backward
+ variables as well as the smoothed transition and state variables
+
+ o added new glm distributions: gamma, poisson
Changes in depmixS4 version 0.1-1
Modified: trunk/man/depmix-methods.Rd
===================================================================
--- trunk/man/depmix-methods.Rd 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/man/depmix-methods.Rd 2008-06-10 22:01:03 UTC (rev 153)
@@ -2,6 +2,8 @@
\docType{methods}
+\alias{depmix-methods}
+
\alias{logLik}
\alias{logLik,depmix-method}
@@ -52,8 +54,9 @@
forward backward routine the state and transition smoothed probabilities
are also computed which are not neccessary for the log likelihood. Those
smoothed variables, and the forward and backward variables are accessible
- through the \code{forwardbackward} function.} \item{which}{The default
- "pars" returns a vector of all parameters of a
+ through the \code{\link{forwardbackward}} function.}
+
+ \item{which}{The default "pars" returns a vector of all parameters of a
\code{depmix} object; the alternative value "fixed" return a logical
vector of the same length indicating which parameters are fixed. The
@@ -69,22 +72,41 @@
\value{
- \item{logLik} {returns a \code{logLik} object with attributes \code{df} and \code{nobs}.}
+ \item{logLik}{returns a \code{logLik} object with attributes \code{df} and \code{nobs}.}
- \item{nobs} {returns the number of observations (used in computing the BIC).}
+ \item{nobs}{returns the number of observations (used in computing the BIC).}
- \item{npar} {returns the number of paramters of a model.}
+ \item{npar}{returns the number of paramters of a model.}
- \item{freepars} {returns the number of non-fixed parameters.}
+ \item{freepars}{returns the number of non-fixed parameters.}
- \item{setpars} {returns a depmix object with new parameter values.}
+ \item{setpars}{returns a depmix object with new parameter values.}
- \item{getpars} {returns a vector with the current parameter values.}
+ \item{getpars}{returns a vector with the current parameter values.}
}
+
\author{Ingmar Visser}
+
\examples{
- # add some examples here in the future
+
+# create a 2 state model with one continuous and one binary response
+data(speed)
+mod <- depmix(list(rt~1,corr~1),data=speed,nstates=2,family=list(gaussian(),multinomial()))
+
+# get the loglikelihood of the model
+logLik(mod)
+
+# to see the ordering of parameters to use in setpars
+mod <- setpars(mod, value=1:npar(mod))
+mod
+
+# to see which parameters are fixed (by default only baseline parameters in
+# the multinomial logistic models for the transition models and the initial
+# state probabilities model
+mod <- setpars(mod, getpars(mod,which="fixed"))
+mod
+
}
\keyword{methods}
Modified: trunk/man/depmix.Rd
===================================================================
--- trunk/man/depmix.Rd 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/man/depmix.Rd 2008-06-10 22:01:03 UTC (rev 153)
@@ -15,16 +15,10 @@
\title{Dependent Mixture Model Specifiction}
\description{
-
- depmixS4 is a framework for specifying and fitting dependent mixture
- models, otherwise known as hidden or latent Markov models.
- Optimization is done with the EM algorithm or optionally with Rdonlp2
- when constraints on parameters are imposed. Models for different
- distributions can easily be added.
- \code{depmix} creates an object of class \code{depmix}, a
- dependent mixture model, otherwise known as hidden Markov
- model.
+ \code{depmix} creates an object of class \code{depmix}, a dependent
+ mixture model, otherwise known as hidden Markov model. For a short
+ description of the package see \code{\link{depmixS4}}.
}
@@ -32,26 +26,23 @@
depmix(response, data=NULL, nstates, transition=~1, family=gaussian(),
prior=~1, initdata=NULL, respstart=NULL, trstart=NULL, instart=NULL,
- ntimes=NULL,...)
+ ntimes=NULL,...)
- \S4method{summary}{depmix}(object)
-
-
}
\arguments{
- \item{object}{An object with class \code{depmix}.}
\item{response}{The response to be modeled; either a formula or a list
- of formulae in the multivariate case. See details.}
+ of formulae in the multivariate case; this interfaces to the glm
+ distributions. See 'Details'.}
\item{data}{An optional data.frame to interpret the variables in
- response and transition.}
+ the response and transition arguments.}
\item{nstates}{The number of states of the model.}
\item{transition}{A one-sided formula specifying the model for the
- transitions. See details.}
+ transitions. See 'Details'.}
\item{family}{A family argument for the response. This must be a list
of family's if the response is multivariate.}
@@ -61,7 +52,7 @@
\item{initdata}{An optional data.frame to interpret the variables
occuring in prior. The number of rows of this data.frame must be
- equal to the number of cases being modeled. See details.}
+ equal to the number of cases being modeled. See 'Details'.}
\item{respstart}{Starting values for the parameters of the response
models.}
@@ -79,32 +70,37 @@
\item{...}{Not used currently.}
+ \item{object}{An object of class \code{depmix}.}
+
}
\details{
The function \code{depmix} creates an S4 object of class \code{depmix},
- which needs to be fitted using \code{\link[depmixS4]{depmix.fit}} to
- optimize the parameters.
+ which needs to be fitted using \code{\link{fit}} to optimize the
+ parameters.
- The response model(s) are created by call(s) to
- \code{\link[depmixS4]{response}} providing the family and optional
- predictors. If response is a list of formulae, the response's are
- assumed to be independent conditional on the latent state.
+ The response model(s) are created by call(s) to \code{\link{response}}
+ providing the response formula and the family specifying the error
+ distribution. If response is a list of formulae, the \code{response}'s
+ are assumed to be independent conditional on the latent state.
The transitions are modeled as a multinomial logistic model for each
state. Hence, the transition matrix can be modeled as time-dependent,
depending on predictors. The prior density is also modeled as a
multinomial logistic. Both are created by calls to
- \code{\link[depmixS4]{transInit}}.
+ \code{\link{transInit}}.
Starting values may be provided by the respective arguments. The order
in which parameters must be provided can be easily studied by using the
- \code{setpars} function (see example).
+ \code{\link{setpars}} function.
Linear constraints on parameters can be provided as argument to the
- \code{\link[depmixS4]{depmix.fit}} function.
+ \code{\link{fit}} function.
+ The print function prints the formulae for the response, transition and
+ prior models along with their parameter values.
+
}
\value{
@@ -122,8 +118,8 @@
\item{prior}{A multinomial logistic model for the initial state
probabilities.}
- \item{dens,trDens,init}{See depmix-class help for details. For internal
- use.}
+ \item{dens,trDens,init}{See \code{\link{depmix-class}} help for
+ details. For internal use.}
\item{stationary}{Logical indicating whether the transitions are
time-dependent or not; for internal use.}
@@ -136,19 +132,20 @@
\item{nresp}{The number of independent responses.}
- \item{npars}{The total number of parameters of the model. This is not
- the degrees of freedom, ie there are redundancies in the
- parameters, in particular in the multinomial models for the
- transitions and prior.}
+ \item{npars}{The total number of parameters of the model. Note: this
+ is \emph{not} the degrees of freedom because there are redundancies in the
+ parameters, in particular in the multinomial models for the transitions
+ and prior probabilities.}
}
-\author{Ingmar Visser \email{i.visser at uva.nl}}
+\author{Ingmar Visser & Maarten Speekenbrink}
\seealso{
- \code{\link[depmixS4]{depmix.fit}}, \code{\link{transInit}},
- \code{\link{response}}.
+ \code{\link{fit}}, \code{\link{transInit}}, \code{\link{response}},
+ \code{\link{depmix-methods}} for accessor functions to \code{depmix}
+ objects.
}
@@ -171,16 +168,6 @@
# print the model, formulae and parameter values
mod
-# to see the ordering of parameters to use in setpars
-mod <- setpars(mod, value=1:npar(mod))
-mod
-
-# to see which parameters are fixed (by default only baseline parameters in
-# the multinomial logistic models for the transition models and the initial
-# state probabilities model
-mod <- setpars(mod, getpars(mod,which="fixed"))
-mod
-
}
\keyword{methods}
Modified: trunk/man/depmix.fit.Rd
===================================================================
--- trunk/man/depmix.fit.Rd 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/man/depmix.fit.Rd 2008-06-10 22:01:03 UTC (rev 153)
@@ -46,54 +46,64 @@
}
-\details{
- The method fits depmix models by the EM algorithm if there are no
- linear constraints on the parameters and if the transition model has
- no covariates. Otherwise the general optimizer donlp is used which
- handles general linear (in-)equality constraints.
+\details{
+
+ Models are fitted by the EM algorithm if there are no constraints on
+ the parameters. Otherwise the general optimizer \code{donlp2} from the
+ package \code{Rdonlp2} is used which handles general linear
+ (in-)equality constraints.
Three types of constraints can be specified on the parameters: fixed,
- equality, and general constraints. Constraint vectors should be of
- length npar(object). See help on getpars and setpars about the
- ordering of parameters.
+ equality, and general linear (in-)equality constraints. Constraint
+ vectors should be of length npar(object). See help on
+ \code{\link{getpars}} and \code{\link{setpars}} about the ordering of
+ parameters.
The \code{equal} argument is used to specify equality constraints:
parameters that get the same integer number in this vector are
- estimated to be equal. Any integers can be used in the vector except 0
- and 1, which indicate fixed and free parameters respectively.
+ estimated to be equal. Any integers can be used in this way except 0
+ and 1, which indicate fixed and free parameters, respectively.
- Using the donlp optimizer a Newton-Raphson scheme is employed to
- estimate parameters subject to linear constraints by imposing:
+ Using the \code{donlp2} optimizer a Newton-Raphson scheme is employed
+ to estimate parameters subject to linear constraints by imposing:
bl <= A*x <= bu,
- where x is the parameter vector, bl is a vector of lower bounds, bu
- is a vector of upper bounds, and A is the constraint matrix.
+ where x is the parameter vector, bl is a vector of lower bounds, bu is
+ a vector of upper bounds, and A is the constraint matrix.
- The \code{conrows} argument is used to specify rows of A directly, and
- the conrows.lower and conrows.upper arguments to specify the bounds on
- the constraints. \code{conrows} is a matrix of npar(object) columns and
- one row for each constraint (ie a vector in the case of a single
- constraint).
+ The \code{conrows} argument is used to specify rows of A directly, and
+ the conrows.lower and conrows.upper arguments to specify the bounds on
+ the constraints. \code{conrows} is a matrix of npar(object) columns
+ and one row for each constraint (a vector in the case of a single
+ constraint).
- \code{llratio} performs a log-likelihood ratio test on two
- \code{fit}ted models; the first object should have the largest degrees
- of freedom.
+ \code{\link{llratio}} performs a log-likelihood ratio test on two
+ \code{fit}'ted models; the first object should have the largest degrees
+ of freedom (find out by using \code{\link{freepars}}).
}
\value{
- \code{fit} returns an object of class \code{\link[depmix.fitted-class]{depmix.fitted}} which contains
- the original depmix object, and further has slots:
+ \code{fit} returns an object of class
+ \code{\link{depmix.fitted}} which contains the
+ original \code{depmix} object, and further has slots:
\item{message}{: Convergence information.}
\item{conMat}{: The constraint matrix A, see details.}
- The print method shows the \code{message} and the summary method
- shows the parameter estimates.
+ \item{posterior}{: The posterior state sequence (computed with the
+ viterbi algorithm), and the posterior probabilities (delta
+ probabilities in Rabiner, 1989, notation).}
+ The print method shows the \code{message} along with the likelihood and
+ AIC and BIC; the summary method prints the parameter estimates.
+
+ Posterior densities and the viterbi state sequence can be accessed
+ through \code{\link{posterior}}.
+
}
\references{
@@ -106,39 +116,7 @@
\examples{
-\dontshow{
data(speed)
-
-pars <- c(1,0.916,0.084,0.101,0.899,6.39,0.24,0.098,0.902,5.52,0.202,0.472,0.528,1,0)
-
-rModels <- list(
- list(
- GLMresponse(formula=rt~1,data=speed,family=gaussian(),pstart=c(5.52,.202)),
- GLMresponse(formula=corr~1,data=speed,family=multinomial(),pstart=c(0.472,0.528))
- ),
- list(
- GLMresponse(formula=rt~1,data=speed,family=gaussian(),pstart=c(6.39,.24)),
- GLMresponse(formula=corr~1,data=speed,family=multinomial(),pstart=c(.098,.902))
- )
-)
-
-trstart=c(0.899,0.101,0.084,0.916)
-
-transition <- list()
-transition[[1]] <- transInit(~1,nstates=2,data=data.frame(1),pstart=c(trstart[1:2]))
-transition[[2]] <- transInit(~1,nstates=2,data=data.frame(1),pstart=c(trstart[3:4]))
-
-instart=c(0,1)
-inMod <- transInit(~1,ns=2,ps=instart,data=data.frame(rep(1,3)))
-
-mod <- makeDepmix(response=rModels,transition=transition,prior=inMod,ntimes=attr(speed,"ntimes"))
-
-ll <- logLik(mod)
-ll.fb <- logLik(mod,method="fb")
-
-} #end dontshow
-
-data(speed)
# 2-state model on the RTs of the speed data with random
# starting values for the transition pars (without those EM does not get off the ground)
set.seed(1)
Modified: trunk/man/depmix.fitted-class.Rd
===================================================================
--- trunk/man/depmix.fitted-class.Rd 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/man/depmix.fitted-class.Rd 2008-06-10 22:01:03 UTC (rev 153)
@@ -2,6 +2,7 @@
\docType{class}
+\alias{depmix.fitted}
\alias{depmix.fitted-class}
\title{Class "depmix.fitted"}
Modified: trunk/man/depmixS4-package.Rd
===================================================================
--- trunk/man/depmixS4-package.Rd 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/man/depmixS4-package.Rd 2008-06-10 22:01:03 UTC (rev 153)
@@ -1,35 +1,49 @@
\name{depmixS4-package}
+\alias{depmixS4}
\alias{depmixS4-package}
-\alias{depmixS4}
\docType{package}
+
\title{
-depmixS4 provides classes for fitting hidden Markov models
+
+depmixS4 provides classes for specifying and fitting hidden Markov models
+
}
+
\description{
-depmixS4 fits hidden Markov models on (multiple) sets of observations by the use
-of either EM or direct optimization of the log-likelihood; the latter is used to
-incorporate general linear constraints into models. The response densities for
-each state may be chosen from the GLM family, or a multinomial. User defined
-response densities are easy to add.
+
+ \code{depmixS4} is a framework for specifying and fitting dependent
+ mixture models, otherwise known as hidden or latent Markov models.
+ Optimization is done with the EM algorithm or optionally with Rdonlp2
+ when (general linear (in-)equality) constraints on the parameters need
+ to be incorporated. Models can be fitted on (multiple) sets of
+ observations. The response densities for each state may be chosen from
+ the GLM family, or a multinomial. User defined response densities are
+ easy to add.
+
}
+
\details{
-\tabular{ll}{
-Package: \tab depmixS4\cr
-Type: \tab Package\cr
-Version: \tab 0.2-0\cr
-Date: \tab 2008-06-10\cr
-License: \tab GPL\cr
-}
-Model fitting is done in two steps; first, models are specified through the
-\code{depmix} function, which uses standard arguments to eg specify GLM densities
-for the responses; second, the model is fitted; the \code{fit} function is used to
-provide extra arguments concerning the optimization, such as providing
-constraints on parameters.
+ \tabular{ll}{
+ Package: \tab depmixS4\cr
+ Type: \tab Package\cr
+ Version: \tab 0.2-0\cr
+ Date: \tab 2008-06-10\cr
+ License: \tab GPL\cr
+ }
+ Model fitting is done in two steps; first, models are specified through
+ the \code{\link{depmix}} function, which uses standard
+ \code{\link{glm}} style arguments to specify the observed
+ distributions; second, the model needs to be fitted by using the
+ \code{\link{fit}} function; imposing constraints is done through the
+ fit function. Standard output includes the optimized parameters and
+ the posterior densities for the states and the optimal state sequence.
+
}
+
\author{
Ingmar Visser & Maarten Speekenbrink
@@ -40,12 +54,12 @@
\references{
-On hidden Markov models: Lawrence R. Rabiner (1989). A tutorial on
-hidden Markov models and selected applications in speech recognition.
-\emph{Proceedings of IEEE}, 77-2, p. 267-295.
+ On hidden Markov models: Lawrence R. Rabiner (1989). A tutorial on
+ hidden Markov models and selected applications in speech recognition.
+ \emph{Proceedings of IEEE}, 77-2, p. 267-295.
-On latent class models: A. L. McCutcheon (1987). \emph{Latent class
-analysis}. Sage Publications.
+ On latent class models: A. L. McCutcheon (1987). \emph{Latent class
+ analysis}. Sage Publications.
}
@@ -53,10 +67,10 @@
\seealso{
-\code{\link[depmixS4]{depmix}}
+ \code{\link{depmix}}, \code{\link{fit}}
}
\examples{
-# These should be added at some point ...
+ # These should be added at some point ...
}
\ No newline at end of file
Modified: trunk/man/response.Rd
===================================================================
--- trunk/man/response.Rd 2008-06-10 15:22:18 UTC (rev 152)
+++ trunk/man/response.Rd 2008-06-10 22:01:03 UTC (rev 153)
@@ -35,37 +35,38 @@
}
\arguments{
- \item{formula}{A model formula.}
- \item{nstates}{The number of states of the model.}
+ \item{formula}{A model \code{\link{formula}}.}
+ \item{data}{An optional data.frame to interpret the variables from the
+ formula argument in.}
\item{family}{A family object; currently only multinomial() and
gaussian() are allowed options.}
- \item{data}{An optional data.frame to interpret the variables from the
- formula argument in.}
\item{pstart}{Starting values for the coefficients and other
parameters, ie the standard deviation for the gaussian() family.}
\item{fixed}{Logical vector indicating which paramters are to be fixed.}
\item{prob}{Logical indicating whether the starting values for
multinomial() family models are probabilities or logistic
parameters (see details).}
+ \item{nstates}{The number of states of the model.}
\item{object}{Object of class response.}
\item{...}{Not used currently.}
}
\details{
- Both methods use the familiar formula interface from linear and general
- linear models to specify how responses (or transition or prior
- parameters) depend on covariates.
+ Both methods use the familiar formula interface from \code{\link{glm}}
+ to specify how responses (or transition or prior parameters) depend on
+ covariates/predictors.
- The GLMresponse model is an interface to the glm functions of which
- the functionality is leant, ie predict, fit and density functions.
+ The \code{GLMresponse} model is an interface to the \code{glm}
+ functions of which the functionality is leant: predict, fit and
+ density functions.
- The transInit response model provides functionality for multinomial
- responses that are currently fit using nnet (this may change in the
- future but this should not affect the interface of this function). Note
- that the transInit model actually lacks a reponse, ie the y-slot is
- empty, at the time of construction, as the transitions are not
- observed.
+ The \code{transInit} response model provides functionality for
+ multinomial responses that are currently fit using nnet (this may
+ change in the future but this should not affect the interface of this
+ function). Note that the transInit model actually lacks a reponse, ie
+ the y-slot is empty, at the time of construction, as the transitions
+ are not observed.
}
More information about the depmix-commits
mailing list