Commit 53df5e91 authored by Eduardo E. R. Junior's avatar Eduardo E. R. Junior

Complementa e corrige documentação e retira offset de 'llcmp'

 - Retira a inclusão de offset na log-verossimilhança, pois a inclusão
   desse termo foi implementado inadequadamente. Incorporar offset no
   modelo COM-Poisson não é tão trivial.
 - Adéqua documentação seguindo os exemplos de 'pgnz' e 'gcnt' no
   ramo walmes.
parent 41719448
...@@ -102,37 +102,78 @@ convergencez <- function(model, tol = 1e-4, incremento = 10, ...@@ -102,37 +102,78 @@ convergencez <- function(model, tol = 1e-4, incremento = 10,
} }
#' @title Log-Verossimilhança do Modelo Conway-Maxwell-Poisson #' @title Log-Verossimilhança do Modelo Conway-Maxwell-Poisson
#' @description Calcula a log-verossimilhança de um modelo COM-Poisson
#' considerando os dados e as estimativas dos parâmetros informadas.
#' @details A função de log-verossimilhança toma a forma: \deqn{-Z - y *
#' \lambda - \nu \log{y!}}, onde \eqn{Z = \sum
#' \frac{\lambda^i}{(i!)^\nu}} e \eqn{\nu = \exp{\phi}}.
#' @param params Um vetor de parâmetros do modelo COM-Poisson. É
#' necessário que seja informado como primeiro elemento do vetor, o
#' valor de \eqn{\phi}. Os demais elementos são os \eqn{\beta}'s do
#' preditor linear \eqn{\lambda}.
#' @param y Um vetor de contagens, considerado como variável resposta.
#' @param X A matriz de delineamento do modelo.
#' @param offset Um vetor de valores a serem adicionados ao preditor
#' linear.
#' @param sumto Número de incrementos a serem considerados para a soma
#' da constante normalizadora. Como padrão, o número de incrementos
#' é o valor inteiro de \eqn{(\max y)^1.2}.
#' @return O valor da log-verossimilhança do modelo
#' Conway-Maxwell-Poisson com os parâmetros e dados informados.
#' @author Eduardo E. R. Junior, \email{edujrrib@gmail.com} #' @author Eduardo E. R. Junior, \email{edujrrib@gmail.com}
#' @seealso \code{\link[bbmle]{mle2}}
#' @export #' @export
#' @description Calcula a log-verossimilhança de um modelo de regressão
#' para o parâmetro \eqn{\lambda} considerando as respostas de
#' contagem (y), condicionadas as suas covariáveis (X), distribuídas
#' conforme modelo COM-Poisson.
#' @details A função de log-verossimilhança da COM-Poisson, na
#' parametrização de modelo de regresssão é:
#'
#' \deqn{\ell(\beta, \nu, y) =
#' \sum_{i=1}^{n} y_i \log(\lambda_i) - \nu \sum_{i=1}^{n}\log(y!)
#' - \sum_{i=1}^{n} \log(Z(\lambda_i, \nu))}
#'
#' em que (i) \eqn{\lambda_i = \exp(X_i \beta)}, no modelo de regressão
#' COM-Poisson um preditor linear é ligado à \eqn{\lambda} por meio
#' da função de ligação log. Note que não estamos modelando
#' diretamente a média, assim as estimativas dos parâmetros
#' \eqn{\beta} não tem a mesma interpretação dos modelos Poisson,
#' por exemplo. Contudo, os sinais desses parâmetros indicam efeitos
#' de acréscimo ou descréscimo nas contagens médias.
#' (ii) \eqn{\nu} é o parâmetro de dispersão que indica equi, sub ou
#' superdispersão das contagens y. Sendo \eqn{nu = 1} o caso de
#' equidispersão, \eqn{0 \leq \nu < 1} superdispersão e \eqn{\nu >
#' 1} subdispersão. Vale ressaltar que a variância \eqn{V(Y)} não
#' tem expressão fechada e não é definada unicamente por \eqn{\nu}.
#' (iii) \eqn{Z(\lambda_i, \nu)} é a constante de normalização definida
#' por \deqn{\sum_{j=0}^{\infty} \frac{\lambda_i^j}{(j!)^\nu}}. Note
#' que são cálculadas n constantes Z. Nesta implementação o número
#' de incrementos considerados para cálculo dessas constantes é
#' definido por \code{sumto}, o mesmo número de incrementos é
#' considerado para o cálculo de todas as contantes. Uma verificação
#' pós ajuste da escolha de \code{sumto} pode ser realizada a partir
#' de \code{\link[MRDCr]{convergencez}}.
#'
#' Nesta parametrização o modelo COM-Poisson tem como casos particulares
#' os modelos Poisson quando \eqn{\nu = 1}, Bernoulli quando
#' \eqn{\nu \rightarrow \infty} (ou o modelo logístico considerando
#' modelos de regressão) e Geométrico quando \eqn{\nu = 0} e
#' \eqn{\lambda < 1}.
#'
#' Para que não seja necessário restringir o algoritmo de maximização da
#' log-verossimilhança, a função foi implementada reparametrizando o
#' parâmetro \eqn{\nu} para \eqn{\log(\phi)}. Assim o parâmetro
#' estimado será \eqn{\phi} que tem suporte nos reais, assim como o
#' vetor \eqn{\beta}.
#' @param params Um vetor de parâmetros do modelo COM-Poisson. O
#' primeiro elemento desse vetor deve ser o parâmetro de dispersão
#' do modelo, \eqn{\phi}, os restantes são os parâmetros
#' \eqn{\beta}'s associados ao preditor linear em \eqn{\lambda}.
#' @param y Um vetor com variável dependente do modelo, resposta do tipo
#' contagem.
#' @param X A matriz de delineamento correspondente ao modelo linear
#' ligado à \eqn{\lambda} pela função de ligação log. A matriz do
#' modelo pode ser construída com a função
#' \code{\link[stats]{model.matrix}}.
#' @param sumto Número de incrementos a serem considerados para a
#' cálculo das constantes normalizadoras. Como padrão, o número de
#' incrementos é o valor inteiro de \eqn{(\max y)^1.5}, porém esse
#' valor padrão não é ótimo. Uma avaliação da escolha desse
#' argumento, pós ajuste pode ser realizada via
#' \code{\link[MRDCr]{convergencez}}.
#' @return O negativo da log-verossimilhança do modelo
#' Conway-Maxwell-Poisson com os parâmetros e dados informados.
#' @seealso \code{\link[bbmle]{mle2}}
llcmp <- function(params, y, X, offset = NULL, llcmp <- function(params, y, X, sumto = ceiling(max(y)^1.2)){
sumto = ceiling(max(y)^1.5)){
##------------------------------------------- ##-------------------------------------------
betas <- params[-1] betas <- params[-1]
phi <- params[1] phi <- params[1]
nu <- exp(phi) nu <- exp(phi)
##------------------------------------------- ##-------------------------------------------
if (is.null(offset)) offset <- 0 Xb <- X %*% betas
Xb <- X %*% betas + offset
##------------------------------------------- ##-------------------------------------------
## Obtendo a constante normatizadora Z. ## Obtendo a constante normatizadora Z.
i <- 0:sumto i <- 0:sumto
......
...@@ -4,37 +4,79 @@ ...@@ -4,37 +4,79 @@
\alias{llcmp} \alias{llcmp}
\title{Log-Verossimilhança do Modelo Conway-Maxwell-Poisson} \title{Log-Verossimilhança do Modelo Conway-Maxwell-Poisson}
\usage{ \usage{
llcmp(params, y, X, offset = NULL, sumto = ceiling(max(y)^1.2)) llcmp(params, y, X, sumto = ceiling(max(y)^1.2))
} }
\arguments{ \arguments{
\item{params}{Um vetor de parâmetros do modelo COM-Poisson. É \item{params}{Um vetor de parâmetros do modelo COM-Poisson. O
necessário que seja informado como primeiro elemento do vetor, o primeiro elemento desse vetor deve ser o parâmetro de dispersão
valor de \eqn{\phi}. Os demais elementos são os \eqn{\beta}'s do do modelo, \eqn{\phi}, os restantes são os parâmetros
preditor linear \eqn{\lambda}.} \eqn{\beta}'s associados ao preditor linear em \eqn{\lambda}.}
\item{y}{Um vetor de contagens, considerado como variável resposta.} \item{y}{Um vetor com variável dependente do modelo, resposta do tipo
contagem.}
\item{X}{A matriz de delineamento do modelo.} \item{X}{A matriz de delineamento correspondente ao modelo linear
ligado à \eqn{\lambda} pela função de ligação log. A matriz do
modelo pode ser construída com a função
\code{\link[stats]{model.matrix}}.}
\item{offset}{Um vetor de valores a serem adicionados ao preditor \item{sumto}{Número de incrementos a serem considerados para a
linear.} cálculo das constantes normalizadoras. Como padrão, o número de
incrementos é o valor inteiro de \eqn{(\max y)^1.5}, porém esse
\item{sumto}{Número de incrementos a serem considerados para a soma valor padrão não é ótimo. Uma avaliação da escolha desse
da constante normalizadora. Como padrão, o número de incrementos argumento, pós ajuste pode ser realizada via
é o valor inteiro de \eqn{(\max y)^1.2}.} \code{\link[MRDCr]{convergencez}}.}
} }
\value{ \value{
O valor da log-verossimilhança do modelo O negativo da log-verossimilhança do modelo
Conway-Maxwell-Poisson com os parâmetros e dados informados. Conway-Maxwell-Poisson com os parâmetros e dados informados.
} }
\description{ \description{
Calcula a log-verossimilhança de um modelo COM-Poisson Calcula a log-verossimilhança de um modelo de regressão
considerando os dados e as estimativas dos parâmetros informadas. para o parâmetro \eqn{\lambda} considerando as respostas de
contagem (y), condicionadas as suas covariáveis (X), distribuídas
conforme modelo COM-Poisson.
} }
\details{ \details{
A função de log-verossimilhança toma a forma: \deqn{-Z - y * A função de log-verossimilhança da COM-Poisson, na
\lambda - \nu \log{y!}}, onde \eqn{Z = \sum parametrização de modelo de regresssão é:
\frac{\lambda^i}{(i!)^\nu}} e \eqn{\nu = \exp{\phi}}.
\deqn{\ell(\beta, \nu, y) =
\sum_{i=1}^{n} y_i \log(\lambda_i) - \nu \sum_{i=1}^{n}\log(y!)
- \sum_{i=1}^{n} \log(Z(\lambda_i, \nu))}
em que (i) \eqn{\lambda_i = \exp(X_i \beta)}, no modelo de regressão
COM-Poisson um preditor linear é ligado à \eqn{\lambda} por meio
da função de ligação log. Note que não estamos modelando
diretamente a média, assim as estimativas dos parâmetros
\eqn{\beta} não tem a mesma interpretação dos modelos Poisson,
por exemplo. Contudo, os sinais desses parâmetros indicam efeitos
de acréscimo ou descréscimo nas contagens médias.
(ii) \eqn{\nu} é o parâmetro de dispersão que indica equi, sub ou
superdispersão das contagens y. Sendo \eqn{nu = 1} o caso de
equidispersão, \eqn{0 \leq \nu < 1} superdispersão e \eqn{\nu >
1} subdispersão. Vale ressaltar que a variância \eqn{V(Y)} não
tem expressão fechada e não é definada unicamente por \eqn{\nu}.
(iii) \eqn{Z(\lambda_i, \nu)} é a constante de normalização definida
por \deqn{\sum_{j=0}^{\infty} \frac{\lambda_i^j}{(j!)^\nu}}. Note
que são cálculadas n constantes Z. Nesta implementação o número
de incrementos considerados para cálculo dessas constantes é
definido por \code{sumto}, o mesmo número de incrementos é
considerado para o cálculo de todas as contantes. Uma verificação
pós ajuste da escolha de \code{sumto} pode ser realizada a partir
de \code{\link[MRDCr]{convergencez}}.
Nesta parametrização o modelo COM-Poisson tem como casos particulares
os modelos Poisson quando \eqn{\nu = 1}, Bernoulli quando
\eqn{\nu \rightarrow \infty} (ou o modelo logístico considerando
modelos de regressão) e Geométrico quando \eqn{\nu = 0} e
\eqn{\lambda < 1}.
Para que não seja necessário restringir o algoritmo de maximização da
log-verossimilhança, a função foi implementada reparametrizando o
parâmetro \eqn{\nu} para \eqn{\log(\phi)}. Assim o parâmetro
estimado será \eqn{\phi} que tem suporte nos reais, assim como o
vetor \eqn{\beta}.
} }
\author{ \author{
Eduardo E. R. Junior, \email{edujrrib@gmail.com} Eduardo E. R. Junior, \email{edujrrib@gmail.com}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment