covid19br · marfcg · Sep 10, 2024
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: nowcaster
 Title: Nowcaster
-Version: 0.2.3
+Version: 0.2.2
 Authors@R: c(
     person("Rafael", "Lopes", , "[email protected]", role = c("aut", "cre"), 
     comment = c(ORCID = "0000-0002-9416-6145")),
@@ -11,7 +11,7 @@ Description: Nowcaster is a package wrapping statistical models to estimate not
 License: GPL (>= 3)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.1
 URL: https://covid19br.github.io/nowcaster
 BugReports: https://github.com/covid19br/nowcaster/issues
 Suggests: 

diff --git a/vignettes/articles/dados_estruturados.Rmd b/vignettes/articles/dados_estruturados.Rmd
@@ -0,0 +1,156 @@
+---
+title: "Dados estruturados"
+output: rmarkdown::html_vignette
+author: "Rafael Lopes & Leonardo Bastos"
+vignette: >
+  %\VignetteIndexEntry{Structured data}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r echo=FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  warning = F,
+  message = F,
+  echo = T
+)
+```
+
+Como no "Ponto de partida", começamos carregando o pacote e seus dados lazy, assim:
+
+```{r data-bh}
+library(nowcaster)
+# Loading Belo Horizonte SARI dataset
+data(sragBH)
+```
+
+## Dados não estruturados
+
+O exemplo "Get Started" é uma estimativa de dados não estruturados. Aqui, fornecemos uma descrição mais detalhada desse tipo de dado e como ele pode influenciar a estimativa de nowcasting.
+
+Agora chamamos a função de nowcasting. Por padrão, ela está parametrizada para pegar os dados e fazer a estimativa com uma forma de dados não estruturada. A estimativa ajusta uma distribuição binomial negativa, $NegBinom(\lambda_{t,d},\phi)$, para a contagem de casos no tempo $t$ com atraso $d$, onde $\phi$ é o parâmetro de dispersão. A taxa $\lambda_{t,d}$ é parametrizada em um formato log-linear por um termo constante, somado a efeitos aleatórios estruturados de atraso e efeitos aleatórios estruturados de tempo. Assim, o modelo é dado por:
+
+$$\begin{equation}
+Y_{t,d} \sim NegBinom(\lambda_{t,d}, \phi), \\
+\log(\lambda_{t,d}) = \alpha + \beta_t + \gamma_d, \\
+t=1,2,\ldots,T, \\ d=1,2,\ldots,D,
+\end{equation}$$
+
+onde o intercepto $\alpha$ segue uma distribuição Gaussiana com uma variância muito grande, $beta_t$ segue um passeio aleatório de segunda ordem com precisão $\tau_\beta$, e $\gamma_d$ é um passeio aleatório de primeira ordem com precisão $\tau_\gamma$. O modelo é então completado pelas distribuições a priori padrão do INLA para $\phi$, $\tau_\beta$, e $\tau_\gamma$. Veja as páginas de ajuda do INLA para nbinom, rw1 e rw2.
+
+A chamada da função é simples, ela simplesmente precisa de um conjunto de dados como entrada, aqui o LazyData carregado no namespace do pacote. A função tem 3 parâmetros obrigatórios: `dataset` para passar o conjunto de dados a ser usado no nowcasting, `date_onset` para passar o nome da coluna que contém a data de início dos sintomas e `date_report` que passa o nome da coluna com a data de notificação dos casos. Aqui, essas colunas são "DT_SIN_PRI" e "DT_DIGITA", respectivamente.
+
+```{r no_age}
+nowcasting_bh_no_age <- nowcasting_inla(dataset = sragBH, 
+                                        date_onset = DT_SIN_PRI, 
+                                        date_report = DT_DIGITA)
+head(nowcasting_bh_no_age$total)
+```
+
+Essa chamada retornará apenas a estimativa de nowcasting e seu Intervalo de Confiança (IC) para dois diferentes Intervalos de Confiança, `LIb` e `LSb` são o IC máximo e mínimo, respectivamente, com credibilidade de 50%, e `LI` e `LS` são o IC máximo e mínimo, respectivamente, com credibilidade de 95%.
+
+`nowcasting_inla` tem a opção de retornar a curva para quando a estimativa de nowcasting foi definida no intervalo de ação do modelo. Se o parâmetro `data.by.week` estiver marcado como `TRUE`, ele retornará no segundo elemento da lista de saída os dados resumidos por semana.
+
+```{r no_age_data}
+nowcasting_bh_no_age <- nowcasting_inla(dataset = sragBH, 
+                                        date_onset = DT_SIN_PRI, 
+                                        date_report = DT_DIGITA, 
+                                        data.by.week = T)
+head(nowcasting_bh_no_age$data)
+```
+
+Esse elemento contém as contagens de casos pelo número de dias de atraso. Isso é conhecido como o triângulo de atraso. Se organizarmos o número de dias de atraso contra a data de início dos primeiros sintomas, podemos ver o padrão de atraso para os casos.  
+
+```{r delay-triangle}
+library(dplyr)
+
+data_triangle <- nowcasting_bh_no_age$data |>
+  rename(dt_event = date_onset) |>
+  filter(Delay < 15) |> 
+  arrange(Delay)
+
+table(data_triangle$dt_event, 
+                     data_triangle$Delay, 
+                     dnn = list("Date of Onset", "Delay"))
+```
+
+Nós apenas olhamos a quantidade de casos com 30 semanas de atraso ou menos, que é o atraso máximo padrão considerado na estimativa de nowcasting.
+
+Se esse elemento for agrupado e resumido pela data de início dos sintomas, aqui `DT_SIN_PRI`, obtém-se a curva epidemiológica observada. Para exemplificar isso, plotamos a estimativa e a curva epidemiológica juntas.
+
+```{r no_age_plot}
+library(ggplot2)
+
+data_by_week <- nowcasting_bh_no_age$data |>
+  dplyr::rename(dt_event = date_onset) |>
+  dplyr::group_by(dt_event) |> 
+  dplyr::reframe(
+    observed = n()
+  ) |>
+  dplyr::filter(dt_event >= max(dt_event)-270)
+
+nowcasting_bh_no_age$total |> 
+  filter(dt_event >= (max(dt_event)-270)) |> 
+  ggplot(aes(x = dt_event, y = Median, col = 'Nowcasting')) +
+  geom_line(data = data_by_week, 
+            aes(x = dt_event, y = observed, col = 'Observed'))+
+  geom_ribbon(aes(ymin = LI, ymax = LS, col = NA), alpha = 0.2, show.legend = F)+
+  geom_line()+
+  theme_bw()+
+  theme(legend.position = "bottom", axis.text.x = element_text(angle = 90)) +
+  scale_color_manual(values = c('grey50', 'black'), name = '')+
+  scale_x_date(date_breaks = '2 weeks', date_labels = '%V/%y', name = 'Date in Weeks')+
+  labs(x = '', y = 'Nº Cases')
+```
+
+
+## Dados estruturados por idade
+
+Para os dados estruturados, a função `nowcasting_inla()` ajusta novamente uma distribuição binomial negativa para a contagem de casos no tempo $t$ com atraso $d$. Diferentemente do caso não estruturado, o modelo agora inclui efeitos aleatórios para a distribuição do atraso e para a distribuição temporal, considerando cada classe etária escolhida pelo usuário para segmentar os dados. O modelo agora tem a seguinte forma:
+
+$$\begin{equation}Y_{t,d,a} \sim  NegBinom(\lambda_{t,d,a}, \phi), \\
+\log(\lambda_{t,d,a}) =  \alpha_a + \beta_{t,a} + \gamma_{d,a}, \\ \quad t=1,2,\ldots,T, \\ d=1,2,\ldots,D, \\ a=1,2,\ldots,A, \end{equation}$$
+
+onde cada classe etária, $a$, tem um intercepto $\alpha_a$ que segue uma distribuição Gaussiana com uma variância muito grande. Os efeitos aleatórios de tempo e idade, $\beta_{t,a}$,  seguem uma distribuição Gaussiana multivariada conjunta com componentes de variância separáveis: um termo Gaussiano independente para as classes etárias com precisão $\tau_{a,\beta}$ e um passeio aleatório de segunda ordem para o tempo com precisão $\tau_{\beta}$. Analogamente, os efeitos aleatórios de atraso-idade, $\gamma_{d,a}$, seguem uma distribuição Gaussiana multivariada conjunta com componentes de variância separáveis: um termo Gaussiano independente para as classes etárias com precisão $\tau_{a,\gamma}$ e um passeio aleatório de primeira ordem para o tempo com precisão $\tau_{\gamma}$. O modelo é então completado pelas distribuições a priori padrão do INLA para $\phi$, $\tau_{a,\beta}$, $\tau_{a,\gamma}$, $\tau_{\beta}$ e $\tau_\gamma$. Veja nbinom, iid, rw1 e rw2 na documentação do INLA.
+
+Este novo modelo corrige o atraso, levando em consideração os efeitos das faixas etárias e as interações de cada faixa etária entre o tempo e também o atraso. Agora o modelo precisa de uma sinalização indicando qual coluna do conjunto de dados será usada para segmentar os dados em faixas etárias e como essas faixas serão divididas. Isso é feito pelos parâmetros `age_col` e `bins_age`. Passamos três parâmetros adicionais, `data.by.week` para retornar a curva epidemiológica fora da janela de ação da estimativa de nowcasting e `return.age` para informar que desejamos um resultado de nowcasting de duas maneiras: a estimativa total agregada e a estimativa estratificada por idade. A chamada da função tem a seguinte forma:
+
+```{r nowcasting}
+nowcasting_bh_age <- nowcasting_inla(dataset = sragBH, 
+                                   bins_age = "10 years",
+                                   data.by.week = T, 
+                                   date_onset = DT_SIN_PRI, 
+                                   date_report = DT_DIGITA,
+                                   age_col = Idade)
+```
+
+Cada uma das estimativas retornadas pelo `nowcasting_inla` tem a mesma forma que no caso não estruturado. Nas estimativas de nowcasting, ele retorna um data.frame com a mediana posterior e os intervalos críveis de 50% e 95%, (`LIb` e `LSb`) e (`LI` e `LS`), respectivamente.
+
+```{r plot}
+library(ggplot2)
+
+dados_by_week <- nowcasting_bh_age$data |> 
+  dplyr::rename(dt_event = date_onset) |>
+  dplyr::group_by(dt_event) |> 
+  dplyr::reframe(
+    observed = n()
+  ) |>
+  dplyr::filter(dt_event >= max(dt_event)-270)
+
+
+nowcasting_bh_age$total |> 
+  ggplot()+
+  geom_line(aes(x = dt_event, y = Median, col = 'Nowcasting'))+
+  geom_line(data = dados_by_week, 
+            aes(x = dt_event, y = observed, col = "Observed"))+
+  geom_ribbon(aes(x = dt_event, y = Median,
+                  ymin = LI, ymax = LS), alpha = 0.2, show.legend = F)+
+  theme_bw()+
+  theme(legend.position = "bottom", axis.text.x = element_text(angle = 90))+
+  scale_color_manual(values = c('grey50', 'black'), name = '')+
+  scale_x_date(date_breaks = '2 weeks', date_labels = '%V/%y', name = 'Date in Weeks')+
+  labs(x = '', y = 'Nº Cases')
+```
+
diff --git a/vignettes/articles/nowcasting_importance.Rmd b/vignettes/articles/nowcasting_importance.Rmd
@@ -69,16 +69,14 @@ Before we see the result of the nowcasting estimate we take a look on intermedia
 From the data in weekly format we mount the counts of cases by the amount of delay. By tabling the delay amount against the data of onset of first symptoms, to see the pattern of the delay for the cases.  
 
 ```{r delay-triangle}
