---
title: "Agrupamento não supervisionado de documentos"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Agrupamento não supervisionado de documentos}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo       = TRUE,
  eval       = TRUE,
  collapse   = TRUE,
  comment    = "#>",
  fig.width  = 8.5,
  fig.height = 5.5,
  fig.align  = "center",
  out.width  = "100%",
  dpi        = 140,
  message    = FALSE,
  warning    = FALSE
)
library(acR)
library(ggplot2)
library(dplyr)
library(tidyr)
set.seed(42)
```

## Por que agrupar documentos?

Nem toda pesquisa começa com um livro de códigos pronto. Às vezes você
tem centenas de discursos, proposições ou entrevistas e precisa
**descobrir tipologias latentes** — antes de rotular, antes de contar,
antes de qualquer LLM. É aí que entra o *clustering*: um algoritmo lê a
matriz de vocabulário e devolve **uma etiqueta por documento**, agrupando
o que se parece por co-ocorrência de termos.

## 1. Três famílias, três leituras teóricas

Antes de rodar qualquer código, vale entender que "descobrir grupos em
texto" é uma família de técnicas com **três leituras teóricas
diferentes**, cada uma respondendo a uma pergunta distinta:

### 1.1 Hard clustering (o que esta vignette faz)

Cada documento pertence a **um único grupo**. A saída é uma etiqueta
`cluster ∈ {1, 2, …, k}`. É o mundo do `ac_cluster_documents()`:
hierárquico (`hclust`), `kmeans` e `pam`.

* **Modelo mental:** cada documento é *do* tipo A ou *do* tipo B.
* **Pergunta:** "que tipologias existem no corpus?"
* **Boa para:** amostragem estratificada, dendrogramas metodológicos,
  triagem antes de codificação qualitativa, criação de estratos para
  análise comparativa.

### 1.2 Soft (fuzzy) clustering

Cada documento tem um **vetor de graus de pertencimento** que soma 1
entre `k` clusters. Um documento "60% tipo A, 40% tipo B" existe. Fuzzy
c-means (`e1071::cmeans()`) e misturas gaussianas (`mclust`) são os
exemplos clássicos.

* **Modelo mental:** documentos são pontos numa **zona cinzenta** entre
  protótipos.
* **Pergunta:** "quão típico deste grupo cada documento é?"
* **Boa para:** identificar documentos *fronteiriços* (bons candidatos
  a revisão humana), ranquear documentos por representatividade dentro
  de um grupo.

### 1.3 Modelos de tópicos (LDA)

Cada documento é uma **mistura probabilística de tópicos**, e cada
tópico é uma **distribuição sobre palavras**. É o mundo do `ac_lda()`:
o output é uma matriz **γ (gamma)** de probabilidades documento × tópico
e uma matriz **β (beta)** de probabilidades tópico × palavra.

* **Modelo mental:** o autor amostrou tópicos com certas proporções e,
  para cada palavra, sorteou um tópico e depois uma palavra dele.
* **Pergunta:** "que temas coexistem em cada documento e como eles se
  compõem?"
* **Boa para:** discurso parlamentar, artigos jornalísticos, textos
  longos com múltiplos temas por documento.

### 1.4 Como escolher?

| Se você quer…                                                        | Use                             |
|----------------------------------------------------------------------|---------------------------------|
| Uma partição limpa, uma etiqueta por documento                       | Hard clustering (esta vignette) |
| Detectar documentos fronteiriços, quão típico de um grupo cada é     | Soft clustering (fuzzy c-means) |
| Descobrir temas que se **misturam** em cada texto                    | LDA (veja `vignette("lda")`)    |
| Rotular documentos com **categorias pré-definidas** por um pesquisador | LLM (veja `vignette("qualitativo-llm")`) |

Um bom pipeline muitas vezes **combina** essas técnicas: hard clustering
para triagem inicial, LDA para entender temas dentro de cada grupo, LLM
para codificar categorias teoricamente motivadas, revisão humana nos
documentos que caírem em fronteiras.

## 2. Um corpus de dois blocos

Para tornar o exemplo transparente, vamos construir um corpus com **dois
blocos temáticos** deliberadamente separados: democracia participativa
de um lado, economia de mercado do outro. O clustering deve, sem
supervisão, reencontrar essa divisão.

```{r corpus}
df <- data.frame(
  id = paste0("d", sprintf("%02d", 1:16)),
  tema_real = rep(c("democracia", "mercado"), each = 8),
  texto = c(
    "democracia participacao voto liberdade cidadania popular",
    "cidadania direitos participacao democracia representacao politica",
    "voto direitos liberdade cidadania soberania popular",
    "democracia voto participacao popular assembleia direta",
    "participacao social democracia direitos coletivos comunidade",
    "cidadania voto democracia representacao plural minorias",
    "liberdade participacao politica assembleia popular deliberacao",
    "democracia direta cidadania voto plebiscito referendo",
    "mercado economia eficiencia privatizacao competicao livre",
    "privatizacao mercado livre eficiencia produtividade lucro",
    "economia crescimento investimento mercado capital juros",
    "eficiencia mercado economia livre concorrencia produtividade",
    "mercado privado investimento economia lucro capital risco",
    "economia livre mercado eficiencia produtividade escala",
    "crescimento economico mercado investimento privatizacao abertura",
    "mercado competicao eficiencia lucro capital privado"
  ),
  stringsAsFactors = FALSE
)

