Weka Plus Grails

Introdução ☄

O Weka Plus Grails é uma aplicação (web) desenvolvida em (Groovy) Grails que usa algumas funções do Weka.

In english: The Weka Plus Grails is an (web) aplication developed in (Groovy) Grails that use some Weka functions.

This Readme file is written in Brazilian Portuguese. But all the other files of this project are in English. Enjoy!

---

Autoria 

• Autor do repositório: Paulo de Lima Cavalcanti (www.paulolimac.com)

---

Descrição 

Esta aplicação web foi desenvolvida para estudo da API do Weka.

São requisitos do sistema:

• uma aplicação usando técnicas de aprendizagem de máquina implementadas no Weka contemplando os seguintes requisitos.

  • Requisito 1: Leitura de arquivo de instâncias - O sistema deve conter uma rotina para leitura de instâncias de treinamento previamente armazenadas em arquivo ARFF.

  • Requisito 2: Treinamento do algoritmo de aprendizado – A partir das instâncias lidas do arquivo, o sistema deverá realizar o treinamento de um classificador do Weka. A escolha do classificador e dos parâmetros de treinamento é livre.

  • Requisito 3: Armazenar classificador gerado – O sistema deverá salvar em arquivo o classificador treinado, para posterior uso em novas instâncias.

  • Requisito 4: Uso do classificador para novas instâncias – O sistema deverá fazer a leitura do classificador treinado e ser usado em novas instâncias não vistas no treinamento. As novas instâncias poderão ser fornecidas manualmente pelo usuário em uma interface ou lidas de um arquivo ARFF.

Este é um prototipo. Falhas e implementações estão presentes.

---

Instalação 

Requisitos/Recursos utilizados ⚙

Basicamente, deve-se ter o Grails instalado em máquina e a API do Weka para disponibilizar as funções.

Com detalhes, foram utilizados os seguintes recursos:

• Programação

  • Grails: como framework para desenvolvimento.
    • Groovy: linguagem implícita do framework
    • Navigation Plugin: plugin para gerar menus nas *.gsp's.
  • Weka API: disponibiliza as funções de aprendizagem do Weka para uso noutros programas.
    • Weka JavaDoc: documentação oficial da API do Weka.
    • Weka Tutorial - Using WEKA from Groovy: tutorial do Weka sobre como aplicar a API em programas Groovy.
    • Weka Tutorial - Use Weka in your Java code: tutorial do Weka sobre como aplicar a API em programas Java.
    • Weka Tutorial - Serialization: tutorial do Weka sobre Serializar o classificador

