product-association-analysis 0.1.0

Ferramenta para análise de associação de produtos em dados de transações

🛒 Product Association Analysis

Descubra quais produtos são frequentemente comprados juntos para impulsionar suas vendas!

---

📋 Índice

• O que é isto?
• Como isto pode me ajudar?
• Instalação Passo a Passo
• Manual Completo
  • Preparando seus Dados
  • Executando a Análise
  • Entendendo o Relatório
• Exemplos de Uso
• Solução de Problemas
• Para Desenvolvedores
• Licença
• Contato e Suporte

---

🤔 O que é isto?

Product Association Analysis é uma ferramenta que analisa seus dados de vendas para descobrir quais produtos são frequentemente comprados juntos. É como ter um analista de dados trabalhando para você, mas totalmente automatizado!

Exemplo: Descubra que 75% das pessoas que compram café também compram açúcar, ou que 40% dos clientes que compram um vestido também adquirem um cinto combinando.

---

💡 Como isto pode me ajudar?

Esta ferramenta pode transformar sua estratégia de vendas com insights poderosos:

Para equipes de Marketing:

• 📊 Crie promoções mais eficazes combinando produtos relacionados
• 📧 Melhore suas campanhas de email com recomendações personalizadas
• 💰 Aumente o valor médio dos pedidos com sugestões de cross-selling

Para gestores de Varejo:

• 🏪 Organize sua loja física colocando produtos relacionados próximos
• 🛒 Otimize o layout do seu e-commerce com recomendações automáticas
• 📦 Crie kits e combos baseados em dados reais, não em suposições

Para equipes de E-commerce:

• 🔍 Melhore seu sistema de "Quem comprou X também comprou Y"
• ⚡ Aumente as taxas de conversão com sugestões relevantes
• 🚀 Impulsione vendas com recomendações baseadas em comportamentos reais

---

📥 Instalação Passo a Passo

NOTA: Nunca usou Python antes? Sem problema! Siga exatamente estas instruções e tudo funcionará perfeitamente!

Windows

1. Instale o Python:

   • Baixe o instalador do Python 3.8 ou superior em python.org
   • IMPORTANTE: Marque a caixa "Add Python to PATH" durante a instalação
   • Clique em "Install Now"

2. Instale a ferramenta:

   • Abra o "Prompt de Comando" (pesquise por "cmd" no menu Iniciar)
   • Cole e execute este comando:

   pip install product-association-analysis
   

3. Verifique a instalação:

   • No mesmo Prompt de Comando, digite:

   product-association-analysis --version
   

   • Você deverá ver a versão do programa, confirmando que está instalado corretamente

Mac

1. Instale o Python:

   • O Mac já vem com Python, mas recomendamos instalar a versão mais recente
   • Baixe o instalador do Python 3.8 ou superior em python.org
   • Abra o arquivo baixado e siga as instruções de instalação

2. Instale a ferramenta:

   • Abra o Terminal (pesquise por "Terminal" no Spotlight)
   • Cole e execute este comando:

   pip3 install product-association-analysis
   

3. Verifique a instalação:

   • No mesmo Terminal, digite:

   product-association-analysis --version
   

   • Você deverá ver a versão do programa, confirmando que está instalado corretamente

---

📖 Manual Completo

Preparando seus Dados

A ferramenta funciona melhor com um arquivo CSV contendo seus dados de transações. Se você não sabe o que é um arquivo CSV, pense nele como uma planilha simples que pode ser criada no Excel.

Formato do arquivo:

1. Seu arquivo deve ter pelo menos estas duas colunas:

   • IdPedido: Um número ou código que identifica cada pedido
   • Produto: O nome ou código do produto comprado

2. Exemplo de como seus dados devem parecer:

   IdPedido	Produto	Quantidade	Valor
   1001	Camiseta Branca	2	59.90
   1001	Calça Jeans	1	129.90
   1002	Tênis Esportivo	1	199.90
   1003	Camiseta Branca	1	59.90
   1003	Meias	3	19.90

   Observação: As colunas Quantidade e Valor são opcionais, mas podem ser úteis para análises futuras.

3. Como exportar do seu sistema:

   • Excel/Google Sheets: Salve como CSV (Arquivo > Salvar como > CSV)
   • Sistema de vendas: Procure pela opção "Exportar transações" ou "Relatório de vendas"
   • E-commerce: A maioria das plataformas permite exportar pedidos como CSV

Executando a Análise

Depois de ter seu arquivo CSV pronto, é hora de executar a análise:

1. Abra o terminal ou prompt de comando:

   • Windows: Aperte a tecla Windows + R, digite cmd e pressione Enter
   • Mac: Abra o Spotlight (Command + Espaço) e digite Terminal

2. Execute o comando básico:

   product-association-analysis caminho/para/seu_arquivo.csv
   

   Substitua caminho/para/seu_arquivo.csv pelo caminho real do seu arquivo.

   Exemplo no Windows:

   product-association-analysis C:\Users\SeuNome\Downloads\vendas.csv
   

   Exemplo no Mac:

   product-association-analysis /Users/SeuNome/Downloads/vendas.csv
   