corpus <- ac_corpus(df, text = texto, docid = id)
corpus
```

Guardei `tema_real` fora do corpus para poder validar depois: o
clustering **não vê** essa coluna; só o texto.

## 3. Ajuste em três linhas

```{r fit}
clust <- ac_cluster_documents(corpus)
clust
```

Os padrões cobrem 80% dos casos:

* **hclust + Ward.D2** — hierárquico, produz dendrograma interpretável.
* **TF-IDF** — palavras raras e discriminantes contam mais.
* **Distância cosseno** — o clássico em texto (invariante a tamanho de
  documento).
* **`k` automático por silhueta** — testa `k ∈ {2, …, 8}` e escolhe o
  melhor (requer pacote `cluster`).

## 4. Seis formas de olhar para o mesmo cluster

### 4.1 Dendrograma — a árvore das fusões

Mostra a ordem em que documentos foram unidos e a **altura** de cada
fusão. Cortes altos separam grupos sólidos; cortes baixos indicam
agrupamentos frouxos.

```{r plot-dendrogram, fig.height=5}
ac_plot_cluster(clust, kind = "dendrogram")
```

### 4.2 Projeção PCA — a geometria do corpus

Cada documento vira um ponto no plano das duas componentes principais.
Documentos com vocabulário parecido ficam próximos; a cor mostra a
divisão do algoritmo.

```{r plot-scatter, fig.height=5}
ac_plot_cluster(clust, kind = "scatter")
```

### 4.3 Mapa de calor — a assinatura da separação

Ordena os documentos pelo dendrograma e desenha a matriz de
dissimilaridade inteira. **Blocos escuros na diagonal** são o carimbo
de qualidade de um clustering bem-sucedido.

```{r plot-heatmap, fig.height=6}
ac_plot_cluster(clust, kind = "heatmap")
```

### 4.4 Termos mais distintivos por cluster

Este gráfico responde à pergunta que interessa depois de rodar o
modelo: **"o que cada grupo *fala* de diferente?"**. Juntamos a etiqueta
do cluster ao TF-IDF e mostramos os 8 termos mais fortes por grupo.

```{r plot-top-terms, fig.height=5.5}
tokens_com_cluster <- corpus |>
  ac_clean() |>
  ac_count() |>
  left_join(clust$assignments, by = "doc_id") |>
  group_by(cluster, token) |>
  summarise(n = sum(n), .groups = "drop") |>
  rename(doc_id = cluster) |>
  mutate(doc_id = paste0("Cluster ", doc_id))

tfidf_cluster <- ac_tf_idf(tokens_com_cluster)

top_por_cluster <- tfidf_cluster |>
  group_by(doc_id) |>
  slice_max(tf_idf, n = 8) |>
  ungroup() |>
  mutate(token = tidytext::reorder_within(token, tf_idf, doc_id))

ggplot(top_por_cluster, aes(tf_idf, token, fill = doc_id)) +
  geom_col(show.legend = FALSE) +
  tidytext::scale_y_reordered() +
  facet_wrap(~ doc_id, scales = "free") +
  scale_fill_manual(values = ac_palette(clust$k)) +
  labs(
    title    = "Termos mais distintivos por cluster (TF-IDF)",
    subtitle = "O 'o que cada grupo fala de diferente'",
    x = "TF-IDF", y = NULL,
    caption = "acR • pos-clustering"
  ) +
  theme_ac()
```

### 4.5 Curva de silhueta — escolhendo `k` visualmente

Quando o `k` automático parecer arbitrário, olhe para a curva. A
silhueta média de cada `k` diz o quão *coeso* é o agrupamento naquele
número de grupos. Picos claros são bons; platôs indicam que a divisão
seguinte é quase tão boa quanto.

```{r plot-silhouette, fig.height=4.5}
if (requireNamespace("cluster", quietly = TRUE)) {
  ks   <- 2:6
  sils <- vapply(ks, function(k_try) {
    ac_cluster_documents(corpus, k = k_try)$silhouette
  }, numeric(1))

  df_sil <- data.frame(k = ks, silhueta = sils)

  ggplot(df_sil, aes(k, silhueta)) +
    geom_line(color = ac_palette(1), linewidth = 1.1) +
    geom_point(size = 3.5, color = ac_palette(1)) +
    geom_point(
      data = df_sil[which.max(df_sil$silhueta), ],
      aes(k, silhueta),
      size = 6, shape = 21, stroke = 1.4,
      fill = "white", color = ac_palette(1)
    ) +
    scale_x_continuous(breaks = ks) +
    labs(
      title    = "Silhueta media por numero de grupos",
      subtitle = "Circulo vazado = k escolhido automaticamente",
      x = "k (numero de clusters)", y = "Silhueta media"
    ) +
    theme_ac()
}
```

### 4.6 Hard vs. soft — comparando com LDA

Este é o gráfico mais **didático** da vignette: mostra lado a lado como
hard clustering e LDA veem o mesmo corpus. À esquerda, cada linha do
heatmap é um documento e cada coluna, o cluster ao qual ele pertence
(binário: 0 ou 1). À direita, cada linha é o mesmo documento e cada
coluna é a proporção γ do tópico LDA — **um gradiente contínuo**.

```{r plot-lda-vs-cluster, fig.height=5.5}
lda_fit <- ac_lda(corpus, k = 2, seed = 42)

