Package 'acR'

Description

ac_build_dictionary() monta um dicionário no formato esperado por ac_dictionary() a partir de argumentos nomeados: cada argumento é uma categoria, e seu valor é o vetor de palavras daquela categoria.

Usage

ac_build_dictionary(...)

Arguments

Value

Lista nomeada de vetores de caracteres (um dicionário).

See Also

ac_dictionary(), ac_dictionary_import(), ac_dictionary_save()

Examples

dict <- ac_build_dictionary(
  positivo = c("bom", "ótimo", "excelente"),
  negativo = c("mau", "péssimo", "horrivel")
)
dict

Description

ac_ca() reduz uma tabela de contingência documento/grupo x termo a poucas dimensões, posicionando unidades e termos no mesmo espaço geométrico (Greenacre, 2007). Unidades próximas entre si têm perfis de vocabulário parecidos; termos próximos entre si são usados de forma parecida pelos grupos. É uma alternativa simples e determinística à Alocação de Dirichlet Latente (LDA, já disponível em ac_lda()) para visualizar associações entre vocabulário e grupos em duas dimensões: sem assumir um número de tópicos latentes.

Como ler o mapa. As coordenadas de unidades e termos são principais (mapa "simétrico"). Nesse mapa, distâncias entre unidades (e entre termos) aproximam distâncias qui-quadrado entre perfis, mas a distância entre uma unidade e um termo não tem interpretação direta (Greenacre, 2007, cap. 8-9). Leia a relação unidade-termo pela direção: um termo longe da origem e na mesma direção de um grupo é sobrerrepresentado nele; termos perto da origem têm perfil parecido com a média (pouco distintivos).

É útil, por exemplo, para visualizar como o vocabulário difere entre categorias de atendimento ao cliente, entre seções de um conjunto de notícias, ou entre partidos/períodos legislativos: qualquer situação em que se queira um "mapa" conjunto de grupos e das palavras que os caracterizam.

Implementação: SVD (base::svd()) sobre os resíduos padronizados de Pearson da tabela de contingência normalizada, no espírito do algoritmo clássico de Análise de Correspondência (Greenacre, 2007). Os sinais de cada dimensão são normalizados (a unidade com maior coordenada em valor absoluto é sempre positiva), para que o resultado seja determinístico entre execuções.

Usage

ac_ca(
  corpus,
  by = NULL,
  top_n = 50L,
  min_count = 5L,
  n_dim = 2L,
  drop_punct = TRUE
)

Arguments

Value

Lista de classe ac_ca com:

• row_coords: tibble com unit, dim1, dim2, ..., mass (massa/peso relativo da linha).

• col_coords: tibble com term, dim1, dim2, ..., mass.

• eigenvalues: autovalores (inércia) de cada dimensão.

• variance_explained: proporção da inércia total explicada por cada dimensão.

References

Greenacre, M. (2007). Correspondence Analysis in Practice (2nd ed.). Chapman and Hall/CRC.

See Also

ac_count(), ac_lda(), ac_plot_ca()

Examples

df <- data.frame(
  id = paste0("d", 1:6),
  texto = c(
    "entrega atrasada rastreio sumiu",
    "pedido atrasou muito, rastreio não atualiza",
    "produto com defeito, chegou quebrado",
    "veio quebrado, qualidade péssima",
    "atendimento excelente, resolveram rápido",
    "suporte educado e rápido, resolveu tudo"
  ),
  categoria = c("entrega", "entrega", "produto", "produto",
                 "atendimento", "atendimento"),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id, meta = categoria)

ca <- ac_ca(corpus, by = "categoria", min_count = 1)
ca$variance_explained

Description

ac_calibrate_tokens() mede, contra um Chat real, quantos tokens de entrada um conjunto de textos de amostra realmente consome, e devolve a razao caracteres/token observada – para usar como chars_per_token em ac_estimate_tokens() (ou como chars_per_token em ac_qual_code() / futuras funções que dependam da estimativa).

Faz uma chamada real ao modelo por texto de amostra (com uma mensagem mínima, para medir so o consumo de tokens de entrada), então usa poucos textos – o suficiente para calibrar, não uma amostra representativa de todo o corpus.

Usage

ac_calibrate_tokens(chat_factory, textos)

Arguments

Value

Número: a mediana de caracteres por token observada na amostra.

Examples

## Not run: 
chat_factory <- function(temperature, system_prompt) {
  ellmer::chat_openai(model = "gpt-4.1-mini", temperature = temperature,
                      system_prompt = system_prompt, echo = "none")
}
razao <- ac_calibrate_tokens(chat_factory, c("texto curto de teste.",
                                             "um texto um pouco mais longo de teste."))
coded <- ac_qual_code(corpus, cb, model = chat_factory)

## End(Not run)

Description

ac_chat_local() cria um Chat do ellmer apontando para um servidor local compativel com a API da OpenAI – LM Studio, llama.cpp (llama-server), vLLM, Ollama em modo OpenAI, etc. – sem exigir uma chave de API real.

Classificar com um modelo local (via ac_qual_code()) elimina o custo por token e mantem os documentos fora de qualquer rede externa, ao preco de gerência propria do servidor: tamanho de contexto, tempo de resposta e throughput passam a depender do hardware local. Use junto com checkpoint_dir e max_retries em ac_qual_code() para rodadas longas, e ac_estimate_tokens() para evitar estouro de contexto.

Usage

ac_chat_local(
  model,
  base_url = "http://localhost:1234/v1",
  api = c("chat_completions", "responses"),
  temperature = NULL,
  system_prompt = NULL,
  ...
)

Arguments

Value

Objeto Chat do ellmer, pronto para uso em ac_qual_code() (via chat = ac_chat_local(...)).

Examples

## Not run: 
# LM Studio rodando localmente, servindo um modelo na porta padrao
chat_local <- ac_chat_local(model = "qwen2.5-14b-instruct")

cb <- ac_qual_codebook(
  name = "tom", instructions = "Classifique o tom.",
  categories = list(
    positivo = list(definition = "Tom propositivo."),
    negativo = list(definition = "Tom crítico.")
  )
)
df <- data.frame(id = "d1", texto = "Proponho cooperacao.")
corpus <- ac_corpus(df, text = texto, docid = id)
coded <- ac_qual_code(corpus, cb, chat = chat_local,
                      checkpoint_dir = "checkpoints/")

## End(Not run)

Description

ac_clean() aplica um conjunto configurável de transformações ao texto de um objeto ac_corpus, retornando um novo corpus com o texto modificado. As transformações são aplicadas em ordem lógica e registradas como atributo para auditoria.

Usage

ac_clean(
  corpus,
  lower = TRUE,
  remove_punct = TRUE,
  remove_numbers = FALSE,
  remove_url = TRUE,
  remove_email = TRUE,
  remove_symbols = FALSE,
  remove_hashtags = FALSE,
  remove_mentions = FALSE,
  remove_stopwords = NULL,
  remove_accents = FALSE,
  normalize_pt = FALSE,
  protect = NULL,
  extra_stopwords = NULL,
  min_char = NULL,
  custom_replacements = NULL,
  handle_na = c("preserve", "empty", "remove"),
  strip_whitespace = TRUE,
  verbose = FALSE,
  ...
)

Arguments

Details

Ordem de aplicação das transformações:

1. handle_na: tratamento de NAs

2. custom_replacements: substituições livres

3. protect: proteção de termos com placeholders

4. remove_url e remove_email

5. remove_hashtags e remove_mentions

6. remove_symbols

7. lower

8. remove_accents

9. normalize_pt

10. remove_numbers

11. remove_punct

12. remove_stopwords + extra_stopwords

13. min_char: remoção de tokens curtos

14. Restauração dos termos protegidos

15. strip_whitespace (sempre)

Value

Um novo objeto ac_corpus com a coluna text transformada e o atributo cleaning_steps registrando as operações aplicadas em ordem. Quando verbose = TRUE, também imprime um resumo com tokens removidos por etapa e documentos que ficaram vazios após limpeza.

See Also

ac_corpus(), ac_clean_stopwords()

Examples

df <- data.frame(
  id = c("a", "b", "c"),
  texto = c(
    "O deputado do PT disse: 'Defendo a CCJ!' Veja em https://exemplo.org",
    "Sra. presidente, o Sr. senador apresentou o requerimento n\u00ba 123.",
    "T\u00e1 na hora de votar, pra acabar com isso."
  )
)
corpus <- ac_corpus(df, text = texto, docid = id)

# Limpeza básica
ac_clean(corpus)

# Limpeza completa com todas as opções
ac_clean(
  corpus,
  remove_stopwords  = "pt-legislativo",
  extra_stopwords   = c("isso", "aquilo", "coisa"),
  protect           = c("PT", "CCJ"),
  normalize_pt      = TRUE,
  custom_replacements = list("pres\\." = "presidente"),
  min_char          = 3L,
  verbose           = TRUE
)

Description

ac_clean_stopwords() retorna (e opcionalmente modifica) o vetor de stopwords adicionais que o pesquisador pode passar a ac_clean() via extra_stopwords. Funciona como um ponto de partida editável: o pesquisador inspeciona o vetor, adiciona ou remove termos conforme o corpus, e passa o resultado para extra_stopwords.

Usage

ac_clean_stopwords(
  add = NULL,
  remove = NULL,
  preset = c("empty", "pt", "pt-br-extended", "pt-legislativo")
)

Arguments

Value

Vetor character de stopwords pronto para passar a ac_clean(..., extra_stopwords = ...).

See Also

ac_clean()

Examples

# Ver o vetor padrão vazio e adicionar termos
sw <- ac_clean_stopwords(add = c("nobre", "ilustre", "respeitavel"))
print(sw)

# Partir do preset legislativo e remover termos que interessam ao corpus
sw <- ac_clean_stopwords(
  preset = "pt-legislativo",
  remove = c("lei", "projeto")   # manter: são relevantes para a análise
)

# Usar na limpeza
# ac_clean(corpus, remove_stopwords = "pt", extra_stopwords = sw)

Description

ac_cluster_documents() particiona os documentos de um corpus em grupos "duros" (hard clustering) com base na similaridade de vocabulário. Serve para descobrir tipologias latentes, montar amostras estratificadas de revisao humana ou produzir dendrogramas para relatórios metodologicos.

Não substitui ac_lda(): o LDA é um modelo de pertencimento misto (cada documento vira uma mistura de tópicos), enquanto esta função devolve uma etiqueta por documento.

Usage

ac_cluster_documents(
  corpus,
  method = c("hclust", "kmeans", "pam"),
  features = c("tfidf", "count"),
  k = NULL,
  distance = c("cosine", "euclidean"),
  min_docs = 15L
)

Arguments

Value