3. Opções avançadas (todas opcionais):

   product-association-analysis seu_arquivo.csv --output relatorio_personalizado.xlsx --max-produtos 30 --encoding latin1 --verbose
   

   • --output: Define o nome do arquivo Excel de saída (padrão: relatorio_associacoes.xlsx)
   • --max-produtos: Número máximo de produtos com abas individuais no Excel (padrão: 20)
   • --encoding: Se seu arquivo contém caracteres especiais (padrão: utf-8)
   • --verbose: Mostra mais informações durante o processamento

4. Aguarde o processamento:

   • A ferramenta vai carregar seus dados, analisar todas as transações e gerar um relatório detalhado
   • No final, ela informará onde o relatório foi salvo

Entendendo o Relatório

Após a execução bem-sucedida, você terá um arquivo Excel com várias abas:

1. Aba "Resumo":

   • Lista todos os produtos ordenados por frequência
   • Mostra quantas vezes cada produto foi vendido
   • Apresenta a porcentagem de cada produto no total de vendas

2. Abas de Produtos Individuais (uma para cada produto popular):

   • Revela quais outros produtos são mais frequentemente comprados junto com este
   • Inclui gráficos visuais para facilitar a interpretação
   • Mostra a força de cada associação em porcentagem

3. Aba "Rankings Completos":

   • Contém a lista completa de todas as associações para todos os produtos
   • Ordenada por produto principal e depois pela força da associação
   • Útil para análises mais detalhadas ou exportação para outros sistemas

4. Aba "Insights e Recomendações":

   • Oferece sugestões práticas baseadas na análise
   • Inclui recomendações de marketing e disposição de produtos
   • Destaca oportunidades específicas de cross-selling

---

🚀 Exemplos de Uso

Exemplo 1: Análise Básica

product-association-analysis vendas_2023.csv

Este comando simples analisará seu arquivo de vendas e criará um relatório Excel chamado relatorio_associacoes.xlsx no mesmo diretório.

Exemplo 2: Análise Personalizada

product-association-analysis vendas_2023.csv --output relatorio_q1_2023.xlsx --max-produtos 10 --verbose

Este comando:

• Analisa o arquivo vendas_2023.csv
• Cria um relatório chamado relatorio_q1_2023.xlsx
• Limita o número de abas de produtos individuais a 10
• Mostra informações detalhadas durante o processamento

Exemplo 3: Uso com Arquivos de Sistemas Diferentes

product-association-analysis dados_loja.csv --encoding latin1

Útil quando seu arquivo foi exportado de sistemas mais antigos ou que usam caracteres especiais (como acentos em português).

---

❓ Solução de Problemas

"Arquivo não encontrado"

• Problema: O programa não consegue encontrar seu arquivo CSV
• Solução: Verifique se o caminho está correto. Tente colocar o arquivo na mesma pasta onde está executando o comando e usar apenas o nome do arquivo.

"Erro de codificação"

• Problema: Caracteres estranhos aparecem nos dados
• Solução: Tente usar a opção --encoding latin1 ou --encoding cp1252 para arquivos exportados do Excel em português.

"Colunas não encontradas"

• Problema: O programa não encontra as colunas necessárias
• Solução: Verifique se seu arquivo tem colunas chamadas "IdPedido" e "Produto". Se tiverem nomes diferentes, renomeie-as no Excel antes de exportar.

"O Excel não abre o relatório"

• Problema: O arquivo é gerado, mas não abre
• Solução: Certifique-se de ter o Microsoft Excel ou LibreOffice Calc instalado. Tente abrir o Excel primeiro e depois abrir o arquivo através do menu Arquivo > Abrir.

---

👨‍💻 Para Desenvolvedores

Se você é um desenvolvedor e quer contribuir ou estender esta ferramenta:

Usando como Biblioteca Python

from product_association import carregar_dados, calcular_frequencia_produtos, identificar_transacoes, criar_ranking_associacoes, criar_excel_detalhado

# Carregar dados
df = carregar_dados('vendas.csv')

# Calcular frequência
contagem_produtos = calcular_frequencia_produtos(df)

# Identificar transações
transacoes, transacoes_multiplas = identificar_transacoes(df)

# Criar rankings de associações
associacoes = criar_ranking_associacoes(transacoes_multiplas, contagem_produtos)

# Gerar relatório
relatorio = criar_excel_detalhado(associacoes, contagem_produtos, 'relatorio.xlsx')

Estendendo a Funcionalidade

A ferramenta foi projetada para ser modular e facilmente extensível. Consulte o arquivo CONTRIBUTING.md para saber como contribuir com o projeto.

---

📄 Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.

---

Transforme seus dados em insights acionáveis!

Feito com ❤️ pela comunidade de contribuidores