cluster_facil.cluster module

class cluster_facil.cluster.ClusterFacil(entrada: DataFrame | str, aba: str | None = None, prefixo_cluster: str = 'cluster_', nome_coluna_classificacao: str = 'classificacao', random_state: int | None = 42)

Base: object

Facilita a clusterização de textos em DataFrames do Pandas.

Esta classe encapsula os passos comuns de pré-processamento de texto (TF-IDF), análise do número ideal de clusters (método do cotovelo) e a aplicação do algoritmo K-Means para agrupar os textos.

Atributos:

df (pd.DataFrame): O DataFrame com os dados e resultados da clusterização. rodada_clusterizacao (int): Contador para nomear arquivos de saída e colunas de cluster,

inicializado em 1 e incrementado a cada chamada de finaliza.

coluna_textos (Optional[str]): Nome da coluna contendo os textos a serem clusterizados. X (Optional[csr_matrix]): Matriz TF-IDF resultante do pré-processamento. inercias (Optional[list[float]]): Lista de inercias calculadas para diferentes K no método do cotovelo. prefixo_cluster (str): Prefixo usado para nomear as colunas de cluster (ex: ‘cluster_’, ‘subcluster_’). nome_coluna_classificacao (str): Nome da coluna usada para armazenar as classificações manuais. random_state (Optional[int]): Semente para geradores de números aleatórios usada internamente.

preparar(coluna_textos: str, limite_k: int = 10, n_init: str | int = 'auto', plotar_cotovelo: bool = True, **tfidf_kwargs) → None

Prepara os dados para a próxima rodada de agrupamento (clusterização).

Realiza a análise inicial dos textos (TF-IDF) e calcula as opções de agrupamento (método do cotovelo) para ajudar na escolha do número ideal de grupos (K). Opcionalmente, exibe um gráfico (cotovelo) para visualizar essas opções.

Como funciona em múltiplas rodadas: * Primeira rodada: Analisa todos os textos do conjunto de dados. * Rodadas seguintes: Se você já classificou alguns grupos manualmente na coluna

de classificação (padrão: ‘classificacao’), este método analisará apenas os textos ainda não classificados. A análise e o gráfico do cotovelo serão baseados somente nesses textos restantes.

Nota: A exibição automática do gráfico (plotar_cotovelo=True) funciona melhor em ambientes interativos como Jupyter Notebooks. Se estiver usando em um script, pode ser melhor definir plotar_cotovelo=False.

Parâmetros:

• coluna_textos (str) – O nome da coluna no seu DataFrame que contém os textos a serem agrupados.

• limite_k (int, optional) – O número máximo de grupos (K) a serem testados para o gráfico do cotovelo. Padrão é 10.

• n_init (str | int, optional) – Define como o K-Means é inicializado para o cálculo do cotovelo. ‘auto’ (padrão) geralmente executa 10 vezes e escolhe o melhor resultado, buscando mais robustez. Um número inteiro (ex: 1) executa um número fixo de vezes.

• plotar_cotovelo (bool, optional) – Se True (padrão), mostra o gráfico do cotovelo após a análise. Padrão é True.

• **tfidf_kwargs – Outras configurações avançadas para a análise de texto (TF-IDF). Permite ajustar parâmetros como min_df, max_df, ngram_range, etc. Permite configurar parâmetros como min_df, max_df, ngram_range, etc. Ex: preparar(…, min_df=5, ngram_range=(1, 2))

Levanta:

• KeyError – Se a coluna de texto informada (coluna_textos) não for encontrada.

• ValueError – Se limite_k não for um número positivo, ou se não houver textos não classificados para analisar em rodadas posteriores à primeira.

• TypeError – Se a coluna de texto não contiver dados do tipo texto.

• ImportError – Se a biblioteca ‘matplotlib’ for necessária (plotar_cotovelo=True) e não estiver instalada.

clusterizar(num_clusters: int, **kmeans_kwargs) → str

Executa a clusterização K-Means nos dados preparados pela última chamada a preparar.

