Estrutura das análises

[guilhermelowa]

Alguns pontos importantes:

• Os resultados das análises tem que estar apresentados de forma fácil, inclusive pra quem não é da área técnica (por ex, jornalista ou advogado que quer ver a análise de algum dado pra entrar com a expertise dele)
• As análises tem que estar bem referenciadas. Os resultados com data e local de acesso (pelo mesmo motivo acima, se alguém quiser usar, tem que tá referenciado direitinho); O dataset utilizado referenciado (de preferência no começo do notebook), de preferência com a data da coleta dos dados. Assim você sabe se aquela análise usa os dados mais recentes ou não, de quando é o dataset, etc.
• Organizar o repositório pra que seja fácil encontrar ou editar as análises.
  • Alterar o CONTRIBUTING.md a medida que as coisas forem sendo estipuladas aqui.

Pensei em 5 pontos principais sobre a formatação das análises e do repositório. Resolvi criar uma Issue só porque mexendo um item você acaba mexendo os outros, ao menos a princípio.

• [x] 1- Referências
• [ ] 2- A estrutura de diretórios das análises
• [x] 3- Onde adicionar novas análises
• [x] 4- Estrutura do código do notebook
• [x] 5- Nomeação dos notebooks

1- A cada resultado, ter associado a ele de onde vieram os dados e a data de acesso. Pra referenciar, mesmo. Além disso, no começo do notebook, referenciar os datasets utilizados - pra quem for depois olhar a análise saber qual dataset e de quando era. Pode ser útil rodar o mesmo notebook num dataset mais atualizado ou atualizar o notebook anterior com dados mais recentes. O que vocês acham?

2- O que eu pensei de estrutura foi o seguinte: repo/analises: -> contratos (Pasta do projeto - podia ser: COVID, câmara, licitações) ->> exploração_inicial.ipynb ou talvez .html (descrição do dataset) ->> análise_a.ipynb (notebook com análise A) ->> análise_b.ipynb (notebook com análise B) -> COVID (outro projeto) ->> repete...

3- E aí vem a questão: cada análise um notebook? Ou só adicionar uma nova célula com uma nova análise e cabou? A vantagem da primeira abordagem é que fica mais organizado. A vantagem da segunda é que os resultados ficam centralizados. Se tiver um HTML com os resultados, então a pessoa ao submeter um notebook pode tb incrementar o HTML com os resultados dela, né? Mas até lá, faz como? Primeiro eu tinha pensado em criar células aninhadas pra cada análise, assim você podia colapsar ou expandir cada análise, exploração inicial, parte do código que não é resultado etc. Tipo aqui.

4- A questão da estrutura que pensei tá relacionado ao que falei acima: centralizar os resultados pra ficar fácil pra quem vai depois utilizar eles em um texto, processo, inquérito, etc. Aí tinha pensado em fazer as células aninhadas, como falei acima. A primeira parte, de preparação e mais voltada pra quem tb é técnico. A segunda, os resultados. E aí quem só quer ver os resultados pode minimizar toda a parte de preparação. Não sei se faz muito sentido, também... O ideal era exportar os resultados pra um outro lugar, como o HTML, onde só tivesse os resultados com explicações e referências. Aí nesse caso este item 4 nem seria uma questão, eu acho.

5- Os notebooks do serenata de amor são data-autor-nome.ipynb. Acho que data e autor não fornecem muita informação no nosso caso. Pelo que eu entendi esse repositório deles é bastante educacional, então funciona pra eles. Prefiro: .ipynb. Assim fica fácil de achar onde tá o que. Tanto pra editar quanto pra ver os resultados. Isso se for o modelo apresentado em 2. Se todas as análises ficarem juntas num notebook só, então podia ser só analises-.ipynb.

[guilhermelowa]

Na verdade, sobre o item 5 acho melhor TEMA_NOME-da-analise_DATA-do-dataset.ipynb Assim você sabe, sem abrir, do que se trata, qual análise tá sendo feita e de quando é o dataset.

[guilhermelowa]

Um outro ponto sobre os nomes (5) é que acho que não deve ter acentos e outros caracteres estranhos (ç talvez). Só ASCII, acho? Não sei.

Se não, nos pulls fica aparecendo caracteres esquisitos:

[guilhermelowa]

Quase tudo mencionado já foi resolvido / decidido. No entanto, surgiu uma questão:

O número de notebooks e scripts tá crescendo e até então os dados utilizados neles estão na mesma pasta. Eu acho um pouco bagunçado.

Minha sugestão:

criar uma pasta data/ dentro de analysis. Dentro de data/, ter subpastas pra cada origem do dado. Por ex: data/images/, data/tse, data/city_hall, data/city_council.

Esse mesmo problema pode acontecer com a pasta /data, que no momento tem as especificações das despesas. Mover essas especificações pra cada subpasta acima é uma opção. Por exemplo: analysis/data/tse/dictionary/, ou algo semelhante.

Acho que ter duas pastas "data", mesmo em níveis diferentes, fica um pouco confuso. Agora mesmo pra explicar eu tive que pensar um pouco em como distinguir.

[anapaulagomes]

Eu não consegui entender, na real, @guilhermelowa. Os dados usados nas análises não tem que ser commitados, então cada pessoa pode organizar como quiser e documentar. Ainda não temos um volume muito grande de análises. Quando acontecer, podemos voltar pra essa discussão.