Objeto de classe ac_cluster com:

assignments

tibble com doc_id e cluster (integer).

fit

Objeto bruto do algoritmo (hclust, kmeans ou pam).

k

Número final de grupos.

method, features, distance

Parametros usados.

silhouette

Silhueta média (NA se cluster não instalado).

dtm

Matriz documento-termo usada (para plotagem).

References

Legendre, P.; Legendre, L. (2012). Numerical Ecology (3rd ed.). Elsevier.

Murtagh, F.; Legendre, P. (2014). Ward's hierarchical agglomerative clustering method: Which algorithms implement Ward's criterion? Journal of Classification, 31(3), 274-295.

Rousseeuw, P. J. (1987). Silhouettes: a graphical aid to the interpretation and validation of cluster analysis. Journal of Computational and Applied Mathematics, 20, 53-65.

Salton, G.; McGill, M. J. (1983). Introduction to Modern Information Retrieval. McGraw-Hill.

See Also

ac_lda(), ac_plot_cluster()

Examples

# Corpus com dois blocos tematicos
df <- data.frame(
  id    = paste0("d", 1:8),
  texto = c("democracia participacao voto liberdade",
            "cidadania direitos participacao democracia",
            "voto direitos liberdade cidadania",
            "democracia voto participacao popular",
            "mercado economia eficiência privatizacao",
            "privatizacao mercado livre eficiência",
            "economia crescimento investimento mercado",
            "eficiência mercado economia livre"),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)
clust  <- ac_cluster_documents(corpus, k = 2)
clust$assignments

Description

ac_collocations() identifica pares (ou trincas) de palavras que aparecem juntas com mais frequência do que o esperado pelo acaso: colocações como "reforma tributária", "não recomendo" ou "atendimento ao cliente", usando medidas de associação estatística em vez de frequência bruta de bigramas/trigramas.

A diferença importa: bigramas puramente frequentes tendem a ser dominados por combinações de palavras funcionais comuns ("de o", "que a"), que são frequentes mas não informativas. As medidas de associação penalizam esse efeito, destacando combinações que ocorrem juntas mais do que a frequência individual de cada palavra sugeriria: o uso típico é alimentar um dicionário customizado (ver ac_build_dictionary()) ou simplesmente explorar expressões compostas específicas de um domínio (jurídico, médico, técnico) antes de uma análise de frequência ou nuvem de palavras.

Usage

ac_collocations(
  corpus,
  n = 2L,
  measure = c("pmi", "ll", "chi2"),
  min_count = 5L,
  drop_punct = TRUE
)

Arguments

Value

Tibble ordenado por associação decrescente, com colunas:

• collocation: o n-grama (palavras separadas por espaço);

• count: frequência absoluta do n-grama no corpus;

• association: valor da medida escolhida em measure.

References

Church, K. W.; Hanks, P. (1990). Word association norms, mutual information, and lexicography. Computational Linguistics, 16(1), 22-29.

Dunning, T. (1993). Accurate methods for the statistics of surprise and coincidence. Computational Linguistics, 19(1), 61-74.

Evert, S. (2005). The Statistics of Word Cooccurrences: Word Pairs and Collocations. Tese (Doutorado), Universität Stuttgart.

Blaheta, D.; Johnson, M. (2001). Unsupervised learning of multi-word verbs. Proceedings of the ACL Workshop on Collocations, 54-60.

See Also

ac_keyness(), ac_count()

Examples