Adiciona a coluna de clusters ao DataFrame original, apenas para as linhas que foram incluídas na última preparação.

Parâmetros:

• num_clusters (int) – O número de clusters (K) a ser usado.

• **kmeans_kwargs – Argumentos de palavra-chave adicionais a serem passados diretamente para o construtor sklearn.cluster.KMeans. Permite configurar parâmetros como max_iter, tol, etc. O n_clusters é definido pelo argumento obrigatório, e random_state e n_init têm padrões internos, mas todos podem ser sobrescritos se incluídos nos kmeans_kwargs. Ex: clusterizar(…, max_iter=500, tol=1e-5)

Retorna:

O nome da coluna de cluster criada (ex: ‘cluster_1’, ‘subcluster_2’).

Tipo de retorno:

str

Levanta:

• RuntimeError – Se preparar não foi executado com sucesso antes (self.X ou self._indices_preparados_na_rodada estão None), ou se não há dados preparados para clusterizar.

• ValueError – Se num_clusters for inválido para o número de amostras preparadas.

• Exception – Outros erros durante a execução do K-Means.

salvar(o_que_salvar: str = 'ambos', formato_tudo: str = 'csv', formato_amostras: str = 'xlsx', caminho_tudo: str | None = None, caminho_amostras: str | None = None, diretorio_saida: str | None = None) → dict[str, bool | str | None]

Salva os resultados do último agrupamento realizado, com opções flexíveis.

Permite salvar o conjunto de dados completo com os resultados, amostras de cada grupo, ou ambos, em diferentes formatos e locais.

Parâmetros:

• o_que_salvar (str, optional) – Define o que será salvo: ‘tudo’: Salva o conjunto de dados completo com a nova coluna de grupo. ‘amostras’: Salva um arquivo separado com exemplos de textos de cada grupo. ‘ambos’: Salva ambos os arquivos (padrão).

• formato_tudo (str, optional) – Formato para salvar o conjunto completo (‘csv’, ‘xlsx’, ‘parquet’, ‘json’). Padrão é ‘csv’.

• formato_amostras (str, optional) – Formato para salvar as amostras (‘xlsx’, ‘csv’, ‘json’). Padrão é ‘xlsx’.

• caminho_tudo (Optional[str], optional) – Caminho completo (incluindo nome do arquivo) para salvar o conjunto completo. Se fornecido, ignora diretorio_saida. Se a extensão for omitida, será adicionada com base em formato_tudo. Padrão é None (usa nome padrão).

• caminho_amostras (Optional[str], optional) – Caminho completo para salvar as amostras. Se fornecido, ignora diretorio_saida. Se a extensão for omitida, será adicionada com base em formato_amostras. Padrão é None (usa nome padrão).

• diretorio_saida (Optional[str], optional) – Pasta onde salvar os arquivos caso caminho_tudo ou caminho_amostras não sejam especificados. Se None (padrão), salva na pasta atual.

Retorna:

Um dicionário indicando o sucesso e o caminho de cada arquivo salvo.

Ex: {‘tudo_salvo’: True, ‘caminho_tudo’: ‘/caminho/abs/dados_com_grupos.csv’, ‘amostras_salvas’: True, ‘caminho_amostras’: ‘/caminho/abs/amostras_grupos.xlsx’}

Tipo de retorno:

dict[str, bool | str | None]

Levanta:

• RuntimeError – Se o método clusterizar (agrupamento) não foi executado antes.

• KeyError – Se a coluna de resultados do último agrupamento não for encontrada.

• ValueError – Se alguma opção (o_que_salvar, formato_tudo, formato_amostras) for inválida.

• ImportError – Se uma biblioteca necessária para o formato de arquivo escolhido não estiver instalada (ex: openpyxl para .xlsx, pyarrow para .parquet).

• OSError – Se houver um erro ao criar a pasta de saída (ex: permissão negada).

classificar(cluster_ids: int | list[int], classificacao: str, rodada: int | None = None) → None