• Editor de textos:

  • Eclipse IDE, versão 4 "Juno" (http://www.eclipse.org)
    • OBS: utilizado o plugin Spring Tool Suite na IDE

• Controle de Versão (opcional):

  • Git, versão 1.7 (http://git-scm.com)
  • GitHub (https://github.com/paulolimac)
  • Bitbucket (https://bitbucket.org/paulolimac)
  • Egit, versão 2.0 (http://eclipse.org/egit)

Com este material é possível iniciar as implementações com Weka no Grails.

Instalação 

Basicamente, necessita-se do ambiente Java, Grails, Weka.jar e uma IDE para facilitar o desenvolvimento.

Utilizando o Ubuntu, é indicado o seguinte procedimento para instalação:

1. Instalação da IDE Eclipse, que trará paralelamente o ambiente Java:
   • Digite no Terminal: sudo apt-get install eclipse.
   • Obs: o Java será instalado automaticamente.
2. Plugin Spring Tool Suite
   • Siga as instruções do http://grails.org/STS+Integration
3. API Weka
   • Baixe o jar do Weka pelo http://www.cs.waikato.ac.nz/ml/weka/index_downloading.html.
   • Depois inclua o jar na pasta libraries do seu projeto Grails.
   • Por fim, clique com o botão direito no seu projeto Grails pelo Eclipse e adicione o Jar ao classpath do seu projeto.
4. Navigation Plugin
   • No diretório do seu projeto Grails, digite no terminal: grails
   • No ambiente grails, digite o comando grails install-plugin navigation
5. (opcional) Controle de versão, sugerido o Git (com o plugin Egit). O uso de controle de versão é um boa prática para gerir mudanças no código, possibilitar SEGURANÇA com cópias de salva-guarda (backup) e, um histórico da sua codificação durante todo seu estudo. Este aprendizado é um adicional em seu conhecimento. E afinal, você está aqui e agora fazendo uso de um repositório Git, não? 
   • No Eclipse: clique no menu Help -> Eclipse Marketplace e faça uma busca pelo plugin Egit.
   • Outra opção é instalar o Git e utilizá-lo por linha de comando. No Terminal, instale pelo comando: sudo apt-get install git-core git-doc git-gui gitk.

---

Downloads 

Caso desejar, brinque com o Weka Plus Grails on-line. Você pode acessá-lo em http://wekaplusgrails.herokuapp.com/

O aplicativo (war) para instalação no seu servidor pode ser baixado pelo link WekaPlusGrails-0.1.war

Se preferir visualizar o código, navegue-copie-e-cole pelas implementações disponibilizadas neste repositório. Ou utilize Git! 

---

Começando a usar este material ⚒

Este repositório pode ser consultado online, ter seus textos e códigos copiados, ou mesmo ser clonado (fork). Além disso, utilize sua instalação Git para copiar o repositório localmente e trabalhar em sua IDE ou editor de textos preferido.

Use o material com bom discernimento!

Um ponto importante é que a estrutura do material aqui apresentado não é a única forma de implementação, nem é a mais elegante. Entenda-o e ajuste-o ao seu gosto e preferência. 

Funções do aplicativo 

Este aplicativo web faz uso básico da biblioteca do Weka e do Grails.

O objetivo é atender os requisitos listados anteriormente. Nisso, foram criadas 4 entidades (Classes de domínio) e suas respectivas classes de controle e visualizações (gsp's). São as entidades:

A descrição das entidades e atributos segue:

• TrainSample: Esta entidade armazena os arquivos ARFF (instâncias) para treino de algoritmos de classificação.
  • name: nome para identificar o TrainSample salvo
  • description: breve descrição sobre o TrainSample armazenado
  • filename: nome do arquivo ARFF salvo pelo sistema. É gerado pelo sistema de acordo o arquivo de upload feito pelo usuário
• Classifier: Salva os classificadores gerados no treino. É pré-requisito que um trainSample esteja salvo no sistema para ser usado na geração do classificador.
  • name: nome para identificar o Classifier salvo
  • description: breve descrição sobre o Classifier armazenado
  • filename: nome do arquivo model salvo pelo sistema. É gerado pelo sistema de acordo o tipo de algoritmo classificador e do TrainSample selecionados. O arquivo é binário, e portanto, ilegível ao usuário.
  • modelTxt: arquivo de texto contendo as regras de decisão do modelo de classificador criado. Variará de acordo com o classificador e com o TrainSample aplicados. É gerado automaticamente pelo aplicativo. Por ser texto, o arquivo é legível pelo usuário
  • typeClassifier: lista para o usuário as opções de algoritmo-classificador para criação do modelo.
  • trainSample: lista dos TrainSample existentes no sistema para treinar o classificador. O usuário escolhe um.
• TestSample: Testa um classificador criado pelo sistema. Para isso, o TestSample armazena instâncias novas fornecidas pelo usuário para teste. No final, ele relata (por estatística) os resultados obtidos. É necessário que um classificador esteja salvo no sistema e, que as instâncias fornecidas sejam compatíveis com as usadas no TrainSample que gerou o classificador.
  • name: nome para identificar o TestSample salvo
  • description: breve descrição sobre o TestSample armazenado
  • filename: nome do arquivo ARFF salvo para o sistema. É gerado pelo sistema de acordo o arquivo de upload feito pelo usuário. Sugere-se um arquivo com instâncias diferentes das usadas no TrainSample, afim de verificar a acuracia do modelo testado.
  • evaluationTxt: arquivo de texto onde consta o relatório do teste efetuado sob o Classifier.
  • classifier: lista dos Classifiers existentes no sistema para testar. O usuário escolhe um.
• Labeler: Aplica o classificador criado no sistema. O usuário fornece as instâncias (por texto ou, por arquivo ARFF) equivalentes a usada no TrainSample que gerou o classificador, seleciona o classificador e, por fim o sistema gera um arquivo ARFF com as instâncias classificadas.
  • name: nome para identificar o Labeler salvo
  • description: breve descrição sobre o Labeler armazenado
  • typeInput: tipo de entrada que o usuário deseja classificar, se pelo campo de texto ou pelo upload de arquivo ARFF.
  • unlabeledArffFilename: nome do arquivo ARFF enviado pelo usuário para o sistema. É gerado o nome pelo sistema de acordo o arquivo de upload feito pelo usuário. As instâncias não devem estar "labeled", ou seja, não devem estar etiquetadas (classificadas).
  • unlabeledTextFieldFilename similar ao anterior, mas o texto é digitado no formulário. É gerado o nome do arquivo ARFF pelo sistema automaticamente. As instãncias devem estar também "unlabeled".
  • classifier: lista dos Classifiers existentes no sistema para testar. O usuário escolhe um.
  • labeledArffFilename: nome do arquivo ARFF com as instâncias classificadas (labeled) pelo sistema. É gerado o nome pelo sistema. As instâncias unlabeled foram as enviadas pelo usuário, e aqui se tornam labeled pelo sistema. As classes são adicionadas em cada linha de instância num arquivo ARFF pelo sistema ao final.
    • OBS: Leia a seção "Perguntas Frequentes (FAQ)" sobre como diferenciar e preparar instâncias classificadas (labeled) e não classificadas (unlabeled)

Estas instâncias são gerados inicialmente com o scaffold do Grails resultando em CRUD's básicos (criar, listar, atualizar, deletar, mostrar, editar e salvar).

Métodos específicos do Weka foram importados nos Controllers das entidades. Com o scaffold das entidades gerado, os métodos e rotinas com uso da biblioteca do Weka foram produzidas e adaptou-se os CRUDs para cada entidade.

Vantagens... ☻

Como pontos positivos do sistema temos que:

• Poucas entidades, para facilitar o entendimento
• Linguagem Groovy, facilita a leitura das rotinas
• Serve de exemplo sobre uso da biblioteca do Weka, com algumas das principais funções que foram exemplificadas com java pelo site oficial
• Usa mais funções do Weka, além do básico com groovy exemplificado pelo site oficial.
• Sistema disponível a todos aqueles que desejarem conhecê-lo

...E desvantagens ☠

Claro que há desvantagens. São:

• Usada a linguagem Groovy (Grails), consequentemente, não há exemplos noutras linguagens (Java, Ruby, Python...)
• Código carece de elegância (concisão)
• Definir melhores nomes para entidades e métodos, nomes que definam melhor o modelo
• Reduzir o código gerado automaticamente (scaffolded) pelo Grails
• Exceptions ocorrerão e não são tratadas
• Entradas nos formulários (e arquivos) não são validadas
• Não há instâncias previamente armazenadas para exemplificar o que é salvo
• Seria melhor ter menos instâncias...
• Diversas outras falhas ainda não identificadas ;)

---

Perguntas frequentes (FAQ's) ⸮

• Pergunta: Qual a diferença entre instâncias classificadas (labeled) e não classificadas (unlabeled)?

  • Resposta: Na documentação do Weka o termo label, em inglês etiqueta, equivale a classificar. Ou seja, instâncias que estão labeled estão classificadas já. E instâncias unlabeled ainda não foram classificadas. As instâncias unlabeled são usadas em classificadores já criados. E as instâncias labeled são usadas para treinar e/ou testar classificadores em sua construção.

• Pergunta: Como reconhecer/diferenciar e fazer instâncias unlabeled e labeled nos arquivos ARFF?

  • Resposta: Ao abrir um arquivo ARFF, verifique se nas linhas das instâncias, há escrito o nome da classe ou se há um sinal de interrogação (?). Se houver um sinal de interrogação ? então a instância está unlabeled, ou seja, não foi classificada. Ao contrário, se no final da linha da instância estiver escrito a classe, então esta instância está classificada, ou seja, ela está labeled. Na resposta dada no tópico WEKA: Classifying an ARFF data with a given SMO model é respondida indiretamente nossa questão. E para facilitar, veja o exemplo abaixo:

    • Instâncias unlabeled num arquivo arff, repare no sinal obrigatório de ?:

        	@relation weather.symbolic
        		@attribute outlook {sunny, overcast, rainy}
        		@attribute temperature {hot, mild, cool}
        		@attribute humidity {high, normal}
        		@attribute windy {TRUE, FALSE}
        		@attribute play {yes, no}
      
        		@data
        			sunny,hot,high,FALSE,?
        			sunny,hot,high,TRUE,?
        			overcast,hot,high,FALSE,?
      

    • Instâncias labeled num arquivo arff, já com a classe no final da linha:

        	@relation weather.symbolic
        		@attribute outlook {sunny, overcast, rainy}
        		@attribute temperature {hot, mild, cool}
        		@attribute humidity {high, normal}
        		@attribute windy {TRUE, FALSE}
        		@attribute play {yes, no}
      
        		@data
        			sunny,hot,high,FALSE,no
        			sunny,hot,high,TRUE,no
        			overcast,hot,high,FALSE,yes
      

• Pergunta: É complicado instalar/configurar tudo?

  • Resposta: Para iniciante, sim!. Mas depois de prática com Grails e com os termos usados no Weka, tudo se torna fácil. Igual a tudo na vida.

• Pergunta: Porque fazer este aplicativo?

  • Resposta: Simples: praticar mais com o Grails, estudar sobre a biblioteca do Weka, etc. Desculpas não faltam.

• Pergunta: Posso utilizar outros softwares para implementar o aplicativo?

  • Resposta: Claro que sim! Utilize seu sistema Java. Sua IDE ou editor. Até mesmo se conhecer outra biblioteca, aprenda-a. Não fique preso neste modelo.

• Pergunta: Neste repositório, como os branches foram criados e usados?

  • Resposta: A organização deste repositório, principalmente os branches e tags, baseou-se na idéia apresentada pelo Vincent Driessen, numa postagem do seu blog entitulada A successful Git branching model. Poucas diferenças para com a idéia original do Vicent foram efetuadas, e visam estruturar (nomear) os branches-tags-commits voltados a organização do repositório orientados por tipo de arquivo/diretório.

• Pergunta: Tenho que utilizar Git para conhecer este aplicativo?

  • Resposta: Não! Você pode baixar o código e usar outro versionador. Ou mesmo não utilizar nenhum. MAS, recomendamos o uso do Git para seus projetos. Vale a pena aprender.

• Pergunta: Não seria melhor implementar uma tela única, ao invés de tantas telas de cadastros e listagens?

  • Resposta: Sim. Mas o foco foi utilizar a API do Weka. Grails foi objetivo secundário. Ainda assim, melhorias precisam ser feitas.

---

Licenciamento (copyright) 

O trabalho aqui foi criado e disponibilizado para estudo acadêmico.

Não somos donos da Linguagem, Biblioteca Weka etc. Cada um destes produtos tem sua própria licença.

Com o código aqui disponível, você pode: copiar, colar, alterar, clonar... enfim, fazer o que achar conveniente.

O Weka Plus Grails é um projeto inicial, um protótipo.

Portanto, saiba que ao utilizá-lo, ele pode não estar conforme com as boas práticas de programação e de uso da API do Weka. Use por sua conta e risco.

Mas enfim, aproveite-o!

---

Changelog 

Caso queira visualizar o histórico de mudanças neste modelo, simples: leia os commits deste repositório Git!

Neles é possível saber, por exemplo, o que foi implementado, modificado, em que período de tempo...

Detalhe: procuramos fazer as mensagens dos commits bem organizadas e informativas. Mas há exceções, claro. Exemplo: commits enviados de forma equívocada, com pouca mensagem, commits sem importância alguma para o entendimento do modelo etc.

Ainda assim, a maioria dos commits representa muito bem o registro de mudanças (changelog) e avanços na criação do Weka Plus Grails.

---

Melhorías para o futuro ∞

Algumas questões que podem ser implantados nas próximas versões:

• Disponibilizar o sistema online para facilitar a execução sem precisar baixar nada.
  • Ou seja, fazer deploy do arquivo war do projeto. Possíveis sites para armazenar a versão seria:
    • http://www.cloudbees.com/
    • http://java.herokuapp.com/
    • http://www.cloudfoundry.com/
    • ... qualquer outro que suporte java.
  • Disponibilizar um banco de dados pré-salvo no aplicativo
    • Cadastrar nele 3 ou mais instâncias, salvas e prontas para consulta
      • Assim qualquer usuário já verá o sistema com dados armazenados e facilita o entendimento
    • Incluir rotina para limpar o banco de dados com frequência
• Reduzir a quantidade de telas: para tornar o aplicativo mais simples;
  • tudo numa única página, um único formulário, quase um script online;
  • usar um modelo (template, layout) mais leve e personalizado. Abandonar o template do scaffold provido pelo Grails;
• Melhorar a documentação, ou seja, este README.
  • Deixá-lo mais compacto, direto, objetivo e bem escrito;
• Refinar a implementação com um código mais elegante e simples.
  • Retirar redundâncias
  • Refatorar
  • Usar variáveis mais globais (exemplo a variável webAppRootPath)
  • Aplicar Exceptions e blocos try-catch
• Fazer um script Groovy, para executar tudo com uma única linha de comando;
• Enviar o código criado para a wiki oficial do Weka com o groovy
  • Adicionar também link para este nosso projeto Grails do github/bitbucket
  • Incluir links dos deploies do projeto
  • submeter tutorial do Weka com foco no groovy
  • submeter tutorial do Weka com foco no grails
• Adotar novas idéias e práticas, caso aparecam :)

---

Agradecimentos 

Queremos agradecer:

• Aos desenvolvedores da IDE Eclipse, Git, do Weka, Egit, Groovy e Grails, pois estes sistemas facilitaram e muito a criação e organização deste projeto.
• As diversas comunidades online, pela documentação e tutoriais que auxiliaram quando os manuais oficiais não foram suficientes para responder as dúvidas;
• E antecipadamente, as futuras contribuições que venhamos receber pelos visitantes nestes repositórios remotos que se encontram online e acessíveis a todos.

---

Desejamos bons desenvolvimentos de aplicativos, a quem interessar! 

Cordialmente,

Paulo de Lima Cavalcanti
(www.paulolimac.com)