hard <- clust$assignments |>
  mutate(valor = 1, tipo = paste0("Cluster ", cluster)) |>
  select(doc_id, tipo, valor)

soft <- lda_fit$documents |>
  mutate(tipo = paste0("Topico ", topic), valor = gamma) |>
  select(doc_id, tipo, valor)

plot_df <- bind_rows(
  hard |> mutate(painel = "Hard clustering\n(1 = pertence)"),
  soft |> mutate(painel = "LDA (soft)\n(gamma = proporcao)")
) |>
  mutate(doc_id = factor(doc_id, levels = rev(sort(unique(doc_id)))))

ggplot(plot_df, aes(tipo, doc_id, fill = valor)) +
  geom_tile(color = "white") +
  facet_wrap(~ painel, scales = "free_x") +
  scale_fill_gradient(low = "#F1F5F9", high = ac_palette(1), name = "Valor") +
  labs(
    title    = "Hard vs. soft: a mesma pergunta, duas respostas",
    subtitle = "Cluster da uma etiqueta; LDA da proporcoes por documento",
    x = NULL, y = NULL,
    caption = "acR • ac_cluster_documents vs. ac_lda"
  ) +
  theme_ac() +
  theme(axis.text.x = element_text(angle = 30, hjust = 1))
```

Note como o hard clustering sempre pinta uma célula por linha (o
documento é *do* grupo A ou *do* grupo B), enquanto o LDA distribui
massa — a maior parte dos documentos é ~90% de um tópico, mas alguns
ficam repartidos. **É a mesma tipologia latente, expressa em duas
métricas diferentes.**

## 5. Validando contra a verdade

Como guardamos `tema_real` fora do modelo, dá para conferir a acurácia
da partição:

```{r validacao}
validacao <- clust$assignments |>
  mutate(tema_real = df$tema_real[match(doc_id, df$id)]) |>
  count(tema_real, cluster)
validacao
```

Se o algoritmo separou corretamente, cada `tema_real` deve concentrar-se
num único cluster (permutação de rótulos é esperada — o clustering não
sabe qual grupo é "democracia" ou "mercado", só que são diferentes).

## 6. Escolhendo o método

`ac_cluster_documents()` aceita três algoritmos:

| Método    | Quando usar                                                             |
|-----------|-------------------------------------------------------------------------|
| `hclust`  | Padrão. Você quer dendrograma, ou não sabe `k` de antemão.              |
| `kmeans`  | Corpus grande (milhares de documentos), você já sabe `k`, quer rapidez. |
| `pam`     | Robusto a *outliers*; devolve medoides reais (documentos exemplares).   |

`pam` requer o pacote `cluster` instalado; os demais rodam com apenas o
`stats` base.

```{r kmeans, fig.height=4.5}
clust_km <- ac_cluster_documents(corpus, method = "kmeans", k = 2)
ac_plot_cluster(clust_km, kind = "scatter")
```

## 7. E depois? Integrando com o pipeline

Fluxo típico onde clustering é **etapa prévia**:

1. `ac_cluster_documents()` particiona o corpus em `k` grupos.
2. Amostre `n` documentos por cluster para leitura humana.
3. Use as leituras para escrever um **codebook inicial** com
   `ac_qual_codebook()`.
4. Aplique o codebook ao corpus inteiro com `ac_qual_code()`.
5. Se quiser refinar temas *dentro* de um cluster, rode `ac_lda()` só
   naquele subcorpus.

Isso reduz o custo cognitivo do primeiro contato com o corpus: em vez de
enfrentar centenas de documentos aleatórios, você lê um punhado de
exemplares de cada tipologia latente.

## Referências

* Blei, D. M., Ng, A. Y., & Jordan, M. I. (2003). Latent Dirichlet
  Allocation. *JMLR*, 3, 993–1022. — o paper original do LDA.
* Bezdek, J. C. (1981). *Pattern Recognition with Fuzzy Objective
  Function Algorithms*. Plenum. — fuzzy c-means.
* Kaufman, L. & Rousseeuw, P. J. (1990). *Finding Groups in Data*.
  Wiley. — PAM e silhueta.
* Manning, C., Raghavan, P. & Schütze, H. (2008). *Introduction to
  Information Retrieval*. Cambridge University Press. Cap. 16–17.
* Murtagh, F. & Legendre, P. (2014). Ward's hierarchical agglomerative
  clustering method: Which algorithms implement Ward's criterion?
  *Journal of Classification*, 31(3), 274–295.