=====================================================
 Dynamic State-Space Models of Coded Political Texts 
=====================================================

.. r-package:: manifestos
.. r-pkgversion:: 0.8
.. r-name:: latpos

     latpos
     print.latpos
     summary.latpos
     print.summary.latpos
     relabel.summary.latpos
     predict.latpos

Description
===========

The function ``latpos`` allows to specify and estimate a dynamic state-space model of
political texts and returns an object from which the (latent) positions, which actors
take in their texts, can be predicted.

Usage
=====

.. code-block:: r

     latpos(formula,data,subset,id,time,
            unfold.method="Schoenemann",start=NULL,
            sampler=mvt.sampler(df=7*length(latent.dims)),
            ...)

     ## S4 method for signature 'latpos'
   predict(object, newdata = NULL, id=NULL, time=NULL,
             type=c("posterior modes","posterior means","simulate"),
             se.fit=FALSE, interval=c("none","normal","percentile"), level=0.95,
             sample.size = object$sample.size,
             sampler=object$sampler,
             maxiter=100,...)

Arguments
=========

``formula``
   a formula describing the model.

``data``
   an optional data frame that contains data to which the model is fitted.

``subset``
   a logical vector; an optional condition that defines a subset of the optiona data frame
   to which the analysis is to be restricted.

``id``
   name of a variable that identifies the actors.

``time``
   name of a variable that identifies the occasions on which actors publish their political
   texts.

``unfold.method``
   a text string, name of the method which is used in the unfolding procedure to obtain
   starting values.

``start``
   an optional list giving starting values.

``sampler``
   an object that generates random numbers to be used in the MCEM algorithm.

``...``
   further optional arguments, that are passed to ``latpos.control`` and ``latpos.start`` by
   the function ``latpos`` and ignored by the ``predict`` method.

``object``
   an object of class "latpos".

``newdata``
   an optional data frame to predict actors positions from, based on the fitted model
   contained in ``object``.

``type``
   a character string identifying the type of predictions about the latent positions, either
   "posterior modes","posterior means", or "simulate".  If the type is "posterior means" or
   "posterior modes", only one prediction is generated per coded text. If the type is
   "simulate", then ``sample.size`` predictions are generated from the empirical Bayes
   posterior distribution of the positions.

``se.fit``
   logical, should standard errors be provided with the posterior means?

``interval``
   a character vector. If "none", then no prediction intervals are returned, if "normal"
   than prediction intervals are contstructed based on normal quantiles, if "percentile",
   then predicion intervals are constructed based on the empirical percentiles of samples
   from the posterior.

``level``
   a number between zero and one, the nominal coverage level of the prediction intervals.

``sample.size``
   a positive number, the sample size for the simulated posterior means, or the number of
   imputed values generated from the posterior.

``maxiter``
   a positive number, the maximum number of iterations used to compute posterior modes.

Value
=====

``latpos`` returns an object of class "latpos" that contains parameter estimates etc.

``predict.latpos`` returns a vector or a matrix depending on the arguments provided to
the function.

Examples
========

.. code-block:: r

   load(file="manifesto-counts.RData")
   options(latpos.chunk.size=4*1024*1024) # determines the size of
   # data chunks used in internal computations.

   econ.latpos <- latpos(
      nationalize+controlecon+econplan+marketregul+incentives+econorthodox+freeenterp~econlr,
      data=manifesto.counts,
      id=party,
      time=year*100 + month,
      free.beta=TRUE,
      initial.size=50
    )

   summary(econ.latpos)

   nonmat.latpos <- latpos(
       laworder+tradmoralpos+tradmoralneg+natwaylifepos+
       democracy+freedmhumrights~authlib+tradmod,
       data=manifesto.counts,
       id=party,
       time=year*100 + month,
       initial.size=50,
       restrictions=set.parms.free(
         authlib=c("natwaylifepos","laworder","democracy","freedmhumrights"),
         tradmod=c("tradmoralpos","tradmoralneg","democracy","freedmhumrights")
       ),
       start = list(
             A=list(
                 authlib=c(natwaylifepos=1.4,laworder=.7,democracy=-1),
                 tradmod=c(tradmoralpos=1,tradmoralneg=-1)
               )
           )
   )
   summary(nonmat.latpos)