-data_triangle <- nowcasting_bh_no_age$data |> 
-  filter(delay < 30) |> 
-  arrange(delay) %>% select(-Time)
-
-# delay_triangle<-table(data_triangle$dt_event, 
-#                       data_triangle$delay, 
-#                       dnn = list("Date of Onset", "Delay"))
-
-data_triangle %>% 
-  tidyr::spread(key = delay, value = Y)
+data_triangle <- nowcasting_bh_no_age$data |>
+  rename(dt_event = date_onset) |>
+  filter(Delay < 15) |> 
+  arrange(Delay)
+
+table(data_triangle$dt_event, 
+                     data_triangle$Delay, 
+                     dnn = list("Date of Onset", "Delay"))
 ```
 
 We just look at the amount of cases with 30 weeks of delay or less, it is the default maximum delay considered at nowcasting estimation. It can be changed by the parameter `Dmax`.
@@ -89,10 +87,12 @@ If this element is grouped by and summarized by the onset of symptoms date, here
 library(ggplot2)
 
 dados_by_week <- nowcasting_bh_no_age$data |> 
+  dplyr::rename(dt_event = date_onset) |>
   dplyr::group_by(dt_event) |> 
   dplyr::reframe(
-    observed = sum(Y, na.rm = T)
-  )
+    observed = n()
+  ) |>
+  dplyr::filter(dt_event >= max(dt_event)-270)
 
 nowcasting_bh_no_age$total |> 
   ggplot(aes(x = dt_event, y = Median, 

diff --git a/vignettes/articles/structured_data.Rmd b/vignettes/articles/structured_data.Rmd
@@ -65,17 +65,14 @@ This element it is the counts of cases by the amount of delay. It is known as th
 ```{r delay-triangle}
 library(dplyr)
 
