%  file sn/man/sn-st.info.Rd  
%  This file is a component of the package 'sn' for R
%  copyright (C) 2013 Adelchi Azzalini
%---------------------
\name{sn-st.info}
\alias{sn.infoUv}
\alias{sn.infoMv}
\alias{st.infoUv}
\alias{st.infoMv}
\title{Expected and observed Fisher information for \acronym{SN} 
  and \acronym{ST} distributions}

\description{
  Computes Fisher information for parameters of simple sample having
  skew-normal (\acronym{SN}) or skew-\eqn{t} (\acronym{ST}) distribution or
  for a regression model with errors term having such distributions, in the
  \acronym{DP} and \acronym{CP} parametrizations.
}

\usage{
sn.infoUv(dp=NULL, cp=NULL, x=NULL, y, w, penalty=NULL,  norm2.tol=1e-06) 
    
sn.infoMv(dp, x=NULL, y, w,  norm2.tol=1e-06)

st.infoUv(dp=NULL, cp=NULL, x=NULL, y, fixed.nu=NULL, w, penalty=NULL, 
  norm2.tol=1e-06) 

st.infoMv(dp, x=NULL, y, fixed.nu=NULL, w, penalty=NULL, norm2.tol=1e-06) 
}

\arguments{

 \item{dp, cp}{direct or centred parameters, respectively; one of the two
  vectors must be supplied, but not both. For the univariate \acronym{SN}
  distribution, \code{sn.infoUv} is to be used, and these arguments are
  vectors. In the multivariate case, \code{sn.infoMv} is to be used and these
  arguments are lists. See \code{\link{dp2cp}} for their description.}

 \item{x}{an optional matrix which represents the design matrix of a 
  regression model}

 \item{y}{a numeric vector (for \code{sn.infoUv} and \code{st.infoUv})
   or a matrix (for \code{sn.infoMv} and \code{st.infoMv}) representing the
   response.  In the \acronym{SN} case ( \code{sn.infoUv} and
   \code{sn.infoMv}), \code{y} can be missing, and in this case the observed
   information matrix is computed; otherwise the observed information is
   computed. In the \acronym{ST} case ( \code{st.infoUv} and \code{st.infoMv},
   \code{y} is a required argument, since only the observed information matrix
   for \acronym{ST} distributions is implemented. See \sQuote{Details} for
   additional information.}

 \item{w}{an optional vector of weights; if missing, a vector of 1's is
  generated.}

\item{fixed.nu}{an optional numeric value which declared a fixed value of the
   degrees of freedom, \code{nu}. If not \code{NULL}, the information matrix
   has a dimension reduced by 1.}

\item{penalty}{a optional string?? with the same  penalty function used in 
  the call to \code{\link{selm}}; see this function for its description;}

 \item{norm2.tol}{for the observed information case, the Mahalanobis squared
   distance of the score 0 is evaluated; if it exceeds \code{norm2.tol}, a
   warning message is issued, since the \sQuote{information matrix} so
   evaluated may be not positive-definite.  See \sQuote{Details} for
   additional information. }
}

\value{
a list containing the following components:
\item{dp, cp}{one of the two arguments is the one supplied on input; 
the other one matches the previous one in the alternative parametrization.}

\item{type}{the type of information matrix: "observed" or "expected".}

\item{info.dp, info.cp}{matrices of Fisher (observed or expected) 
information in the two parametrizations.}
 
\item{asyvar.dp, asyvar.cp}{inverse matrices of Fisher information in the two
parametrizations, when available; See \sQuote{Details} for additional
information. }
 
\item{aux}{a list containing auxiliary elements, depending of the selected 
function and the type of computation.}
}

\section{Details}{

In the univariate case, when \code{x} is not set, then a simple random sample
is assumed and a matrix \code{x} with a single column of all 1's is
constructed; in this case, the supplied vector \code{dp} or \code{cp} must
have length 3.  If \code{x} is set, then the supplied vector of parameters,
\code{dp} or \code{cp}, must have length \code{ncol(x)+2}.
In the multivariate case, a direct extension of this scheme applies.

If the observed information matrix is required, \code{dp} or \code{dp} should
represent the maximum likelihood estimates (MLE) for the given \code{y},
otherwise the information matrix may fail to be positive-definite. Therefore,
the squared Mahalobis norm of the score vector is evaluated and compared with
\code{norm2.tol}. If it exceeds this threshold, it is taken as an indication
that the parameter is not at the MLE and a warning message is issued. The
returned list still includes \code{info.dp} and \code{info.cp}, but in this
case these represent merely the matrices of second derivatives;
\code{asyvar.dp} and \code{asyvar.cp} are set to \code{NULL}.

}

\section{Background}{
  The information matrix for the the univariate \acronym{SN} distribution in
  the two stated parameterizations in discussed in Sections 3.1.3--4 of 
  Azzalini and Capitanio (2014). For the multivariate distribution,   
  Section 5.2.2 of this monograph summarizes briefly the findings of 
  Arellano-Valle and Azzalini (2008).
 
  For \acronym{ST} ??
}

\references{
  Arellano-Valle, R. B., and Azzalini, A. (2008).
  The centred parametrization for the multivariate skew-normal distribution.
  \emph{J.\ Multiv.\ Anal.} \bold{99}, 1362--1382.
  Corrigendum: vol.\,100 (2009), p.\,816.

  Azzalini, A. with the collaboration of Capitanio, A. (2014). 
  \emph{The Skew-Normal and Related Families}. 
  Cambridge University Press, IMS Monographs series.
}

\seealso{\code{\link{dsn}}, \code{\link{dmsn}}, \code{\link{dp2cp}}}

\examples{
infoE <- sn.infoUv(dp=c(0,1,5))
infoO <- sn.infoUv(cp=c(0,1,0.8), y=rsn(50, dp=c(0,1,5)))
#
data(wines)
X <- model.matrix(~ pH + wine, data=wines)
fit <- sn.mple(x=X, y=wines$alcohol)
infoE <- sn.infoUv(cp=fit$cp, x=X)
infoO <- sn.infoUv(cp=fit$cp, x=X, y=wines$alcohol)
}
\keyword{distribution}