# Reviews de um restaurante com expressoes compostas recorrentes
df <- data.frame(
  id = paste0("r", 1:6),
  texto = c(
    "atendimento ao cliente impecavel, super recomendo o lugar",
    "o atendimento ao cliente deixou a desejar dessa vez",
    "comida boa mas atendimento ao cliente lento",
    "não recomendo, atendimento ao cliente horrivel",
    "ambiente agradável e atendimento ao cliente rápido",
    "preco justo, atendimento ao cliente cordial sempre"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)

ac_collocations(corpus, min_count = 2)

Description

ac_cooccurrence() calcula pares de termos que co-ocorrem dentro de janelas deslizantes ou dentro do mesmo documento, retornando frequências e medidas de associação (PMI, Dice).

Usage

ac_cooccurrence(
  corpus,
  window = 5L,
  unit = c("window", "document"),
  measure = c("count", "pmi", "dice"),
  min_count = 2L,
  ...
)

Arguments

Details

PMI (Church & Hanks, 1990) compara a probabilidade conjunta com a esperada sob independência: $\log_2 [P(x,y) / (P(x)P(y))]$. Zero indica que o par aparece junto tanto quanto o acaso preveria; valores positivos, mais que o acaso. PMI superestima pares raros (Evert, 2005), por isso use min_count para descartá-los.

Dice (Smadja, McKeown & Hatzivassiloglou, 1996) é $2 f(x,y) / (f(x) + f(y))$, entre 0 e 1.

As probabilidades usam a mesma unidade da contagem conjunta: com unit = "window", frequências de token e o total de tokens do corpus (aproximação usual de Church & Hanks); com unit = "document", frequência documental (em quantos documentos o termo aparece) e o número de documentos. Pares de um termo com ele mesmo são ignorados.

Value

Tibble com colunas:

• word1, word2: par de termos (ordenado alfabeticamente);

• cooc: frequência de co-ocorrência. Com unit = "window", é o número de vezes em que os dois termos aparecem a até window tokens um do outro (cada encontro conta uma vez); com unit = "document", é o número de documentos que contêm os dois;

• pmi (se solicitado): pointwise mutual information, em bits;

• dice (se solicitado): coeficiente Dice.

References

Church, K. W.; Hanks, P. (1990). Word association norms, mutual information, and lexicography. Computational Linguistics, 16(1), 22-29.

Evert, S. (2005). The Statistics of Word Cooccurrences: Word Pairs and Collocations. Tese (Doutorado), Universität Stuttgart.

Smadja, F.; McKeown, K. R.; Hatzivassiloglou, V. (1996). Translating collocations for bilingual lexicons: A statistical approach. Computational Linguistics, 22(1), 1-38.

See Also

ac_tokenize(), ac_plot_cooccurrence()

Examples

# Corpus tematico: coocorrência revela associações conceituais
# (que palavras "andam juntas" no discurso).
df <- data.frame(
  id = paste0("d", 1:6),
  texto = c(
    "democracia participacao voto liberdade cidadania popular",
    "cidadania direitos participacao democracia representacao politica",
    "voto direitos liberdade cidadania soberania popular",
    "mercado economia eficiência privatizacao competicao livre",
    "privatizacao mercado livre eficiência produtividade lucro",
    "economia crescimento investimento mercado capital juros"
  ),
  stringsAsFactors = FALSE
)

corpus <- ac_corpus(df, text = texto, docid = id) |>
  ac_clean()
tokens <- ac_tokenize(corpus)

# Janela de 3 tokens, sem filtro de frequência mínima
# (em corpora reais use min_count >= 5 para reduzir ruido)
cooc <- ac_cooccurrence(tokens, window = 3L, min_count = 1L)
head(cooc)

# Coocorrência com PMI (associação normalizada por acaso)
cooc_pmi <- ac_cooccurrence(tokens, window = 3L, measure = "pmi",
                            min_count = 1L)
head(cooc_pmi)

Description

ac_corpus() é a porta de entrada do pipeline do pacote acR. Constrói um objeto estruturado de corpus a partir de um data.frame, um vetor de caracteres, ou um corpus do quanteda, validando a entrada e preservando metadados associados aos documentos.

Usage

ac_corpus(data, text = NULL, docid = NULL, meta = NULL, lang = "pt", ...)

Arguments

Details

A função realiza cinco validações obrigatórias e falha cedo em caso de problema:

1. data deve ser de um dos tipos suportados;

2. a coluna de texto deve existir (ou ser detectável automaticamente);

3. a coluna de texto não pode ser inteiramente NA ou vazia;

4. doc_id não pode ter valores duplicados;

5. doc_id não pode conter NA.

Documentos com texto vazio ou NA geram aviso (warning) mas são mantidos no corpus com texto "": o usuário decide se filtra depois.

Value

Um objeto de classe ac_corpus (que herda de tbl_df, tbl, data.frame) com as colunas:

• doc_id (character): identificador único do documento.

• text (character): texto do documento.

• Demais colunas de metadados, preservadas de data. O objeto traz também o atributo lang indicando o idioma.

Examples

# A partir de um data.frame
df <- data.frame(
  id = c("a", "b", "c"),
  texto = c("Primeiro texto.", "Segundo texto.", "Terceiro."),
  partido = c("PT", "PL", "MDB")
)
corpus <- ac_corpus(df, text = texto, docid = id, meta = partido)
corpus

# A partir de um vetor character (doc_id gerado automaticamente)
ac_corpus(c("Texto um.", "Texto dois."))

# Detecção automática da coluna de texto
df2 <- data.frame(text = c("A", "B"), autor = c("X", "Y"))
ac_corpus(df2)

Description

ac_count() calcula frequências de tokens ou n-gramas a partir de um objeto ac_corpus(), usando internamente ac_tokenize() seguido de uma agregação com dplyr::count().

É o insumo direto de quase toda análise quantitativa do pacote: ac_top_terms() pega o topo, ac_tf_idf() recalibra por distintividade, ac_keyness() compara grupos, ac_wordcloud() visualiza. O argumento by decide se a unidade de análise é o documento ou o grupo agregado.

Pode operar em dois níveis:

• por documento (by = NULL): contagens por doc_id e token;

• por metadados (by = c("partido", ...)): contagens por variáveis de agrupamento e token (agregando vários documentos).

Usage

ac_count(corpus, n = 1L, drop_punct = FALSE, by = NULL, sort = TRUE, ...)

Arguments

Value

Um tibble::tibble():

• Se by = NULL: colunas doc_id, token, n;

• Se by não nulo: colunas by, token, n.

See Also

ac_corpus(), ac_clean(), ac_tokenize()

Examples

df <- data.frame(
  id      = c("d1", "d2", "d3"),
  texto   = c(
    "O deputado do PT falou na CCJ.",
    "O deputado do PL falou novamente.",
    "O senador do PT falou na CCJ."
  ),
  partido = c("PT", "PL", "PT"),
  stringsAsFactors = FALSE
)

corp <- ac_corpus(df, text = texto, docid = id, meta = partido)

# Frequência de palavras (unigramas) por documento
ac_count(corp)

# Frequência de palavras por partido
ac_count(corp, by = "partido")

# Frequência de bigramas por partido, removendo apenas pontuação
ac_count(corp, n = 2, drop_punct = TRUE, by = "partido")

Description

ac_dictionary() conta, para cada documento de um ac_corpus, quantas palavras caem em cada categoria de um dicionário: generalização do método que ac_sentiment() já aplica só para polaridade (positivo/negativo). Um dicionário aqui é qualquer lista nomeada de listas de palavras: temas ("economia", "saúde"), enquadramentos ("ameaça", "oportunidade"), categorias de produto, ou qualquer taxonomia definida a priori pelo pesquisador.

Métodos de dicionário são o método mais antigo e mais transparente de análise de conteúdo assistida por computador (Stone et al., 1966, The General Inquirer; revisado em Grimmer & Stewart, 2013): toda decisão de classificação é auditável: basta olhar a lista de palavras. O preço é a falta de sensibilidade a contexto: a palavra "não" imediatamente antes de um termo do dicionário não inverte a contagem, e sarcasmo ou negação sofisticada passam batido. Para esses casos, o pipeline de LLM (ac_qual_code()) é a alternativa: mais caro, menos transparente, mas sensível a contexto.

Usage

ac_dictionary(corpus, dictionary, by = NULL, case_insensitive = TRUE)

Arguments

Value

Tibble com uma linha por documento (ou grupo), contendo total_tokens e, para cada categoria do dicionário, duas colunas: ⁠<categoria>_n⁠ (contagem de palavras daquela categoria) e ⁠<categoria>_prop⁠ (proporção sobre total_tokens).

References

Stone, P. J.; Dunphy, D. C.; Smith, M. S.; Ogilvie, D. M. (1966). The General Inquirer: A Computer Approach to Content Analysis. MIT Press.

Grimmer, J.; Stewart, B. M. (2013). Text as Data: The Promise and Pitfalls of Automatic Content Analysis Methods for Political Texts. Political Analysis, 21(3), 267-297.

See Also

ac_build_dictionary(), ac_sentiment(), ac_qual_code()

Examples

# Reclamacoes de clientes, categorizadas por tema do problema
df <- data.frame(
  id = paste0("c", 1:4),
  texto = c(
    "a entrega atrasou muito e o rastreio não funcionava",
    "o produto chegou com defeito e quebrado na caixa",
    "cobraram duas vezes no cartao e o reembolso demorou",
    "entrega rápida mas o produto tinha um defeito de fabrica"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)

dict <- ac_build_dictionary(
  entrega    = c("entrega", "atrasou", "rastreio", "rápida"),
  produto    = c("defeito", "quebrado", "fabrica"),
  financeiro = c("cobraram", "cartao", "reembolso")
)

ac_dictionary(corpus, dict)

Description

ac_dictionary_import() constrói um dicionário (ver ac_build_dictionary()) a partir de uma tabela em formato longo: uma linha por par palavra-categoria, o formato em que léxicos costumam ser distribuídos (CSV, planilha). Útil para importar listas de palavras construídas fora do R, ou léxicos de terceiros já traduzidos/adaptados para português (o pacote não distribui nenhum léxico de categorias além do OpLexicon usado em ac_sentiment(); veja vignette("dicionários") para onde encontrar léxicos de terceiros e como adaptá-los a este formato).

Usage

ac_dictionary_import(data, term_col = "termo", category_col = "categoria", ...)

Arguments

Value

Lista nomeada de vetores de caracteres (um dicionário), uma entrada por valor distinto de category_col.

See Also

ac_build_dictionary(), ac_dictionary_save()

Examples

lexico <- data.frame(
  termo     = c("bom", "ótimo", "mau", "péssimo"),
  categoria = c("positivo", "positivo", "negativo", "negativo"),
  stringsAsFactors = FALSE
)
ac_dictionary_import(lexico)

Description

ac_dictionary_save() grava um dicionário (ver ac_build_dictionary()) em um arquivo YAML legível por humanos, para versionar, compartilhar entre pesquisadores ou editar fora do R. ac_dictionary_load() faz o caminho inverso.

Usage

ac_dictionary_save(dictionary, path)

ac_dictionary_load(path)

Arguments

Value

ac_dictionary_save(): o caminho do arquivo, de forma invisível. ac_dictionary_load(): o dicionário (lista nomeada de vetores de caracteres).

See Also

ac_build_dictionary(), ac_dictionary_import()

Examples

dict <- ac_build_dictionary(
  positivo = c("bom", "ótimo"),
  negativo = c("mau", "péssimo")
)
arquivo <- tempfile(fileext = ".yaml")
ac_dictionary_save(dict, arquivo)

dict2 <- ac_dictionary_load(arquivo)
identical(dict, dict2)

Description

ac_dictionary_validate() compara a classificação por dicionário (saída de ac_dictionary(), ac_emotion() ou ac_sentiment() com categorias binarizadas) contra uma codificação de referência humana, categoria por categoria: a mesma lógica de validação que ac_qual_reliability() aplica à classificação por LLM (com by_variable = TRUE), agora para o método de dicionário.

Nenhum dicionário deveria ser usado numa análise publicável sem essa etapa (Grimmer & Stewart, 2013): um dicionário construído à mão pode parecer razoável e ainda assim ter baixa precisão ou recall numa categoria específica: só a comparação com uma amostra codificada por humano revela isso.

Usage

ac_dictionary_validate(scored, human, cat_col = "categoria", threshold = 0)

Arguments

Value

Tibble com uma linha por categoria do dicionário e colunas categoria, n, vp, fp, fn, vn, ⁠concordância⁠, precisao, recall, f1, gwet_ac1, krippendorff_alfa: as mesmas colunas de attr(ac_qual_reliability(...), "by_variable"). Denominadores indefinidos (ex.: uma categoria que nenhum dos dois lados marcou) geram NA, nunca 0 ou 1 artificiais.

References

Grimmer, J.; Stewart, B. M. (2013). Text as Data: The Promise and Pitfalls of Automatic Content Analysis Methods for Political Texts. Political Analysis, 21(3), 267-297.

See Also

ac_dictionary(), ac_qual_reliability()

Examples

df <- data.frame(
  id = paste0("d", 1:4),
  texto = c(
    "a entrega atrasou muito",
    "o produto chegou com defeito",
    "cobraram duas vezes no cartao",
    "entrega rápida e produto perfeito"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)
dict <- ac_build_dictionary(
  entrega = c("entrega", "atrasou", "rápida"),
  produto = c("defeito", "perfeito")
)
scored <- ac_dictionary(corpus, dict)

# Codificacao humana de referência (simulada para o exemplo)
human <- tibble::tibble(
  doc_id    = paste0("d", 1:4),
  categoria = c("entrega", "produto", NA, "entrega|produto")
)

ac_dictionary_validate(scored, human)

Description

ac_emotion() conta, por documento, quantas palavras caem em cada categoria de emoção de um léxico fornecido pelo usuário: indo além da polaridade binária de ac_sentiment() para distinguir, por exemplo, se um texto negativo expressa raiva, medo ou tristeza (Mohammad & Turney, 2013, propuseram essa distinção no NRC Emotion Lexicon, hoje o léxico de emoções mais usado em inglês).

O pacote não distribui um léxico de emoções em português: o NRC Emotion Lexicon original é em inglês e sua tradução/adaptação para português está sujeita aos termos de licença do léxico de origem, que o usuário deve obter e licenciar por conta própria (o NRC é gratuito para pesquisa, mas não redistribuível livremente dentro de outro pacote). ac_emotion() é agnóstica ao léxico: funciona com qualquer tabela palavra→emoção que você tenha: o NRC traduzido, um léxico doméstico, ou uma lista construída à mão para um domínio específico (ex.: emoções em avaliações de atendimento ao cliente).

Internamente, é uma camada sobre ac_dictionary(): converte o léxico em formato longo (uma linha por palavra-emoção) para o formato de dicionário multi-categoria e aplica a mesma contagem.

Usage

ac_emotion(
  corpus,
  lexicon,
  term_col = "termo",
  emotion_col = "emocao",
  by = NULL
)

Arguments

Value

Tibble no mesmo formato de ac_dictionary(): total_tokens e, para cada emoção presente em lexicon, colunas ⁠<emocao>_n⁠ e ⁠<emocao>_prop⁠.

References

Mohammad, S. M.; Turney, P. D. (2013). Crowdsourcing a Word-Emotion Association Lexicon. Computational Intelligence, 29(3), 436-465.

See Also

ac_dictionary(), ac_sentiment()

Examples

# Lexico de emocao mínimo, construido a mao para este exemplo
# (em uso real, substitua por um lexico de emocoes licenciado em PT)
lexico <- data.frame(
  termo  = c("alegria", "feliz", "medo", "assustado", "raiva", "furioso"),
  emocao = c("alegria", "alegria", "medo", "medo", "raiva", "raiva"),
  stringsAsFactors = FALSE
)

df <- data.frame(
  id = paste0("d", 1:3),
  texto = c(
    "fiquei muito feliz com a alegria do momento",
    "fiquei assustado, senti muito medo da situação",
    "fiquei furioso, aquela raiva não passava"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)

ac_emotion(corpus, lexicon = lexico)

Description

ac_estimate_tokens() estima o número de tokens de entrada que um texto vai consumir, usando uma heurística de caracteres por token. Util para prever o custo de uma rodada de ac_qual_code() ou para detectar, antes de enviar ao LLM, documentos que provavelmente excederao a janela de contexto do modelo.

E uma estimativa deliberadamente barata: não faz nenhuma chamada de rede nem depende do tokenizador exato de um modelo específico (que varia por provedor e as vezes nem e público). Para calibrar a heurística contra um modelo real, use ac_calibrate_tokens() com uma amostra pequena de textos.

Usage

ac_estimate_tokens(text, chat = NULL, chars_per_token = 3.2)

Arguments

Value

Vetor inteiro com a estimativa de tokens por texto.

Examples

ac_estimate_tokens("Este e um texto de exemplo para estimar tokens.")
ac_estimate_tokens(c("texto curto", "um texto um pouco mais longo que o anterior"))

Description

Exporta data.frames de resultados (corpus codificado, tabelas de frequência, métricas de confiabilidade) para CSV, LaTeX, Excel (.xlsx) ou RDS. Pensada para facilitar a transicao entre o pipeline acR e a escrita acadêmica (tabelas em artigos) ou o compartilhamento de dados replicaveis.

Usage

ac_export(
  x,
  path = NULL,
  format = NULL,
  overwrite = TRUE,
  latex_caption = NULL,
  latex_label = NULL,
  latex_digits = 3L,
  excel_sheet = "acR",
  verbose = TRUE
)

Arguments

Details

CSV

Usa utils::write.csv() com row.names = FALSE e encoding UTF-8. Separador: virgula. Adequado para importacao em Stata, SPSS, Python e R.

LaTeX

Gera código LaTeX via knitr::kable() com format = "latex", empacotado em ambiente table com ⁠\\centering⁠, ⁠\\caption⁠ e ⁠\\label⁠. Adicione ⁠\\usepackage{booktabs}⁠ no preambulo do documento para melhor tipografia.

Excel

Usa writexl::write_xlsx(): sem dependência de Java ou LibreOffice. Cria arquivo .xlsx compativel com Excel 2007+, Google Sheets e LibreOffice Calc.

RDS

Serializa o objeto R completo via base::saveRDS(). Preserva tipos, atributos e classes (incluindo objetos ac_irr, corpus etc.). Ideal para replicabilidade interna ao projeto.

Value

Invisivel: o caminho do arquivo salvo (character).

See Also

ac_qual_irr(), ac_qual_code()

Examples

resultados <- data.frame(
  id_discurso   = c("d1", "d2", "d3"),
  nome_deputado = c("Dep. A", "Dep. B", "Dep. C"),
  categoria     = c("progressista", "conservador", "tecnocratico"),
  confianca     = c(0.94, 0.91, 0.87)
)

# Escrevemos em tempdir() para não poluir o filesystem do usuário
out_csv <- file.path(tempdir(), "resultados.csv")
out_tex <- file.path(tempdir(), "resultados.tex")
out_rds <- file.path(tempdir(), "resultados.rds")

# CSV
ac_export(resultados, out_csv)

# LaTeX (para incluir em artigo)
ac_export(
  resultados,
  out_tex,
  latex_caption = "Classificação do tom dos discursos por LLM",
  latex_label   = "tab:tom_discursos"
)

# RDS (replicabilidade)
ac_export(resultados, out_rds)

# Excel (requer openxlsx ou writexl instalado)
if (requireNamespace("writexl", quietly = TRUE) ||
    requireNamespace("openxlsx", quietly = TRUE)) {
  out_xlsx <- file.path(tempdir(), "resultados.xlsx")
  ac_export(resultados, out_xlsx, excel_sheet = "Classificação")
}

# Objeto ac_irr (comparar codificacao humana vs. LLM)
gold <- data.frame(
  id_discurso = c("d1", "d2", "d3"),
  categoria   = c("progressista", "conservador", "tecnocratico")
)
predicted <- data.frame(
  id_discurso = c("d1", "d2", "d3"),
  categoria   = c("progressista", "conservador", "progressista")
)
irr_result <- ac_qual_irr(gold, predicted, verbose = FALSE)
ac_export(irr_result, file.path(tempdir(), "confiabilidade.csv"))

Description

Coleta discursos parlamentares diretamente da API pública da Camara dos Deputados (v2), retornando um data.frame padronizado e pronto para uso nas funções do acR. A coleta e feita em duas etapas: (1) lista deputados conforme os filtros informados; (2) para cada deputado, busca os discursos no periodo solicitado, com paginacao automática.

Usage

ac_fetch_camara(
  data_inicio,
  data_fim,
  legislatura = NULL,
  partido = NULL,
  uf = NULL,
  n_max = 100,
  tipo_discurso = "plenario",
  verbose = TRUE,
  sleep = 0.5
)

Arguments

Details

A API Dados Abertos da Camara (v2) não dispoe de endpoint único para discursos por periodo. O fluxo de coleta e:

1. GET /api/v2/deputados - lista deputados com filtros de partido/UF.

2. GET /api/v2/deputados/{id}/discursos - discursos de cada deputado, com paginacao (max. 100 itens por pagina).

O filtro tipo_discurso atua sobre o campo tipoDiscurso retornado pela API. Valores observados: "DISCURSO", "DISCURSO ENCAMINHADO", "BREVE COMUNICAÇÃO", "PELA ORDEM", "COMUNICAÇÃO PARLAMENTAR".

Value

Um data.frame com as colunas:

id_discurso

character. Identificador único do discurso.

id_deputado

integer. ID do deputado na API da Camara.

nome_deputado

character. Nome civil do parlamentar.

partido

character. Sigla do partido na data do discurso.

uf

character. UF da bancada do parlamentar.

data

Date. Data do discurso.

hora_inicio

character. Hora de inicio (HH:MM).

tipo_discurso

character. Tipo de fase do evento.

⁠sumário⁠

character. Sumário do discurso (quando disponivel).

texto

character. Texto integral do discurso (quando disponivel).

uri_discurso

character. URI do recurso na API.

References

CAMARA DOS DEPUTADOS. Dados Abertos da Camara dos Deputados - API v2. Brasilia, 2024. Disponivel em: https://dadosabertos.camara.leg.br/swagger/api.html. Acesso em: abr. 2026.

See Also

ac_corpus() para transformar o resultado em corpus.

Examples

## Not run: 
# Discursos do plenário, marco de 2024
disc <- ac_fetch_camara(
  data_inicio = "2024-03-11",
  data_fim    = "2024-03-15",
  n_max       = 50
)

# Apenas PT e PL
disc_partidos <- ac_fetch_camara(
  data_inicio = "2024-01-01",
  data_fim    = "2024-03-31",
  partido     = c("PT", "PL"),
  n_max       = 100
)

# Todos os tipos de discurso
disc_todos <- ac_fetch_camara(
  data_inicio   = "2024-03-01",
  data_fim      = "2024-03-31",
  uf            = "SP",
  tipo_discurso = "todos",
  n_max         = 100
)

## End(Not run)

Description

Coleta discursos parlamentares do Senado Federal usando o pacote senatebR como backend, retornando um data.frame no mesmo formato padronizado de ac_fetch_camara(). Isso permite combinar corpora das duas casas legislativas sem atrito.

O periodo pode ser especificado por legislatura (atalho conveniente) ou por datas exatas (controle fino). Se ambos forem fornecidos, as datas prevalecem.

Usage

ac_fetch_senado(
  data_inicio = NULL,
  data_fim = NULL,
  legislatura_inicio = NULL,
  legislatura_fim = NULL,
  partido = NULL,
  uf = NULL,
  nome_senador = NULL,
  n_max = 100,
  verbose = TRUE,
  sleep = 0.3
)

Arguments

Details

Legislaturas do Senado Federal

Compatibilidade com ac_fetch_camara()

O data.frame retornado tem as mesmas colunas de ac_fetch_camara(), com a adicao da coluna casa ("senado"). Isso permite combinar os dois corpora com rbind() ou dplyr::bind_rows().

Backend

Esta função usa senatebR (Santos, 2026) como backend para acesso a API do Senado Federal. O senatebR deve estar instalado: install.packages("senatebR").

Value

Um data.frame com as mesmas colunas de ac_fetch_camara():

id_discurso

character. Identificador único.

id_deputado

character. Código do senador na API.

nome_deputado

character. Nome do senador.

partido

character. Sigla do partido.

uf

character. UF da representacao.

data

Date. Data do discurso.

hora_inicio

character. Hora de inicio (HH:MM).

tipo_discurso

character. Tipo/fase do discurso.

sumário

character. Resumo do discurso.

texto

character. Texto integral (quando disponivel).

uri_discurso

character. URL do recurso.

casa

character. Sempre "senado".

References

SANTOS, V. senatebR: Collect Data from the Brazilian Federal Senate Open Data API. CRAN, 2026. Disponivel em: https://github.com/vsntos/senatebR.

See Also

ac_fetch_camara(), ac_corpus()

Examples

## Not run: 
# Por legislatura
disc_sen <- ac_fetch_senado(
  legislatura_inicio = 57,
  n_max = 50
)

# Por datas + filtro de partido
disc_pt <- ac_fetch_senado(
  data_inicio = "2024-01-01",
  data_fim    = "2024-06-30",
  partido     = c("PT", "PL"),
  n_max       = 100
)

# Combinar Camara + Senado
disc_camara <- ac_fetch_camara(
  data_inicio = "2024-03-01",
  data_fim    = "2024-03-31",
  n_max       = 50
)
disc_senado <- ac_fetch_senado(
  data_inicio = "2024-03-01",
  data_fim    = "2024-03-31",
  n_max       = 50
)
corpus_bicameral <- dplyr::bind_rows(disc_camara, disc_senado)

## End(Not run)

Description

Importa arquivos de texto em diferentes formatos (PDF, Word, Excel, CSV, TXT, JSON, imagens com OCR) e retorna diretamente um objeto ac_corpus. Suporta caminhos individuais, vetores de arquivos e globs (⁠dados/*.pdf⁠).

É a via de entrada principal do pipeline quando você trabalha com arquivos em disco (relatórios, transcrições, PDFs escaneados). Faz o que ac_corpus() faria a partir de um data.frame, mas cobrindo o passo anterior: extração de texto de formatos heterogêneos com detecção automática pelo sufixo do arquivo. Para PDFs escaneados e imagens, aciona OCR via tesseract com português como padrão.

Usage

ac_import(path, text_field = NULL, lang_ocr = "por", id_from = "filename", ...)

Arguments

Details

O ac_import() detecta automaticamente o formato pelo extension e aciona o parser correto:

• PDF com texto selecionavel: readtext + pdftools

• PDF escaneado / imagem: tesseract (OCR)

• Word (.doc, .docx): readtext

• Excel (.xlsx, .xls): readtext (requer text_field)

• CSV: readtext (requer text_field) (em tabelas, cada linha vira um documento, com doc_id ⁠<arquivo>.<n>⁠, e as demais colunas viram metadados do corpus)

• TXT / JSON: readtext

• Pasta inteira / glob: todos os arquivos compativeis de uma vez

A ordem dos documentos no corpus resultante segue a ordem de entrada em path (ou a ordem alfabetica retornada por Sys.glob()), independente de o parser ser OCR ou readtext. IDs duplicados (dois arquivos com o mesmo basename) sao desambiguados automaticamente com um sufixo ⁠_2⁠, ⁠_3⁠, ... e um aviso e emitido.

Dependências opcionais: readtext e tesseract não sao importados automaticamente – o ac_import() verifica se estao instalados e orienta a instalacao caso necessário.

Value

Um objeto ac_corpus pronto para uso com todas as funções do acR.

References

Benoit, K., et al. (2018). readtext: Import and Handling for Plain and Formatted Text Files. R package. https://CRAN.R-project.org/package=readtext

Ooms, J. (2024). tesseract: Open Source OCR Engine. R package. https://CRAN.R-project.org/package=tesseract

See Also

ac_corpus(), ac_clean(), ac_tokenize()

Examples

## Not run: 
# PDF com texto selecionavel
corpus <- ac_import('relatório.pdf')

# Pasta inteira de Word
corpus <- ac_import('proposicoes/*.docx')

# Excel -- indicar a coluna de texto
corpus <- ac_import('respostas.xlsx', text_field = 'resposta')

# PDF escaneado (OCR em português)
corpus <- ac_import('ata_manuscrita.pdf', lang_ocr = 'por')

# Imagem (OCR)
corpus <- ac_import('captura.png')

# Pasta mista (PDF + DOCX + TXT)
corpus <- ac_import('dados/*')

## End(Not run)

Description

ac_keyness() calcula estatísticas de "keyness" para comparar a distribuicao de termos entre dois grupos. O criterio que define os grupos e do pesquisador: partido, periodo, tema, regiao, autor, condicao experimental ou qualquer variável categorica no corpus. A função e inspirada em quanteda.textstats::textstat_keyness() e utiliza tabelas 2x2 por termo.

A entrada típica e uma tabela de frequências gerada por ac_count(), agregada por uma coluna de grupo:

• ac_count(corp, by = "grupo") seguido de

• ac_keyness(freq, group = "grupo", target = "A").

Usage

ac_keyness(x, group, target, measure = c("chi2", "ll"), sort = TRUE)

Arguments

Details

Para cada termo, a função constroi uma tabela 2x2:

• a = n_target (frequência do termo no grupo alvo)

• b = n_reference (frequência do termo no grupo de referência)

• c = total_target - a

• d = total_reference - b

Em seguida, calcula:

• qui-quadrado com 1 g.l. na opcao measure = "chi2";

• log-likelihood ratio (G^2) na opcao measure = "ll".

Em ambos os casos, a estatística e multiplicada pelo sinal da diferenca de frequências relativas (a / total_target - b / total_reference), de forma que valores positivos indiquem termos mais caracteristicos do grupo alvo e valores negativos termos mais caracteristicos do grupo de referência.

Value

Um tibble::tibble() com uma linha por termo, contendo:

• token

• group (nome da coluna de grupo, repetido para referência)

• target, reference

• n_target, n_reference

• total_target, total_reference

• keyness (estatística assinada, positiva quando o termo e mais frequente no grupo alvo, negativa quando e mais frequente no grupo de referência)

• direction (nome do grupo em que o termo e relativamente mais frequente)

See Also

ac_count(), ac_top_terms(), ac_tf_idf()

Examples

# Comparar vocabulário entre dois grupos (aqui, dois temas legislativos).
# O criterio de grupo e do pesquisador: partido, periodo, regiao, tema...
df <- data.frame(
  id    = paste0("d", 1:8),
  texto = c(
    "reforma tributária simplifica sistema impostos empresas",
    "IVA dual substitui PIS COFINS ICMS federal",
    "aliquotas excecoes tributárias setores economicos",
    "reforma tributária unifica impostos indiretos",
    "programa habitacional amplia recursos moradia popular",
    "deficit habitacional afeta familias baixa renda",
    "urbanizacao favelas regularizacao fundiária municipios",
    "moradia digna direito social constituicao"
  ),
  tema  = rep(c("tributário", "habitacao"), each = 4),
  stringsAsFactors = FALSE
)

corp <- ac_corpus(df, text = texto, docid = id)
freq <- ac_count(corp, by = "tema")

# Termos-chave do grupo "tributário" versus o resto
key <- ac_keyness(freq, group = "tema", target = "tributário")
head(key)

Description

ac_kwic() localiza todas as ocorrências de um termo (ou padrão) nos documentos de um ac_corpus e devolve cada ocorrência com uma janela de palavras antes e depois: a técnica de concordância usada desde os primórdios da linguística de corpus (Sinclair, 1991) para entender como uma palavra é usada, não só com que frequência.

É o complemento natural de uma análise de frequência ou keyness: saber que "liberdade" é um termo-chave de um grupo não diz nada sobre como o termo é empregado: a concordância mostra se aparece ao lado de "econômica", "de expressão" ou "individual", revelando o enquadramento (framing) real do termo em cada contexto. Funciona em qualquer corpus com linguagem natural: reviews de produto, letras de música, transcrições de atendimento, posts em redes sociais.

Usage

ac_kwic(corpus, pattern, window = 5L, regex = FALSE, case_insensitive = TRUE)

Arguments

Value

Tibble com uma linha por ocorrência, colunas:

• doc_id: documento onde a ocorrência foi encontrada;

• position: posição do token correspondente no documento;

• before: até window palavras imediatamente antes;

• keyword: o token que casou com pattern, como aparece no texto;

• after: até window palavras imediatamente depois.

References

Sinclair, J. (1991). Corpus, Concordance, Collocation. Oxford University Press.

See Also

ac_plot_xray(), ac_count()

Examples

# Avaliações de atendimento ao cliente
df <- data.frame(
  id = paste0("a", 1:4),
  texto = c(
    "o atendimento foi rápido e a atendente foi muito educada comigo",
    "fiquei esperando muito tempo e o atendimento foi frio e distante",
    "atendimento excelente, resolveram meu problema na hora",
    "o atendimento automático não entendeu minha solicitacao"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)

ac_kwic(corpus, pattern = "atendimento", window = 3)

Description

ac_lda() ajusta um modelo de tópicos LDA sobre um ac_corpus, retornando um objeto com os resultados do modelo e tibbles tidy de termos por tópico e prevalência por documento.

Usage

ac_lda(corpus, k = 10L, seed = 42L, method = c("VEM", "Gibbs"), ...)

Arguments

Value

Lista de classe ac_lda com:

• model: objeto LDA do pacote topicmodels;

• terms: tibble com beta (probabilidade de cada termo por tópico);

• documents: tibble com gamma (prevalência de cada tópico por documento);

• k: número de tópicos;

• params: parâmetros usados.

References

Blei, D. M.; Ng, A. Y.; Jordan, M. I. (2003). Latent Dirichlet Allocation. Journal of Machine Learning Research, 3, 993-1022.

Vignette: vignette("lda", package = "acR"): tutorial completo com corpus real e visualizações.

See Also

ac_lda_tune(), ac_plot_lda_topics()

Examples

# 1. Corpus sintético com 3 temas nitidos (democracia, economia, saude, educacao)
df <- data.frame(
  id = paste0("d", 1:10),
  texto = c(
    "democracia participacao cidadania direitos politica",
    "mercado economia privatizacao crescimento fiscal",
    "saude hospital medico doenca tratamento",
    "educacao escola professor ensino aprendizagem",
    "democracia eleicao voto politica partido",
    "economia inflacao juros fiscal orcamento",
    "saude sus medico hospital remedio",
    "educacao universidade pesquisa ciência",
    "participacao social cidadania direitos igualdade",
    "mercado trabalho emprego salário industria"
  )
)
corpus <- ac_corpus(df, text = texto, docid = id)

# 2. Ajustar LDA com k=3 tópicos (o corpus tem ~4 temas; k=3 for a experimentacao)
lda <- ac_lda(corpus, k = 3)
lda  # imprime resumo do modelo

Description

ac_lda_tune() ajusta modelos LDA para diferentes valores de k e calcula a perplexidade fora da amostra por validação cruzada, para auxiliar na seleção do número de tópicos.

Por que fora da amostra: a perplexidade calculada nos mesmos documentos usados para ajustar o modelo cai quase sempre à medida que k cresce, porque mais tópicos = mais parâmetros para memorizar o corpus. Blei, Ng & Jordan (2003) e Wallach et al. (2009) avaliam a perplexidade em documentos não vistos no ajuste; Zhao et al. (2015) usam validação cruzada em 5 partes, como faz esta função por padrão. A versão de treino continua disponível na coluna perplexity_train, só para comparação.

Perplexidade é um critério de ajuste preditivo, não de qualidade substantiva: Chang et al. (2009) mostram que modelos com melhor perplexidade podem produzir tópicos menos interpretáveis para humanos. Use a curva para delimitar uma faixa de k e decida dentro dela lendo os tópicos.

Usage

ac_lda_tune(
  corpus,
  k_range = 5:20,
  seed = 42L,
  method = c("VEM", "Gibbs"),
  folds = 5L,
  ...
)

Arguments

Value

Tibble com colunas k, perplexity (média da perplexidade nas partes de teste da validação cruzada), perplexity_sd (desvio padrão entre as partes) e perplexity_train (perplexidade no corpus inteiro usado no ajuste).

References

Blei, D. M.; Ng, A. Y.; Jordan, M. I. (2003). Latent Dirichlet Allocation. Journal of Machine Learning Research, 3, 993-1022.

Chang, J.; Gerrish, S.; Wang, C.; Boyd-Graber, J.; Blei, D. M. (2009). Reading tea leaves: How humans interpret topic models. Advances in Neural Information Processing Systems, 22, 288-296.

Wallach, H. M.; Murray, I.; Salakhutdinov, R.; Mimno, D. (2009). Evaluation methods for topic models. Proceedings of the 26th International Conference on Machine Learning, 1105-1112.

Zhao, W. et al. (2015). A heuristic approach to determine an appropriate number of topics in topic modeling. BMC Bioinformatics, 16(Suppl 13), S8.

See Also

ac_lda(), ac_plot_lda_tune()

Examples

# 1. Corpus sintético (mesmos temas de ac_lda(), palavras diferentes)
df <- data.frame(
  id = paste0("d", 1:10),
  texto = c(
    "democracia participacao politica voto eleicao",
    "mercado economia fiscal privatizacao",
    "saude hospital medico doenca sus",
    "educacao escola professor universidade",
    "democracia cidadania direitos igualdade",
    "economia inflacao juros orcamento",
    "saude medico remedio tratamento",
    "educacao pesquisa ciência tecnologia",
    "participacao social democracia cidadania",
    "mercado trabalho emprego salário"
  )
)
corpus <- ac_corpus(df, text = texto, docid = id)

# 2. Testar k de 2 a 5: perplexidade fora da amostra (validacao cruzada)
tune <- ac_lda_tune(corpus, k_range = 2:5)
tune

Description

ac_lexical_diversity() mede quão variado é o vocabulário dos documentos de um ac_corpus: uma pergunta recorrente em linguística computacional (textos de falantes nativos vs. aprendizes de uma língua), análise de redações escolares, estudos de estilo autoral, ou comparação de roteiros/transcrições por gênero ou locutor.

Calcula três métricas, cada uma respondendo à mesma pergunta de forma diferente: e cada uma com um ponto fraco diferente:

• TTR (Type-Token Ratio): proporção simples tipos / tokens. Fácil de entender, mas extremamente sensível ao tamanho do texto: textos mais longos quase sempre têm TTR menor, então não compare TTR entre documentos de tamanhos muito diferentes.

• C de Herdan (Herdan, 1960): log(tipos) / log(tokens). Mais estável que TTR frente a variação de tamanho, mas ainda não é totalmente independente do comprimento do texto.

• MTLD (Measure of Textual Lexical Diversity; McCarthy & Jarvis, 2010): percorre o texto token a token acumulando um "fator" sempre que a TTR local cai abaixo de 0,72, e usa a média de fatores nos sentidos direto e reverso. É a métrica recomendada quando os documentos comparados têm tamanhos desiguais.

Usage

ac_lexical_diversity(corpus, by = NULL, case_sensitive = FALSE)

Arguments

Value

Tibble com colunas:

• doc_id (ou as colunas de by, se informado);

• n_tokens, n_types: contagens de tokens e tipos (palavras únicas);

• ttr, herdan_c, mtld: as três métricas descritas acima.

References

Herdan, G. (1960). Type-Token Mathematics: A Textbook of Mathematical Linguistics. Mouton.

McCarthy, P. M.; Jarvis, S. (2010). MTLD, vocd-D, and HD-D: A validation study of sophisticated approaches to lexical diversity assessment. Behavior Research Methods, 42(2), 381-392.

See Also

ac_readability()

Examples

# Transcricoes de dois narradores com estilos de vocabulário distintos
df <- data.frame(
  id = paste0("t", 1:4),
  texto = c(
    "o gato subiu no muro e desceu depois correu e subiu de novo",
    paste(
      "o felino ascendeu ao parapeito, permaneceu imovel por instantes,",
      "descendeu com cautela e retornou ao ponto de partida original"
    ),
    "ela correu muito rápido e muito rápido e muito rápido ainda",
    paste(
      "a atleta acelerou vertiginosamente, superando marcas anteriores",
      "com uma performance notável e consistente ao longo do percurso"
    )
  ),
  narrador = c("simples", "rebuscado", "simples", "rebuscado"),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id, meta = narrador)

ac_lexical_diversity(corpus)

# Comparar riqueza de vocabulário entre os dois estilos narrativos
ac_lexical_diversity(corpus, by = "narrador")

Description

Retorna a paleta categórica padrão do pacote: cores compatíveis com contraste WCAG AA e teste de daltonismo (deuteranopia). Deriva da paleta Okabe-Ito, referência para acessibilidade em visualização científica.

Usage

ac_palette(n = 8L)

Arguments

Value

Vetor character com códigos hex.

See Also

theme_ac()

Examples

ac_palette()      # todas as 8 cores
ac_palette(3)     # primeiras 3

if (requireNamespace("ggplot2", quietly = TRUE)) {
  ggplot2::ggplot(iris, ggplot2::aes(Sepal.Length, Petal.Length,
                                      color = Species)) +
    ggplot2::geom_point(size = 2, alpha = 0.85) +
    ggplot2::scale_color_manual(values = ac_palette(3)) +
    theme_ac()
}

Description

ac_plot_ca() plota um biplot com as duas primeiras dimensões da saída de ac_ca(): pontos de unidades (documentos/grupos) e de termos no mesmo espaço, com os eixos rotulados pela proporção de inércia explicada.

Usage

ac_plot_ca(ca, top_terms = 20L, title = NULL)

Arguments

Value

Objeto ggplot.

See Also

ac_ca()

Examples

df <- data.frame(
  id = paste0("d", 1:6),
  texto = c(
    "entrega atrasada rastreio sumiu",
    "pedido atrasou muito, rastreio não atualiza",
    "produto com defeito, chegou quebrado",
    "veio quebrado, qualidade péssima",
    "atendimento excelente, resolveram rápido",
    "suporte educado e rápido, resolveu tudo"
  ),
  categoria = c("entrega", "entrega", "produto", "produto",
                 "atendimento", "atendimento"),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id, meta = categoria)
ca <- ac_ca(corpus, by = "categoria", min_count = 1)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  ac_plot_ca(ca)
}

Description

Tres formas complementares de olhar para o mesmo cluster:

• "dendrogram" (padrao para method = "hclust"): arvore de fusoes com cortes coloridos por grupo.

• "scatter": projecao 2D via PCA sobre a matriz documento-termo, com pontos coloridos por cluster.

• "heatmap": mapa de calor da matriz de dissimilaridade, ordenado pelo dendrograma.

Usage

ac_plot_cluster(
  x,
  kind = c("auto", "dendrogram", "scatter", "heatmap"),
  title = NULL,
  palette = NULL
)

Arguments

Value

Objeto ggplot.

See Also

ac_cluster_documents()

Examples

df <- data.frame(
  id = paste0("d", 1:8),
  texto = c("democracia participacao voto",
            "cidadania direitos participacao",
            "voto direitos liberdade",
            "democracia voto participacao",
            "mercado economia eficiência",
            "privatizacao mercado livre",
            "economia crescimento mercado",
            "eficiência mercado livre")
)
corpus <- ac_corpus(df, text = texto, docid = id)
clust  <- ac_cluster_documents(corpus, k = 2)
ac_plot_cluster(clust)

Description

ac_plot_cooccurrence() gera um gráfico de rede a partir de um tibble de co-ocorrências (saída de ac_cooccurrence()), usando ggplot2 e ggraph.

Usage

ac_plot_cooccurrence(
  cooc,
  top_n = 50L,
  weight = c("cooc", "pmi", "dice"),
  layout = "fr",
  node_color = "#0072B2",
  edge_color = "grey70",
  title = NULL,
  ...
)

Arguments

Value

Objeto ggplot.

See Also

ac_cooccurrence()

Examples

# 1. Corpus pequeno de tres documentos
df <- data.frame(
  id = c("d1", "d2", "d3"),
  texto = c(
    "democracia participacao cidadania",
    "participacao politica democracia",
    "cidadania direitos participacao"
  )
)

# 2. Calcular co-ocorrências de termos
corpus <- ac_corpus(df, text = texto, docid = id) |> ac_clean()
cooc <- ac_cooccurrence(ac_tokenize(corpus), min_count = 1)

# 3. Rede visualizada com ggraph (dependência opcional)
if (requireNamespace("ggraph", quietly = TRUE)) {
  ac_plot_cooccurrence(cooc)
}

Description

ac_plot_keyness() cria um grafico de barras com as estatísticas de keyness calculadas por ac_keyness(), destacando os termos mais caracteristicos do grupo alvo e do grupo de referência.

A função usa ggplot2 como base e pode, opcionalmente, aplicar o estilo editorial do pacote ipeaplot.

Usage

ac_plot_keyness(
  x,
  n = NULL,
  style = c("default", "ipea"),
  flip = TRUE,
  show_reference = TRUE
)

Arguments

Value

Um objeto ggplot.

See Also

ac_count(), ac_keyness()

Examples

# 1. Corpus fabricado com duas subamostras (Governo vs Oposicao)
df <- data.frame(
  id    = c("d1", "d2", "d3", "d4"),
  texto = c(
    "A A A B",
    "A B",
    "A B B B",
    "B B C"
  ),
  lado  = c("Governo", "Governo", "Oposicao", "Oposicao"),
  stringsAsFactors = FALSE
)

# 2. Calcular termos-chave (sobre-representados no grupo alvo)
corp <- ac_corpus(df, text = texto, docid = id, meta = lado)
freq <- ac_count(corp, by = "lado")
key <- ac_keyness(freq, group = "lado", target = "Governo")

# 3. Grafico dos 5 termos com maior chi-quadrado
ac_plot_keyness(key, n = 5)

Description

ac_plot_lda_topics() gera um gráfico de barras com os termos de maior probabilidade (beta) para cada tópico do modelo LDA.

Usage

ac_plot_lda_topics(lda_result, top_n = 10L, ncol = NULL, title = NULL, ...)

Arguments

Value

Objeto ggplot.

See Also

ac_lda()

Examples

# Corpus sintético com dois blocos tematicos
df <- data.frame(
  id = paste0("d", 1:8),
  texto = c(
    "democracia participacao voto cidadania",
    "cidadania direitos participacao democracia",
    "voto direitos liberdade cidadania",
    "democracia voto participacao popular",
    "mercado economia eficiência privatizacao",
    "privatizacao mercado livre eficiência",
    "economia crescimento investimento mercado",
    "eficiência mercado economia livre"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)
lda    <- ac_lda(corpus, k = 2)

# Grafico com os 5 termos mais probabilisticos por tópico
ac_plot_lda_topics(lda, top_n = 5)

Description

ac_plot_lda_tune() gera um gráfico de linha da perplexidade (ou outras métricas) em função do número de tópicos k, auxiliando na escolha do k ideal para o modelo LDA.

Usage

ac_plot_lda_tune(tune_result, title = NULL, ...)

Arguments

Value

Objeto ggplot.

See Also

ac_lda_tune()

Examples

# Corpus sintético com dois blocos tematicos
df <- data.frame(
  id = paste0("d", 1:8),
  texto = c(
    "democracia participacao voto cidadania",
    "cidadania direitos participacao democracia",
    "voto direitos liberdade cidadania",
    "democracia voto participacao popular",
    "mercado economia eficiência privatizacao",
    "privatizacao mercado livre eficiência",
    "economia crescimento investimento mercado",
    "eficiência mercado economia livre"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)

# Testar k de 2 a 4 e visualizar a curva de perplexidade
# (ponto de inflexao/"cotovelo" sugere um bom k)
tune <- ac_lda_tune(corpus, k_range = 2:4)
ac_plot_lda_tune(tune)

Description

ac_plot_lexical_diversity() compara MTLD (ou outra métrica de ac_lexical_diversity()) entre grupos.

Usage

ac_plot_lexical_diversity(
  diversity_tbl,
  group_col = NULL,
  metric = c("mtld", "ttr", "herdan_c"),
  type = c("box", "bar"),
  title = NULL
)

Arguments

Value

Objeto ggplot.

See Also

ac_lexical_diversity()

Examples

df <- data.frame(
  id = paste0("t", 1:4),
  texto = c(
    "o gato subiu no muro e desceu depois correu e subiu de novo",
    "o felino ascendeu ao parapeito e descendeu com cautela depois",
    "ela correu muito rápido e muito rápido e muito rápido ainda",
    "a atleta acelerou vertiginosamente superando marcas anteriores"
  ),
  narrador = c("simples", "rebuscado", "simples", "rebuscado"),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id, meta = narrador)
div <- ac_lexical_diversity(corpus)
div$narrador <- corpus$narrador
ac_plot_lexical_diversity(div, group_col = "narrador")

Description

ac_plot_readability() compara a distribuição do Índice de Flesch (ver ac_readability()) entre grupos, com boxplots: a forma usual de reportar legibilidade comparada na literatura de linguística computacional e comunicação.

Usage

ac_plot_readability(
  readability_tbl,
  group_col = NULL,
  type = c("box", "bar"),
  title = NULL
)

Arguments

Value

Objeto ggplot.

See Also

ac_readability()

Examples

df <- data.frame(
  id = paste0("r", 1:6),
  texto = c(
    "Bom. Gostei. Rápido.",
    "Fácil de montar e usar no dia a dia.",
    paste(
      "A configuracao inicial demanda familiaridade com conceitos",
      "de rede que extrapolam o público leigo habitual."
    ),
    "Perfeito, superou expectativas.",
    paste(
      "A ausência de documentacao técnica compromete a integracao",
      "com sistemas legados preexistentes na infraestrutura corporativa."
    ),
    "Simples e direto, recomendo."
  ),
  categoria = rep(c("fácil", "difícil"), 3),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id, meta = categoria)
leg <- ac_readability(corpus)
leg$categoria <- corpus$categoria
ac_plot_readability(leg, group_col = "categoria")

Description

ac_plot_sentiment() gera visualizações de sentimento: barras por documento, linha temporal, ou distribuição de scores.

Usage

ac_plot_sentiment(
  sentiment_tbl,
  type = c("bar", "line", "density"),
  x_col = "doc_id",
  fill_col = "sentiment",
  title = NULL,
  ...
)

Arguments

Value

Objeto ggplot.

See Also

ac_sentiment()

Examples

# Requer internet na primeira execucao: ac_sentiment() baixa o OpLexicon
# do GitHub e o guarda em cache (tools::R_user_dir("acR", "data")).
# Corpus com quatro documentos de valências distintas
df <- data.frame(
  id = c("a", "b", "c", "d"),
  texto = c(
    "excelente ótimo positivo bom",
    "péssimo terrivel negativo ruim",
    "aprovada proposta reuniao",
    "bom resultado positivo ótimo"
  )
)
corpus <- ac_corpus(df, text = texto, docid = id)

# Calcular scores e visualizar em barras (positivo/neutro/negativo por doc)
sent <- ac_sentiment(corpus)
ac_plot_sentiment(sent)

Description

ac_plot_temporal() traça a evolução de uma métrica agregada por período, saída de ac_temporal(), com uma linha de tendência suavizada opcional.

Usage

ac_plot_temporal(temporal_tbl, smooth = TRUE, title = NULL, ylab = "Valor")

Arguments

Value

Objeto ggplot.

See Also

ac_temporal()

Examples

df <- data.frame(
  doc_id = paste0("d", 1:6),
  data   = as.Date(c("2024-01-05", "2024-01-20", "2024-02-02",
                     "2024-02-15", "2024-03-01", "2024-03-10")),
  score  = c(-2, -1, 0, 1, 2, 1)
)
temporal <- ac_temporal(df, date_col = "data", value_col = "score")
ac_plot_temporal(temporal, ylab = "Sentimento médio")

Description

ac_plot_tf_idf() cria um grafico de barras com os termos mais caracteristicos a partir de uma tabela com a coluna tf_idf, tipicamente gerada por ac_tf_idf().

A função usa ggplot2 como base e pode, opcionalmente, aplicar o estilo editorial do pacote ipeaplot.

Usage

ac_plot_tf_idf(
  x,
  by = NULL,
  n = NULL,
  style = c("default", "ipea"),
  flip = TRUE
)

Arguments

Value

Um objeto ggplot.

See Also

ac_count(), ac_tf_idf(), ac_top_terms()

Examples

# 1. Corpus de 3 discursos com metadado de partido
df <- data.frame(
  id      = c("d1", "d2", "d3"),
  texto   = c(
    "O deputado do PT falou na CCJ.",
    "O deputado do PL falou novamente.",
    "O senador do PT falou na CCJ."
  ),
  partido = c("PT", "PL", "PT"),
  stringsAsFactors = FALSE
)

# 2. Pipeline padrao: corpus -> frequência -> tf-idf
corp  <- ac_corpus(df, text = texto, docid = id, meta = partido)
freq  <- ac_count(corp)
tfidf <- ac_tf_idf(freq)

# 3. Grafico dos 10 termos com maior tf-idf (mais distintivos)
ac_plot_tf_idf(tfidf, n = 10)

freq_by <- ac_count(corp, by = "partido")
tfidf_by <- ac_tf_idf(freq_by, by = "partido")
ac_plot_tf_idf(tfidf_by, by = "partido", n = 5)

Description

ac_plot_top_terms() cria um grafico de barras com os termos mais frequentes a partir de uma tabela de frequências, tipicamente gerada por ac_count() ou filtrada por ac_top_terms().

A função usa ggplot2 como base e pode, opcionalmente, aplicar o estilo editorial do pacote ipeaplot.

Usage

ac_plot_top_terms(
  x,
  by = NULL,
  n = NULL,
  style = c("default", "ipea"),
  flip = TRUE
)

Arguments

Value

Um objeto ggplot.

See Also

ac_count(), ac_top_terms()

Examples

# 1. Corpus curto com metadado de partido
df <- data.frame(
  id      = c("d1", "d2", "d3"),
  texto   = c(
    "O deputado do PT falou na CCJ.",
    "O deputado do PL falou novamente.",
    "O senador do PT falou na CCJ."
  ),
  partido = c("PT", "PL", "PT"),
  stringsAsFactors = FALSE
)
corp <- ac_corpus(df, text = texto, docid = id, meta = partido)

# 2. Top 10 termos do corpus inteiro
freq <- ac_count(corp)
ac_plot_top_terms(freq, n = 10)

# 3. Top 5 termos POR partido (facets)
freq_by <- ac_count(corp, by = "partido")
ac_plot_top_terms(freq_by, by = "partido", n = 5)

Description

ac_plot_wordcloud_comparative() gera nuvens de palavras comparativas entre N grupos de documentos, dispostas em facets lado a lado. Usa TF-IDF (calculado tratando cada grupo como um "documento") para identificar os termos mais distintivos de cada grupo.

Aceita 2, 3, 4+ grupos: cada grupo vira uma faceta. Para dois grupos a leitura fica naturalmente lado a lado; para mais, o layout se organiza em uma linha (ou grade, se muitos grupos).

Usage

ac_plot_wordcloud_comparative(
  corpus,
  group,
  max_words = 50L,
  colors = NULL,
  title = NULL,
  seed = 42L,
  backend = c("auto", "ggwordcloud", "ggplot"),
  ...
)

Arguments

Value

Objeto ggplot.

See Also

ac_tf_idf()

Examples

# Corpus dividido em dois grupos com vocabulário contrastante
df <- data.frame(
  id     = paste0("d", 1:6),
  texto  = c(
    "democracia participacao popular voto",
    "direitos cidadania liberdade democracia",
    "participacao popular igualdade direitos",
    "mercado economia privatizacao eficiência",
    "privatizacao mercado livre eficiência",
    "economia crescimento mercado investimento"
  ),
  grupo = c("A","A","A","B","B","B")
)
corpus <- ac_corpus(df, text = texto, docid = id)

# Nuvem comparativa: termos distintivos de cada grupo
ac_plot_wordcloud_comparative(corpus, group = grupo)

Description

ac_plot_wordscores() plota os escores estimados por ac_wordscores() num eixo único, destacando quais documentos foram usados como referência.

Usage

ac_plot_wordscores(wordscores_tbl, title = NULL)

Arguments

Value

Objeto ggplot.

See Also

ac_wordscores()

Examples

df <- data.frame(
  id = paste0("r", 1:4),
  texto = c(
    "excelente, recomendo muito",
    "bom, atende bem",
    "ruim, não gostei",
    "péssimo, decepcao"
  ),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)
notas <- c(r1 = 5, r3 = 2, r4 = 1)
out <- ac_wordscores(corpus, notas)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  ac_plot_wordscores(out)
}

Description

ac_plot_xray() exibe a posição de ocorrência de um ou mais termos ao longo do texto de cada documento, como marcações verticais numa linha horizontal. Útil para visualizar padrões de uso ao longo de discursos, capítulos ou documentos longos.

Usage

ac_plot_xray(
  corpus,
  terms,
  ignore_case = TRUE,
  colors = NULL,
  title = NULL,
  ...
)

Arguments

Value

Objeto ggplot.

See Also

ac_corpus()

Examples

# Dois documentos com repeticao de termos-alvo em posicoes diferentes
df <- data.frame(
  id = c("d1", "d2"),
  texto = c(
    "democracia liberdade igualdade democracia direitos democracia",
    "mercado liberdade privatizacao mercado eficiência mercado"
  )
)
corpus <- ac_corpus(df, text = texto, docid = id)

# X-ray: pontos marcam a posicao relativa de cada termo dentro do texto
ac_plot_xray(corpus, terms = c("democracia", "mercado", "liberdade"))

Description

ac_plot_zipf() produz o gráfico diagnóstico clássico de Zipf (1949): frequência de cada palavra contra sua posição no ranking de frequência (1º, 2º, 3º... termo mais comum), em escala log-log. Em praticamente qualquer corpus de linguagem natural: avaliações de produto, letras de música, posts de redes sociais, discursos: essa relação é aproximadamente linear com inclinação próxima de -1: a palavra mais frequente aparece cerca de duas vezes mais que a segunda, três vezes mais que a terceira, e assim por diante.

É útil como diagnóstico de qualidade do corpus antes de qualquer análise mais sofisticada: desvios fortes da reta esperada podem indicar problemas de tokenização (pontuação não removida dominando o ranking), um corpus pequeno demais, ou texto fortemente repetitivo (boilerplate, templates).

Usage

ac_plot_zipf(freq_tbl, by = NULL, title = NULL)

Arguments

Value

Objeto ggplot.

References

Zipf, G. K. (1949). Human Behavior and the Principle of Least Effort. Addison-Wesley.

See Also

ac_count(), ac_top_terms()

Examples

# Avaliações de produtos de duas categorias
df <- data.frame(
  id = paste0("r", 1:6),
  texto = c(
    "bom produto bom preco bom atendimento",
    "produto bom mas entrega lenta",
    "preco justo produto funcional",
    "péssimo atendimento produto com defeito",
    "excelente produto rápido e eficiente",
    "produto ok nada de especial"
  ),
  categoria = rep(c("eletronico", "casa"), 3),
  stringsAsFactors = FALSE
)
corpus <- ac_corpus(df, text = texto, docid = id)
freq <- ac_count(corpus, drop_punct = TRUE, by = NULL)

ac_plot_zipf(freq)

Description

ac_qual_code() classifica os textos de um ac_corpus de acordo com um ac_codebook, usando um modelo de linguagem via ellmer. Retorna um tibble com a classificação, grau de certeza (via self-consistency) e raciocinio da LLM para cada documento.

E o motor de classificação do pipeline qualitativo do acR. Assume que o codebook já foi construido com ac_qual_codebook() e (idealmente) testado numa amostra piloto. A saida e sempre validada com ac_qual_reliability() contra uma amostra codificada por humano – nenhuma análise categorial publicável dispensa essa etapa.

Tres parametros determinam qualidade e custo:

• k_consistency: número de rodadas de self-consistency (Wang et al., 2023). O mesmo texto e classificado k vezes com pequena variacao de temperatura, e a categoria final e a moda. O confidence_score sai dessa concordância – 1,0 significa que todas as k rodadas concordaram. Padrao k = 3 custa 3x mais tokens que uma rodada única, e e a configuracao mínima para reportar confianca de forma defensavel.

• reasoning: pede raciocinio estruturado. Melhora a qualidade em casos ambiguos mas praticamente dobra o custo por documento. Use "short" como padrao e "detailed" so quando planeja auditar decisoes individuais.

• live: tira a classificação do modo "caixa-preta" mostrando cada documento em tempo real. Numa rodada de 500 discursos, você percebe nos primeiros 10 se o codebook esta funcionando – antes de gastar todo o orcamento de tokens.

Usage

ac_qual_code(
  corpus,
  codebook,
  model = "anthropic/claude-sonnet-4-5",
  chat = NULL,
  confidence = c("total", "by_variable", "both", "none"),
  k_consistency = 3L,
  temperature = 0.3,
  reasoning = TRUE,
  reasoning_length = c("short", "medium", "detailed"),
  main_temperature = 0,
  reasoning_extras = FALSE,
  live = c("off", "terminal", "progress", "shiny"),
  max_retries = 2L,
  checkpoint_dir = NULL,
  ...
)

Arguments

Value

Tibble com colunas:

• doc_id: identificador do documento;

• Metadados originais do corpus;

• categoria: slug interno da categoria (chave da lista categories no codebook). Em multilabel = TRUE, string pipe-separada sem espaco ("técnica|politica").

• categoria_label: rotulo humano correspondente, vindo do campo label de cada categoria (se ausente, repete o slug). Em multilabel, unidos por " | " (espaco dos dois lados).

• confidence_score: grau de certeza da categoria vencedora (0-1). Presente quando confidence e "total" ou "both".

• confidence_level: "alta" (⁠>= 0,80⁠), "média" (⁠>= 0,61⁠) ou "baixa" – faixas convencionadas pelo pacote para resumir confidence_score. Não vêm da literatura de confiabilidade: as faixas de Landis & Koch (1977) são para kappa, não para proporção de rodadas concordantes. A ideia de usar a concordância entre amostras como sinal de incerteza vem de Wang et al. (2023) e Xiong et al. (2024), que mostram que ela se correlaciona com acerto, mas não propõem cortes universais. Com k_consistency = 3, os valores possíveis são só 1/3, 2/3 e 1. Acompanha confidence_score.

• ⁠<categoria>_confidence⁠: uma coluna por categoria do codebook (ex.: positivo_confidence, negativo_confidence), com a proporção de rodadas de self-consistency que escolheram aquela categoria. Presentes quando confidence e "by_variable" ou "both".

• raciocinio: justificativa da classificação (se reasoning = TRUE).

• status: resultado da rodada principal: "ok", "resposta_invalida" (JSON não parseavel), "estouro_contexto", "limite_taxa" (limite de requisições ou de tokens por minuto/dia do provedor, HTTP 429), "timeout" ou "erro_servidor".

• n_tentativas: número de tentativas até obter status = "ok" (ou até esgotar max_retries).

• tokens_entrada, tokens_saida: tokens de entrada/saida da rodada principal, via chat$get_tokens() (NA se o provedor não expoe).

• segundos: tempo total da rodada principal, incluindo novas tentativas.

• tokens_por_segundo: tokens_saida / segundos.

O resultado carrega também um atributo run_info (ver attributes()) com metadados da execucao: versoes de acR e ellmer, modelo, base_url, parametros efetivos aplicados ao provedor, temperaturas pedidas, k_consistency, hash do codebook e timestamps de inicio/fim.

References

Wang, X. et al. (2023). Self-Consistency Improves Chain of Thought Reasoning in Language Models. International Conference on Learning Representations (ICLR).

Xiong, M. et al. (2024). Can LLMs Express Their Uncertainty? An Empirical Evaluation of Confidence Elicitation in LLMs. International Conference on Learning Representations (ICLR).

Landis, J. R.; Koch, G. G. (1977). The Measurement of Observer Agreement for Categorical Data. Biometrics, 33(1), 159-174.

Gilardi, F.; Alizadeh, M.; Kubli, M. (2023). ChatGPT Outperforms Crowd Workers for Text-Annotation Tasks. PNAS, 120(30).

Examples

## Not run: 
cb <- ac_qual_codebook(
  name         = "tom",
  instructions = "Classifique o tom do discurso.",
  categories   = list(
    positivo = list(definition = "Tom propositivo e colaborativo."),
    negativo = list(definition = "Tom crítico e confrontacional.")
  )
)

df <- data.frame(
  id    = c("d1", "d2"),
  texto = c("Proponho cooperacao.", "Este governo e um fracasso.")
)
corpus <- ac_corpus(df, text = texto, docid = id)

# Usando string de modelo (comportamento padrao)
coded <- ac_qual_code(corpus, cb, model = "anthropic/claude-sonnet-4-5")

# Usando objeto Chat do ellmer (recomendado para controle fino)
chat_obj <- ellmer::chat_google_gemini(model = "gemini-2.5-flash", echo = "none")
coded <- ac_qual_code(corpus, cb, chat = chat_obj)

# Groq (inferência rápida, plano gratuito)
chat_groq <- ellmer::chat_groq(model = "openai/gpt-oss-120b", echo = "none")
coded <- ac_qual_code(corpus, cb, chat = chat_groq)

# Ollama (modelos locais, sem envio de dados externos)
chat_local <- ellmer::chat_ollama(model = "llama3.2", echo = "none")
coded <- ac_qual_code(corpus, cb, chat = chat_local)

# confidence = "both": além de confidence_score (categoria vencedora),
# ganha uma coluna <categoria>_confidence por categoria do codebook --
# util para montar uma matriz de confianca por tema entre documentos
# ou comparar modelos na mesma tarefa.
coded_both <- ac_qual_code(corpus, cb, model = "anthropic/claude-sonnet-4-5",
                            confidence = "both")
coded_both[, c("doc_id", "categoria", "confidence_score",
               "positivo_confidence", "negativo_confidence")]

## End(Not run)

Description

ac_qual_codebook() cria um livro de códigos estruturado para classificação de textos via LLM. É o instrumento central da análise de conteúdo assistida por IA: nenhum resultado publicável de codificação automática dispensa um codebook explícito, versionável e passível de revisão por pares (Krippendorff, 2018).

Um codebook do acR operacionaliza cinco elementos por categoria: definição (o que é), exemplos positivos (o que é, concretamente), exemplos negativos (o que não é, para desambiguar categorias vizinhas), referências (ancorar a categoria em literatura publicada) e peso (indicação relativa de prioridade no prompt). Um codebook bem construído é a diferença entre a LLM adivinhar (com prior próprio, não replicável) e a LLM aplicar uma operacionalização reproduzível (Gilardi et al., 2023).

Suporta três modos de construção:

• "manual" (padrão): o pesquisador fornece definições, exemplos e referências diretamente.

• "induced": a LLM induz categorias automaticamente a partir de uma amostra do corpus, sugerindo nomes, definições e exemplos. Útil como ponto de partida quando você não tem um esquema teórico a priori.

• "literature": a LLM busca definições na literatura acadêmica, gerando um banco estruturado com trecho original, tradução, autor, ano, revista e link. O pesquisador revisa e aprova interativamente.

Todo codebook mantém um history das modificações: quem alterou, quando e o quê. Essencial para auditoria metodológica quando o instrumento evolui entre a versão piloto e a versão final publicada.

Usage

ac_qual_codebook(
  name,
  instructions,
  categories = list(),
  corpus = NULL,
  n_categories = 5L,
  mode = c("manual", "induced", "literature"),
  multilabel = FALSE,
  lang = "pt",
  chat = NULL,
  model = "anthropic/claude-sonnet-4-5",
  journals = "default",
  n_refs = 5L,
  check_overlap = FALSE,
  ...
)

Arguments

Value

Objeto de classe ac_codebook.

References

Gilardi, F., Alizadeh, M., & Kubli, M. (2023). ChatGPT outperforms crowd workers for text-annotation tasks. PNAS, 120(30).

Krippendorff, K. (2018). Content Analysis: An Introduction to Its Methodology (4th ed.). SAGE.

Sampaio, R. C., & Lycarião, D. (2021). Análise de conteúdo categorial: manual de aplicação. Brasília: ENAP.

Examples

# Codebook manual com duas categorias, cada uma com exemplos positivos
# (o que E) e negativos (o que NÃO e, para desambiguar categorias vizinhas)
cb <- ac_qual_codebook(
  name         = "tom_discurso",
  instructions = "Classifique o tom geral do discurso.",
  categories   = list(
    positivo = list(
      definition   = "Discurso com tom propositivo e colaborativo.",
      examples_pos = c("Proponho que trabalhemos juntos nesta agenda."),
      examples_neg = c("Este governo e um desastre completo."),
      weight       = 1  # peso relativo no prompt; use >1 para priorizar
    ),
    negativo = list(
      definition   = "Discurso com tom crítico ou confrontacional.",
      examples_pos = c("Esta proposta vai arruinar o pais."),
      examples_neg = c("Apresento esta emenda para melhorar o texto."),
      weight       = 1
    )
  )
)
cb  # imprime resumo do codebook

Description

ac_qual_codebook_add() adiciona uma ou mais categorias a um ac_codebook já criado, sem precisar recriar o objeto do zero. Útil para refinamento iterativo do codebook durante a análise.

Usage

ac_qual_codebook_add(codebook, ...)

Arguments

Value

Objeto ac_codebook atualizado.

See Also

ac_qual_codebook(), ac_qual_codebook_remove()

Examples

# Codebook inicial com 2 categorias
cb <- ac_qual_codebook(
  name         = "tom",
  instructions = "Classifique o tom.",
  categories   = list(
    positivo = list(definition = "Tom propositivo."),
    negativo = list(definition = "Tom crítico.")
  )
)

# Adicionar uma terceira categoria (nome do argumento vira nome da categoria)
cb <- ac_qual_codebook_add(cb,
  neutro = list(
    definition   = "Tom neutro, sem posicionamento claro.",
    examples_pos = c("O projeto foi apresentado na sessão de hoje.")
  )
)
names(cb$categories)  # "positivo" "negativo" "neutro"

Description

ac_qual_codebook_history() retorna e imprime o histórico de ações registradas em um ac_codebook (adições, remoções, merges, traduções etc.).

Usage

ac_qual_codebook_history(codebook, n = Inf)

Arguments