-data_triangle <- nowcasting_bh_no_age$data |> 
-  filter(delay < 30) |> 
-  arrange(delay) %>% select(-Time)
-
-# delay_triangle<-table(data_triangle$dt_event, 
-#                       data_triangle$delay, 
-#                       dnn = list("Date of Onset", "Delay"))
-
-data_triangle %>% 
-  tidyr::spread(key = delay, value = Y)
-
+data_triangle <- nowcasting_bh_no_age$data |>
+  rename(dt_event = date_onset) |>
+  filter(Delay < 30) |> 
+  arrange(Delay)
+
+delay_triangle <- table(data_triangle$dt_event, 
+                     data_triangle$Delay, 
+                     dnn = list("Date of Onset", "Delay"))
 ```
 
 We just look at the amount of cases with 30 weeks of delay or less, it is the default maximum delay considered at nowcasting estimation.  
@@ -85,10 +82,11 @@ If this element is groped by and summarized by the onset of symptoms date, here
 ```{r no_age_plot}
 library(ggplot2)
 
-data_by_week <- nowcasting_bh_no_age$data |> 
+data_by_week <- nowcasting_bh_no_age$data |>
+  dplyr::rename(dt_event = date_onset) |>
   dplyr::group_by(dt_event) |> 
   dplyr::reframe(
-    observed = sum(Y, na.rm = T)
+    observed = n()
   ) |>
   dplyr::filter(dt_event >= max(dt_event)-270)
 