Atribui uma classificação a um ou mais clusters de uma rodada específica.

Preenche a coluna de classificação (self.nome_coluna_classificacao) do DataFrame para todas as linhas pertencentes aos clusters especificados na rodada indicada. Se a coluna de classificação não existir, ela será criada. Classificações posteriores para as mesmas linhas sobrescreverão as anteriores.

Parâmetros:

• cluster_ids (int | list[int]) – O ID do cluster ou uma lista de IDs de clusters a serem classificados.

• classificacao (str) – O rótulo (string) de classificação a ser atribuído. Não pode ser uma string vazia.

• rodada (Optional[int], optional) – O número da rodada de clusterização cujos clusters serão classificados. Se None (padrão), usa a última rodada de clusterização concluída. Padrão é None.

Levanta:

• RuntimeError – Se nenhuma clusterização foi realizada ainda (clusterizar não foi chamado).

• TypeError – Se classificacao não for string ou cluster_ids não for int/list de ints, ou se rodada não for int (se fornecido).

• ValueError – Se classificacao for vazia, rodada for inválida (fora do range), ou se algum cluster_id não existir na rodada especificada, ou se a lista cluster_ids estiver vazia.

• KeyError – Se a coluna de cluster correspondente à rodada não for encontrada (erro interno).

resetar() → None

Reinicia o estado da instância ClusterFacil.

Remove todas as colunas de resultados de agrupamentos anteriores (identificadas pelo prefixo_cluster) e a coluna de classificação manual (self.nome_coluna_classificacao), se existirem. Redefine o contador de rodadas para 1 e limpa as configurações e resultados anteriores (análise TF-IDF, opções de agrupamento, etc.).

Após chamar resetar, você precisará chamar preparar novamente antes de poder clusterizar ou salvar.

subcluster(classificacao_desejada: str) → Self

Cria uma nova instância de ClusterFacil contendo apenas os textos de uma classificação específica.

Útil para realizar um novo agrupamento (subcluster) dentro de um grupo já classificado.

A nova instância terá os resultados de agrupamentos anteriores removidos e usará ‘subcluster_’ como prefixo para os novos resultados e ‘subclassificacao’ como nome da coluna para classificações manuais dentro deste subcluster. A coluna de classificação original é mantida, mas renomeada para ‘{nome_original}_origem’ para referência.

Parâmetros:

classificacao_desejada (str) – A classificação manual atribuída anteriormente que você deseja usar para filtrar os textos.

Retorna:

Uma nova instância de ClusterFacil, pronta para analisar e agrupar os textos do subcluster.

Tipo de retorno:

ClusterFacil

Levanta:

• KeyError – Se a coluna de classificação original não for encontrada.

• ValueError – Se a classificacao_desejada não existir na coluna de classificação.

• RuntimeError – Se preparar não foi chamado na instância original (necessário para saber qual era a coluna de texto).

obter_subcluster_df(classificacao_desejada: str) → DataFrame

Retorna um DataFrame contendo apenas os textos de uma classificação específica, com as colunas de resultados de agrupamentos anteriores removidas e a coluna de classificação original renomeada.

Parâmetros:

classificacao_desejada (str) – A classificação manual que você deseja usar para filtrar os textos.

Retorna:

O DataFrame filtrado e preparado para análise de subcluster.

Tipo de retorno:

pd.DataFrame

Levanta:

• KeyError – Se a coluna de classificação original não for encontrada.

• ValueError – Se a classificacao_desejada não existir na coluna de classificação.

listar_classificacoes() → list[str]

Retorna uma lista das classificações manuais únicas (não nulas) presentes na coluna de classificação.

Retorna:

Lista das classificações únicas encontradas. Retorna lista vazia se

a coluna não existir ou não houver classificações atribuídas.

Tipo de retorno:

list[str]

contar_classificacoes(inclui_na=False) → Series

Loga a contagem de quantos textos pertencem a cada classificação manual atribuída.