Cortext/Tutoriais/A aplicação Cortext Manager

História

Cortext Manager surge de uma vontade de promover e parear o desenvolvimento e a popularização de métodos computacionais apropriados às pesquisas em ciências sociais e humanas. Visando a comunidade acadêmica mas também a sociedade civil, os agentes de instituições públicas ou do setor privado. A história começa em 2008 na unidade de pesquisa francesa SenS (Ciências em Sociedade), que a partir de 2011 publica uma primeira aplicação pública inspirada de trabalhos acadêmicos do grupo e de colegas, que remontam às análises “co-word” de Michel Callon como também se inspiram dos trabalhos em análise de redes sociais. A unidade muda de nome para LISIS (Laboratório Interdisciplinar Ciências Inovações Sociedades) e em 2016 inaugura uma nova versão da aplicação. Se a aplicação sempre foi oferecida gratuitamente, foi recentemente que a plataforma começou a adotar integralmente práticas alinhadas com a ciência aberta: publicação dos códigos dos métodos de análise sob licenças livres, publicação de ambientes de execução visando a reprodutibilidade das análises, e — em uma parceria com o CCSL da USP — implementação de boas práticas de engenharia de software viabilizando sustentabilidade e colaboração em torno dos métodos.

A aplicação e sua documentação

A aplicação Cortext Manager encontra-se no endereço: https://managerv2.cortext.net/

A documentação da aplicação e de suas operações encontra-se no endereço: https://docs.cortext.net/

Elementos e fluxo de trabalho

Conta

Iniciamos o uso do Cortext Manager criando uma conta ou conectando-nos a uma conta existente. Esta conta irá identificar-nos em nossos usos e interações dentro do aplicativo.

Dashboard

O "Painel Inicial" (Dashboard), primeira tela do aplicativo, nos mostra a última atividade para cada um dos nossos projetos mais recentes.

Projeto

O primeiro passo para usar o Cortext Manager é a criação de um projeto. Basta preencher o nome do projeto e clicar em “Criar um projeto”.

Ações

Em um projeto, a qualquer momento, três ações principais são possíveis:

« Upload file » : Faça o upload de um novo arquivo. Um arquivo .zip contendo um conjunto de dados (dataset) em um dos vários formatos suportados. Ou um arquivo com informações adicionais usadas por um dos métodos, por exemplo, uma lista de termos a serem extraídos, no formato .tsv.
« Start script » : Executar uma operação, normalmente sobre um corpus. Os vários tipos de operação existentes serão discutidos em uma seção dedicada. Também é possível executar uma operação em um conjunto de dados para transformá-lo em corpus.
« Start discussion » : Iniciar uma nova discussão entre os membros de um projeto.

Para cada ação realizada em um projeto, um novo item é adicionado à sua linha do tempo.

Linha do tempo

A linha do tempo do projeto é a sequência de itens correspondo às ações executadas. Ela é cronológica, o que possibilita entender a ordem das ações, e pode ser filtrada por texto usando o campo na parte superior. Várias ações são possíveis em um item da linha do tempo e serão discutidas em uma seção dedicada.

Gestão

Também encontramos na página de um projeto elementos e funções para gerenciá-lo. À esquerda da linha do tempo, é possível: ver o progresso das últimas operações do projeto, ou a lista de análises favoritas; ver os conjuntos de dados do projeto e filtrar os itens associados clicando em seu nome; ver os participantes de um projeto e seu volume de atividades, filtrar os itens de ações de cada usuário, e adicionar novos usuários ao projeto. No painel à direita, é possível: consultar e modificar o nome e a descrição do projeto; obter diferentes formatos para citar o aplicativo em nossos trabalhos; arquivar, baixar ou excluir o projeto.

Conjunto de dados e corpus

No Cortext Manager, chamamos de “dataset” um conjunto de dados carregado para criar um corpus. Correspondentemente, chamamos de “corpus” o banco de dados obtido pela importação de um “dataset”. O interesse dessa conversão é que o formato do corpus é adaptado às operações da aplicação.

A operação que converte um “dataset” em um “corpus” chama-se Data parsing. Vários formatos de conjunto de dados podem ser importados por esta operação, e existe uma descrição detalhada dos formatos suportados.

As duas etapas fundamentais de qualquer projeto são portanto: fazer upload de um “dataset” no formato .zip com a ação “Upload file” e, em seguida, convertê-lo em corpus com a operação Data parsing. Essa operação pode ser acessada: clicando em um link proposto no final de qualquer upload de um “dataset”; ou através da ação "Start script", conforme explicado na seção dedicada às operações.