@@ -133,9 +131,10 @@ Each of the estimates returned by `nowcasting_inla` has the same form as in the
 library(ggplot2)
 
 dados_by_week <- nowcasting_bh_age$data |> 
+  dplyr::rename(dt_event = date_onset) |>
   dplyr::group_by(dt_event) |> 
   dplyr::reframe(
-    observed = sum(Y, na.rm = T)
+    observed = n()
   ) |>
   dplyr::filter(dt_event >= max(dt_event)-270)
 

diff --git a/vignettes/nowcaster.Rmd b/vignettes/nowcaster.Rmd
@@ -55,6 +55,7 @@ library(ggplot2)
 library(dplyr)
 
 dados_by_week <- nowcasting_bh_no_age$data |> 
+  dplyr::rename(dt_event = date_onset) |>
   dplyr::group_by(dt_event) |> 
   dplyr::reframe(
     observed = sum(Y, na.rm = T)

diff --git a/vignettes/nowcaster_ptbr.Rmd b/vignettes/nowcaster_ptbr.Rmd
@@ -0,0 +1,109 @@
+---
+title: "Ponto de partida"
+output: rmarkdown::html_vignette
+author: "Rafael Lopes & Leonardo Bastos"
+vignette: >
+  %\VignetteIndexEntry{Get Started}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r echo=FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>", 
+  warning = F, 
+  message = F, 
+  echo = T
+)
+```
+
+## Primeiro exemplo com LazyData
+
+Quando o pacote é carregado ele fornece um arquivo LazyData, `sariBH`, que são registros anonimizados de Síndrome Respiratória Aguda Grave notificados in the city of Belo Horizonte, desde março de 2020 até abril de 2022. Para carregá-lo, basicamente escreva:
+
+```{r data-bh}
+library(nowcaster)
+# Loading Belo Horizonte SARI dataset
+data(sragBH)
+```
+
+E damos uma olhada nos dados:
+
+```{r lookup}
+head(sragBH)
+```
+
+É um data.frame com 7 variáveis e 65.404 observações. Vamos utilizar apenas as duas primeiras colunas, "DT_SIN_PRI" (data de início de sintomas) e "DT_DIGITA" (data de digitação), bem como a coluna "Idade" (idade em anos) para fazer nowcasting com estrutura etária.
+
+A chamada da função é simples, ela simplesmente precisa de um conjunto de dados como entrada, aqui o `LazyData` disponível no pacote. A função tem 3 parâmetros obrigatórios, `dataset` para o fornecimento do conjunto de dados a ser usado no nowcasting, `date_onset` para indicar o nome da coluna que contém a data de início dos sintomas, e `date_report` que indica o nome da coluna com a data de digitação dos casos. Aqui, essas colunas são "DT_SIN_PRI" e "DT_DIGITA", respectivamente.
+
+```{r no_age}
+nowcasting_bh_no_age <- nowcasting_inla(dataset = sragBH, 
+                                        date_onset = "DT_SIN_PRI", 
+                                        date_report = "DT_DIGITA", 
+                                        data.by.week = T)
+head(nowcasting_bh_no_age$total)
+```
+
+Essa chamada retornará, no primeiro elemento, a estimativa de nowcasting e seu Intervalo de Confiança (CI) para dois diferentes intervalos de credibilidade. `LIb` e `LSb` são o CI máximo e mínimo, respectivamente, com credibilidade de 50%, e `LI` e `LS` são o CI máximo e mínimo, respectivamente, com credibilidade de 95%.
+
+No segundo elemento, ela retorna os dados a serem agrupados e resumidos para gerar a curva epidêmica. Podemos dar uma olhada nesse elemento.
+
+```{r epi-curve-plot}
+library(ggplot2)
+library(dplyr)
+
+dados_by_week <- nowcasting_bh_no_age$data |> 
+  rename(dt_event = date_onset) |>
+  dplyr::group_by(dt_event) |> 
+  dplyr::reframe(
+    observed = n()
+  ) |>
+  dplyr::filter(dt_event >= max(dt_event)-270)
+
+dados_by_week |> 
+  ggplot()+
+  geom_line(data = dados_by_week, 
+            aes(dt_event, 
+                y = observed, 
+                col = 'Observed'))+
+  theme_bw()+
+  theme(legend.position = "bottom", 
+        axis.text.x = element_text(angle = 90)) +
+  scale_color_manual(values = c('grey50', 'black'), 
+                     name = '')+
+  scale_x_date(date_breaks = '2 weeks', 
+               date_labels = '%V/%y', 
+               name = 'Date in Weeks')+
+  labs(x = '', 
+       y = 'Nº Cases')
+```
+
+Após esse elemento ser agrupado e resumido pela data de início dos sintomas, aqui `DT_SIN_PRI`, obtém-se a curva epidemiológica observada. Para exemplificar como a estimativa se compara com a curva observada, plotamos a estimativa e a curva epidemiológica juntas.
+
+```{r no_age_plot}
+
+nowcasting_bh_no_age$total |> 
+  ggplot(aes(x = dt_event, y = Median, 
+             col = 'Nowcasting')) +
+  geom_line(data = dados_by_week, 
+            aes(y = observed, 
+                col = 'Observed'))+
+  geom_ribbon(aes(ymin = LI, ymax = LS, col = NA), 
+              alpha = 0.2, 
+              show.legend = F)+
+  geom_line()+
+  theme_bw()+
+  theme(legend.position = "bottom", 
+        axis.text.x = element_text(angle = 90)) +
+  scale_color_manual(values = c('grey50', 'black'), 
+                     name = '')+
+  scale_x_date(date_breaks = '2 weeks', 
+               date_labels = '%V/%y', 
+               name = 'Date in Weeks')+
+  labs(x = '', 
+       y = 'Nº Cases')
+```
+
+Este é um exemplo em que a estimativa foi feita sem considerar nenhum tipo de estrutura nos dados, que é a primeira suposição para o nowcasting.