Operação (script)

Uma vez selecionada a ação “Start script”, a aplicação propõe uma lista de operações, organizada de acordo com seis categorias com cores distintas. Apesar das instruções de uso comuns expostas aqui, essas operações servem a propósitos muito diferentes, e uma seção deste documento é dedicada a explicar conceitualmente suas finalidades. Aqui trataremos dos elementos comuns à execução de qualquer operação.

Uma vez escolhida a operação que queremos executar, somos apresentados à uma escolha do corpus sobre o qual operar. A única exceção é a operação Data parsing que oferecerá uma escolha de "dataset", para criar um corpus.

Parâmetros

A operação e o corpus definidos, devemos decidir como parametrizá-la. Uma operação pode ter qualquer número de parâmetros, que são apresentados em um formulário e podem ser organizados em seções, ou mesmo em várias abas. Por exemplo, é nos parâmetros que escolheremos, se houver, em quais colunas de nossos dados a operação deve atuar, que tipo de modelagem aplicar aos dados, quais dimensões exibir em uma visualização, e outros detalhes do funcionamento da operação. Alguns parâmetros têm valores predefinidos ou são obrigatórios, outros são opcionais.

Se o formulário contém explicações breves dos parâmetros, é na documentação para cada operação que vamos encontrar o necessário para entendê-los em profundidade. Além de acessar diretamente o site da documentação, ela também está disponível pela lista de operações através dos ícones “ℹ️”, ou no formulário de parametrização das operações por um link no seu início.

Dito isto, e especialmente para operações com múltiplos parâmetros que são difíceis de entender, é perfeitamente aceitável usar uma operação preenchendo apenas algumas escolhas simples, e manter os outros parâmetros no seu valor padrão, confiando a escolha aos curadores da operação.

Execução

Finalmente, uma vez escolhidos os parâmetros da operação, ela pode ser executada clicando no botão “Start script”.

Resultados de uma operação

Operação executada
Entradas	Operação	Saídas	Descrições das saídas
Operação Corpus Parâmetros	⇒	Item na linha do tempo	Título Texto (se houver) Resultados visíveis Botões
		Registro da operação	Relato detalhado da execução
		Resultados não visíveis	Modificações do corpus Outros dados internos à operação

Uma operação executada é uma ação e, portanto, gera um item na linha do tempo do projeto. A partir deste item, temos acesso a uma série de elementos:

Título: o título do item conta a operação lançada, o corpus sobre o qual agiu, a data e o avatar do usuário responsável;
Texto: o texto do item, se presente, fornece informações relevantes sobre os resultados da operação;
Resultados visíveis: ao centro do item na linha do tempo encontram-se uma série de arquivos que constituem a parte visível dos resultados da operação;
Barra inferior:
- À esquerda: encontramos a data e hora operação, bem como um identificador “analysis id”;
- À direita: cinco botões são visíveis e permitem, respectivamente: retornar ao formulário de parâmetros para executar uma nova operação com as mesmas entradas, ou modificá-las; acessar o Registro da operação, ou seja, um relatório detalhado de seu progresso; excluir o item da operação; marcar o item como favorito; deixar um comentário no item.

E para além do item:

Resultados não visíveis: uma outra parte dos resultados não é visível, por exemplo, se correspondem a alterações no corpus como o acréscimo de uma nova coluna aos dados ou a modificação de uma coluna existente.

Entendendo as operações na Cortext Manager

Existem quatro grupos principais de operações possíveis, geralmente utilizados em ordem.

Aquisição de dados (categoria Corpus no painel): Data parsing, Query, Corpus from query
Leitura e edição (categoria Corpus no painel): Corpus explorer, Data curation, Data slicer
Busca e manipulação de entidades (categoria Text no painel)
Métodos de análise
- Especializados
  - Tempo (categoria Time no painel)
  - Espaço (categoria Space no painel)
- Genéricos
  - categoria Analysis no painel, onde cada item corresponde a um método independente
  - categoria SASHIMI no painel: onde cada item corresponde a uma etapa do método Sashimi

Para entender o uso das operações, recomendamos ler as descrições no painel de escolha apresentado ao clicar-se em Start Script, depois clicar no ícone ℹ️ à direita da descrição para acessar a documentação completa de cada operação. Também é possível navegar diretamente o site de documentação da aplicação.