- Objetivos
- Nomenclaturas
- Gerenciamento da informação
- Painel de administrador
- Tutorial
- Detalhamento de tecnologias e metodologias
- Considerações finais
Este documento tem como objetivos (i) a documentação das tecnologias e metodologias utilizadas na elaboração e manutenção da plataforma República em Dados (RED), (ii) exposição de como a informação é gerenciada pela República.org, (iii) o detalhamento sobre o painel de administrador e, por fim, (iii) a apresentação de um passo a passo para inserção de novos dados.
2. Nomenclaturas
Para facilitar a comunicação no presente
documento, serão usadas algumas siglas importantes para todo o processo
do RED:
- RED - Abreviação de República em Dados.
- DV - Sigla para data view, que se refere a cada gráfico ou tabela disponibilizada no painel de dados do RED.
- GBQ - Sigla para “google bigquery”, ferramenta utilizada na infraestrutura de dados do República em Dados.
3. Gerenciamento da informação
A infraestrutura dos dados encontrados no República em Dados (RED) é feita pelo bigquery. Entretanto, uma parte do gerenciamento da informação acontece através do google drive pois é a ferramenta de armazenamento utilizada pela organização. Além disso, utilizamos também o github, por se tratar de um ambiente mais amigável para armazenamento de códigos.
Existe uma pasta no google drive da instituição que se chama “Ecossistema de Dados” e ela foi clonada no github no seguinte repositório: https://github.com/Republica-org/Ecossistema-dados. Neste repositório constam todos os códigos utilizados no tratamento e limpeza dos dados, aqueles utilizados na subida dos dados para o bigquery e também os esquemas utilizados no painel de administrador.
Existem quatro pastas organizando esses arquivos e suas subpastas estão detalhadas no esquema abaixo:
Imagem 1: Organização das pastas no github ddo repositório ” Ecossistema
de dados”
Na pasta de esquemas estão organizados todos os
esquemas em JSON que são inseridos no painel de administrador para
geração dos gráficos. Deixamos um backup nesta pasta pois
editamos o arquivo no VScode e lá contamos com uma melhor
usabilidade e visualização do documento. Além disso, o arquivo é uma
parte fundamental para produção dos gráficos no sistema, então ter esse
registro é importante para replicabilidade do gráfico em caso de perda
de acesso. Todos os esquemas estão organizados em subpastas
corrrespondentes a categoria a qual o seu respectivo gráfico
pertence.
Na pasta de notas estão as notas metodológicas e os
detalhes metodológicos de cada um dos gráficos, os quais estão
organizados na pasta de mais_detalhes. Nessa parte de
mais_detalhes são guardados arquivos em markdown que
possuem informações gerais sobre a metodologia de cada DV (dataview) e
os links dos scripts de tratamento que encaminham o usuário para o
github. Abaixo temos um exemplo de como é essa parte do detalhe
metodológico:
Código 1: Detalhes metodológicos do gráfico de total de profissionais de
saúde
<br>
Foi consultada a base do CNES de janeiro de cada ano. O CNES aqui foi consultado diretamente do datalake da Base dos Dados.
<br>
<details>
<summary><b> 1º passo:</b> Pré-tratamento: </summary>
Acesso em:
[https://github.com/Republica-org/Ecossistema-dados/blob/main/pre_tratamento/tratamento_BD/CNES_vinculo_saude_tipo_ocupacao.sql](https://github.com/Republica-org/Ecossistema-dados/blob/main/pre_tratamento/tratamento_BD/CNES_vinculo_saude_tipo_ocupacao.sql)
</details>
<details>
<summary><b> 2º passo:</b> Tratamento e subir no GBQ da República.org:</summary>
Acesso em:
[https://github.com/Republica-org/Ecossistema-dados/blob/main/tratamento_GBQ/perfil_remuneracao/CNES_total_profissionais_saude.ipynb](https://github.com/Republica-org/Ecossistema-dados/blob/main/tratamento_GBQ/perfil_remuneracao/CNES_total_profissionais_saude.ipynb)
</details>
Na pasta de pre_tratamentoestão organizados os códigos
em python, R ou queries do SQL que foram utilizados para
limpeza dos dados e filtragens necessárias. Não são todos os DV que
passam pela etapa de pré-tratamento, essa etapa depende da complexidade
de transformação da fonte original para uma arquitetura de dados
compatível com o RED. Na pasta de tratamento_BD estão as
queries utilizadas pela Base
dos Dados, organização que nos auxiliou no tratamento de alguns dos
dados presentes no RED. Eles possuem um datalake próprio e para
alguns dos gráficos consultamos diretamente esse datalake que já
passou pelo tratamento deles. Na pasta de
tratamento_republica constam os scripts de um
pré-tratamento feito pela equipe interna e as pastas estão divididas
pela fonte do dado.
Na pasta de tratamento_GBQestão os scripts
utilizados para realizar o tratamento final dos DV e subida desses dados
para o GBQ através do uso das bibliotecas pandas_gbq e
bigquery do python. Foi utilizada a API do GBQ
para quase todos os DV.
Todos os dados (DV) existentes no RED estão catalogados em uma tabela
que consta no googledrive da República.org e que se chama
Galáxia de dados. Nesta tabela estão os cadastros de todas as DV,
na aba de “lista de dados” e as informações necessárias para cadastro no
painel de administrador. Esse registro é feito para que em caso de falha
no site, ainda se tenha o registro de todas as informações. A aba de
“Gráficos” é um ambiente de criação para se desenhar o tipo de gráfico
utilizado para cada dado e sua arquitetura.
Todo o fluxo de informação do RED pode ser visto no esquema abaixo:
Imagem 2: Fluxo de informação do RED
A parte de arquitetura da tabela é crucial para criação dos DV. É nessa fase que são definidos quais tipos de gráficos serão utilizados e o que queremos apresentar com esses gráficos. A lógica da geração desses gráficos é uma lógica de queries, aonde alimentamos o sistema com parâmetros que vão realizar consultas no GBQ para geração do gráfico. Exemplo: imagine que queremos gerar um gráfico de linha aonde o eixo x seja o ano e o eixo y seja a quantidade de servidores e queremos aplicar alguns agrupamentos e filtros. Para tal, será feita a seguinte consulta:
Código 2: Exemplo de consulta SQL a ser feita no back-end
SELECT ano, [nome das colunas selecionadas no esquema JSON para agrupamento], sum(quantidade_servidores)
FROM [table_id]
WHERE [nome das colunas selecionadas no esquema JSON para filtro]
GROUP BY ano,[nome das colunas selecionadas no esquema JSON para agrupamento]
Para que essa consulta funcione, precisamos que a tabela a ser
consultada tenha uma coluna de ano, uma coluna com quantidade de
servidores e para cada variável a mais a ser usada em filtros ou
agrupamentos, que essa quantidade de servidores esteja desagregada para
todas as suas categorias. Nesse cenário, caso se some todos os valores
da coluna de quantidade de servidores, obtemos o universo observado. O
número de linhas deve ser o produtório da quantidade de categorias de
todas as variáveis categóricas:
Imagem 3: Cálculo da quantidade de linhas que uma tabela do RED deve ter
nos casos exemplificados
\({\displaystyle \prod_{i=1}^n C_{i}}\)
Aonde C é a quantidade de categorias de cada variável, incluindo a
variável utilizada no eixo, que nesse caso é o ano e o n é
o número de colunas com variável categórica da tabela.
Na parte do GBQ, foram criados datasets para cada uma das categorias
e as tabelas criadas são distribuídas de acordo com sua respectiva
categoria. Existe um dataset chamado datalake que armazena
tabelas pré-tratadas para consulta no RED. É importane salientar que por
se tratar de uma metodologia de consulta ao GBQ, a tabela a ser
consultada deve ser a mais otimizada possível em termos de tamanho, pois
caso contrário, a consulta ficará inviável e muito custosa.
O painel de administrador é uma plataforma hospedada no Keystone 6 que está direcionada no endereço https://apidados.republica.org/. Através dela os usuários cadastrados podem acessar o painel de administrador e gerenciar muitos dos conteúdos presentes no RED. O objetivo é trazer maior autonomia para que a instituição consiga criar novas visualizações, cadastrar notas metodológicas, inserir estudos e tornar a plataforma perene e sustentável.
Imagem 4: Printscreen do dashboard principal
Ao longo desta seção serão apresentadas todas as páginas existentes no painel de administrador e a explicação de todos os campos presentes nelas. Além disso, será feita uma seção específica para o esquema em JSON, que é a estrutura utilizada para a elaboração dos gráficos presentes no painel de dados.
4.1 Users
A página users é o ambiente para criação e edição dos
usuários do painel. Ao entrar nessa página aparecerá uma lista com os
usuários existentes e na parte superior há um botão escito
Create User, o qual possibilita a criação de um novo
usuário.
Para criar um novo usuário é preciso cadastrar um e-mail, configurar uma senha e definir o tipo de privilégio que esse usuário irá ter. São duas as opções de privilégio:
Administrator - Pode criar data views, criar notas, categorias, dúvidas frequentes e gerenciar todos os usuários.
Content Administrator - Pode criar data views, criar notas, categorias e dúvidas frequentes.
É recomendado que pelo menos duas pessoas da organização tenham o privilégio de Administrator.
4.2 Data Views
Esta é a área de criação dos gráficos presentes na página de painel de dados do RED. Aqui são cadastrados todas as informações para geração dos gráficos, de metadados, de recursos para filtragem e as notas metodológicas.
Imagem 5: Printscreen do dashboard da página de Data Views
Assim como na página anterior, ao clicar no botão de Data
Views a partir do dashboard principal, o usuário será
encaminhado para a listagem de cadastros disponíveis. Nesta área é
possível ordenar a lista pelo botão de sorted by e também
escolher quais colunas o usuário deseja visualizar através da lista
suspensa ao lado de with 3 columns. Por padrão, será possível
ver a label do data view, o status de publicação
(Publishing Status) e a url para acesso. É possível
escolher o data view para editar, clicando na label
correspondente e também criar um novo ao se clicar no botão
Create Data View.
Na área de criação do Data View existem 29 campos, aonde 7 deles são preenchidos automaticamente e 22 precisam ser preenchidos pelo usuário. O detalhamento de todos os campos segue abaixo:
Tabela 1: Conteúdo dos campos da página de  Data Views
| Nome do campo | Conteúdo | Preenchimento automático ou manual |
|---|---|---|
| Label | Nome da tabela como você quer que apareça na listagem do painel de dados. | Manual |
| Publishing Status | Lugar de escolha entre rascunho e publicar tabela. Caso esteja querendo fazer testes ou não finalizou o cadastro escolha “Draft”. Caso esteja tudo finalizado escolha “Published”. | Manual |
| Slug | É o trecho da url que será criado para endereçar aquele dado. Exemplo: “https://dados.republica.org/dados/quantidade-de-vinculos-publicos-civis-ativos“, para esse caso o slug é o”quantidade-de-vinculos-publicos-civis-ativos”. | Automático |
| Description | Campo aonde é possível trazer informações fundamentais para entendimento daquele gráfico ou algum destaque importante. O conteúdo deste campo irá aparecer no módulo do gráfico, na parte inferior, aonde temos o título “DESCRIÇÃO:” | Manual |
| Big Query Full Table Id | É o código do id da tabela no bigquery a ser utilizada para elaboração do gráfico. Na parte de “details” do bigquery há um campo de “Table ID”, basta copiar o código da respectiva tabela e colcar neste campo. Mais detalhes sobre esse fluxo será apresentado na seção de “Tutorial”. | Manual |
| Categories | Escolha da categoria a qual aquele gráfico pertence. As categorias correspondem aos grandes circulos naquele esquema de grafos do painel de dados. Podem ser escolhidas mais de uma categoria. | Manual |
| Related Library Items | Aqui são inseridos os itens da biblioteca que esse gráfico posui relação ou é usado como insumo. O objetivo é que na aba de “Biblioteca” apareça junto ao trabalho listado esses dados que foram utilizados para a elaboração daquele produto. São os dados que aparecem em “Dados Relacionados” nos trabalhos da biblioteca. | Manual |
| Reference To Data Views | Aqui são inseridas as outras data views que possuem relação com essa data view criada. Esse campo permite a conexão na rede de grafos do painel de dados. | Manual |
| Reference From Data Views | Aqui aparecem as data views que cadastraram a presente como relacionada. | Automático |
| Schema | Esse é o campo que suporta uma entrada em JSON para a elaboração do gráfico. As possibilidades desse campo serão detalhadas na seção de “Esquema JSON e os tipos de gráficos”. | Manual |
| Big Query Table Metadata | Campo que aparece o metadata da tabela. O valor deste campo alimenta a parte de dicionário de variáveis da metodologia. | Automático |
| Fonte | Campo aonde é cadastado a fonte original daquele dado. | Manual |
| Tratamento Primario Dos Dados | Qual instituição fez o primeiro tratamento daquele dado. | Manual |
| Tratamento Secundário Dos Dados | Qual instituição tratou o dado após tratamento da primeira instituição. Esses campos são diferentes pois alguns dados possuem fonte indireta. Exemplo: os dados da RAIS são provenientes do datalake da Base dos Dados e a República.org faz um outro tratamento a partir do tratamento deles. | Manual |
| Cobertura Temporal | Cobertura temporal daquela tabela. Pode ser um ou mais anos específicos ou um intervalo. Quando for intervalo, cadastrar como: “2010-2020”, quando for um retrato de determinado(s) ano(s), cadastrar como: 2010, 2012 e 2014. | Manual |
| Unidade | Unidade de análise daquela tabela. Especificar se ela se refere a vínculos, pessoas, legislações, territórios. | Manual |
| Metodological Details | Aqui serão colocados todos os detalhes metodológicos de tratamento daquela informação e os links para acesso ao script original. Mais detalhes podem ser vistos na seção “Detalhes Metodológicos”. | Manual |
| Keywords | Aqui podem ser cadastradas palavras-chave para busca do gráfico no painel de dados. A funcionalidade de busca do painel consegue buscar a fonte do dado, as labels cadastradas e as palavras cadastradas nesse campo. | Manual |
| Recorte territorial | Definição do recorte territorial da tabela. É o nível de desagregação por território. | Manual |
| Poderes | Quais poderes são considerados nessa tabela. | Manual |
| Esferas federativas | Quais esferas federativas são consideradas na tabela. | Manual |
| Setores | Setores específicos da administração pública que esses dados se referem. Exemplo: educação, segurança pública, saúde. | Manual |
| Dados sócio demográficos | Quais dados sociodemográficos estão presentes nesta tabela. | Manual |
| Tipo de administração | A tabela pode se referir a administração direta ou indireta. | Manual |
| Full Data Attachment | Campo para anexar a tabela completa. Para acesso a tabela no BQ e para salvar localmente a fim de anexar neste campo, consultar o seguinte script: https://github.com/Republica-org/Ecossistema-dados/blob/main/tratamento_GBQ/baixar_tabelas.ipynb | Manual |
| Created At | Data de criação. | Automático |
| Updated At | Data de atualização. | Automático |
| Created By | Identificador do usuário que criou. | Automático |
| Updated By | Identificador do usuário que atualizou. | Automático |
4.3 Categories
Página de cadastro de novas categorias. Nesta página é possível editar a label da categoria, a cor correspondente a ela no painel de dados (todas as cores cadastradas estão no manual de marca da República.org) e também cadastrar os data view. Entretanto, é recomendado que o cadastro das categorias no dsta view se restrinja a seção de Data Views.
4.4 Library Items
Página para inserção da chamada paras estudos, notas técnicas e reltórios na página da biblioteca. Todos os documentos são hospedados no site institucional da República.org e aqui são cadastrados os nomes, imagens, links para encaminhamento até o documento e dados relacionados. Essa disponibilização tem como finalidade permitir uma outra forma de acesso para quem se interessa pelos estudos da República.org e para que seja possível a relação entre o documento e os dados do painel de dados.
4.5 Library Item Tags
A página permite a criaçaõ de tags para identificar diferentes tipos de documentos dentro da página de “Biblioteca”. A criação é livre e também é possível cadastrar os itens de bibliotecadiretamente na parte das tags.
4.6 Metodological Notes
Aqui são criadas notas metodológicas gerais que não se referem a nenhum data view específico. A entrada compatível é um arquivo markdown.
4.7 Frequently Asked Questions
Nesta seção é possível cadastrar perguntas frequentes e suas respostas para auxiliar o usuário a utilizar a plataforma. A entrada deste conteúdo aparece na página de “Sobre” na seção de “Perguntas Frequentes”.
4.8 O esquema JSON
No campo Schema da página de Data Views deve ser inserido um conteúdo em formato JSON que seja alimentado com os parâmetros necessários para formação de cada um dos gráficos. Nesta seção serão apresentados os exemplos de esquemas de cada um dos tipos de gráficos cadastrados: gráfico de linhas, de barras, de pizza, mapa de variável contínua, mapa de variável categórica e tabela. Nesta seção também serão descritos os principais campos para preenchimento. Como os códigos em seguida estão escritos em JSON, para fins explicativos utiliza-se ‘//’ apenas para comentar o código, sem alterar o script.
- Gráfico de linha
Abaixo está o esquema utilizado para elaboração do gráfico de linha do DV chamado de “Vínculos Públicos Civis Ativos”.
Código 3: Esquema em JSON do gráfico de “Vínculos Públicos Civis Ativos”
{
"view": {
"type": "data_series", //tipo de série.
"range": [
{
"label": "Total de vínculos",
"value": "quantidade_vinculos_sum" // nome da coluna utilizada na agregação seguida da operação matemática de agregação.
}
],
"domain": "ano", //eixo x
"groupBy": [
{
"label": "---",
"value": "" // ao adicionar um value vazio o padrão é aparecer sem nenhum agrupamento.
},
"sexo",
"poderes",
"grau_instrucao",
"esfera",
"faixa_etaria",
"carga_horaria",
"tipo_vinculo"
],
"filterBy": [
"sexo",
"poderes",
"grau_instrucao",
"esfera",
"faixa_etaria",
"carga_horaria",
"tipo_vinculo"
],
"chartType": "lines",
"dataSourceType": "aggregation",
"filterByStateId": "sigla_uf"
},
"variables": {
"ano": {
"type": "continuous",
"label": "Ano"
},
"sexo": {
"type": "categorical",
"label": "Gênero",
"options": [
{
"value": "Feminino",
"color": "dark-blue",
"label": "Feminino"
},
{
"value": "Masculino",
"color": "green",
"label": "Masculino"
}
],
"phrasePrefix": "do gênero"
},
"esfera": {
"type": "categorical",
"label": "Esfera federativa",
"options": [
{
"value": "Municipal",
"color": "dark-blue",
"label": "Municipal"
},
{
"value": "Estadual",
"color": "orange",
"label": "Estadual"
},
{
"value": "Federal",
"color": "green",
"label": "Federal"
},
{
"value": "Outros",
"color": "light-grey",
"label": "Outros"
}
],
"phrasePrefix": "que atuam na esfera"
},
"poderes": {
"type": "categorical",
"label": "Poderes",
"options": [
{
"value": "Executivo",
"color": "dark-blue",
"label": "Executivo"
},
{
"value": "Legislativo",
"color": "orange",
"label": "Legislativo"
},
{
"value": "Judiciário",
"color": "green",
"label": "Judiciário"
},
{
"value": "Outros",
"color": "light-grey",
"label": "Outros"
}
],
"phrasePrefix": "que atuam no poder"
},
"sigla_uf": {
"type": "categorical",
"label": "UF",
"options": [
"IGNORADO",
"AC",
"AL",
"AM",
"AP",
"BA",
"CE",
"DF",
"ES",
"GO",
"MA",
"MG",
"MS",
"MT",
"PA",
"PB",
"PE",
"PI",
"PR",
"RJ",
"RN",
"RO",
"RR",
"RS",
"SC",
"SE",
"SP",
"TO"
]
},
"faixa_etaria": {
"type": "categorical",
"label": "Faixa etária",
"options": [
{
"value": "Entre 18 e 29 anos",
"color": "dark-blue",
"label": "Entre 18 e 29 anos"
},
{
"value": "Entre 30 e 49 anos",
"color": "orange",
"label": "Entre 30 e 49 anos"
},
{
"value": "Entre 50 e 65 anos",
"color": "green",
"label": "Entre 50 e 65 anos"
},
{
"value": "Acima de 65 anos",
"color": "red",
"label": "Acima de 65 anos"
},
{
"value": "Ignorado",
"color": "light-grey",
"label": "Ignorado"
}
],
"phrasePrefix": "com idade"
},
"tipo_vinculo": {
"type": "categorical",
"label": "Tipo de vínculo",
"options": [
{
"value": "Estatutário",
"color": "dark-blue",
"label": "Estatutário"
},
{
"value": "CLT",
"color": "orange",
"label": "CLT"
},
{
"value": "Estatutário não efetivo",
"color": "green",
"label": "Estatutário não efetivo"
},
{
"value": "Diretor",
"color": "purple",
"label": "Diretor"
},
{
"value": "Temporário",
"color": "red",
"label": "Ignorado"
},
{
"value": "Aprendiz contratado",
"color": "pale-green",
"label": "Aprendiz contratado"
},
"Avulso",
"CLT/Rural",
"Contratado/prazo determinado",
"Contratado/tempo determinado"
],
"phrasePrefix": "com vínculo do tipo"
},
"carga_horaria": {
"type": "categorical",
"label": "Carga horária",
"options": [
"20 horas",
"30 horas",
"40 horas ou mais",
"Ignorado"
],
"phrasePrefix": "com carga horária de"
},
"grau_instrucao": {
"type": "categorical",
"label": "Grau de instrução",
"options": [
{
"value": "Até Fundamental ",
"color": "dark-blue",
"label": "Até Fundamental "
},
{
"value": "Até Ensino Médio",
"color": "orange",
"label": "Até Ensino Médio"
},
{
"value": "Até Ensino Superior Completo",
"color": "green",
"label": "Até Ensino Superior Completo"
},
{
"value": "Até Pós Graduação",
"color": "red",
"label": "Até Pós Graduação"
}
],
"phrasePrefix": "que cursaram"
},
"quantidade_vinculos": {
"type": "continuous",
"label": "Quantidade de vínculos"
}
}
}
- Gráfico de barras
Abaixo está o esquema utilizado para elaboração do gráfico de barra do DV chamado de “Comparação de remuneração entre setor público e privado”.
Código 4: Esquema em JSON do gráfico de “Comparação de remuneração entre setor público e privado”
{
"view": {
"type": "data_series",
"range": [
"media_remuneracao_ajustada"
],
"domain": "flag_publico_privado",
"groupBy": [
{
"label": "Gênero",
"value": "genero"
},
{
"label": "Poderes",
"value": "poderes"
},
{
"label": "Nível de governo",
"value": "nivel_governo"
},
{
"label": "Grau de instrução",
"value": "grau_instrucao"
}
],
"filterBy": [
{
"type": "single",
"variableId": "ano"
}
],
"chartType": "bars",// onde se define o tipo de gráfico.
"numberFormat": {
"style": "currency", // formatando pela moeda local
"currency": "BRL"
},
"defaultValues": {
"filterBy": {
"ano": 2021
}
},
"dataSourceType": "staticValues",
"dimensionVariableId": "variavel",
"dimensionValueVariableId": "categoria"
},
"filterBy": [
"flag_publico_privado"
],
"variables": {
"ano": {
"type": "continuous",
"label": "Ano",
"options": [
2013,
2014,
2015,
2016,
2017,
2018,
2019,
2020,
2021
],
"phrasePrefix": "em"
},
"variavel": {
"type": "categorical"
},
"categoria": {
"type": "categorical"
},
"flag_publico_privado": {
"type": "categorical",
"label": "Tipo de setor"
},
"media_remuneracao_ajustada": {
"type": "continuous",
"label": "Remuneração média",
"expression": "media_remuneracao_ajustada"
}
}
}
- Gráfico de pizza
Abaixo está o esquema utilizado para elaboração do gráfico de pizza do DV chamado de “Municípios com política de priorização para mulheres em cargos de chefia e assessoramento”.
Código 5: Esquema em JSON do gráfico de “Municípios com política de priorização para mulheres em cargos de chefia e assessoramento”
{
"view": {
"type": "pie", // ao invés de data_series, seria pie
"range": [
{
"label": "Municípios ",
"value": "count_all"
}
],
"domain": "existencia_priorizacao_cargo_mulher"
},
"variables": {
"existencia_priorizacao_cargo_mulher": {
"type": "categorical",
"options": [
{
"color": "var(--red)",
"label": "Não",
"value": "Não"
},
{
"color": "var(--green)",
"label": "Sim",
"value": "Sim"
}
],
"variableId": "existencia_priorizacao_cargo_mulher",
"label": "política de priorização de cargos para mulheres em chefia e assessoramento"
}
},
"dataSources": {
"MUNIC_politica_mulheres": "repositoriodedadosgpsp.acoes_afirmativas.MUNIC_politica_mulheres"
}
}
- Mapa de variável contínua
Será apresentado na seção seguinte de tutorial.
- Mapa de variável categórica
Abaixo está o esquema utilizado para elaboração do mapa referente ao DV chamado de “Mapa com perfil do titular do órgão de cultura dos estados brasileiros”.
Código 6: Esquema em JSON do gráfico de “Mapa com perfil do titular do órgão de cultura dos estados brasileiros”
{
"view": {
"type": "br_map_categorical",
"range": [
{
"label": "Perfil do gestor de cultura por cor/raça",
"value": "cor_raca"
},
{
"label": "Perfil do gestor de cultura por gênero",
"value": "genero"
},
{
"label": "Perfil do gestor de cultura por faixa etária",
"value": "faixa_etaria"
},
{
"label": "Perfil do gestor de cultura por escolaridade",
"value": "grau_instrucao"
}
],
"mapType": "states",
"filterBy": [
{
"type": "single",
"variableId": "ano"
}
],
"defaultValues": {
"filterBy": {
"ano": 2021
}
},
"stateIdVariableId": "sigla_uf"
},
"variables": {
"ano": {
"type": "continuous",
"label": "Ano",
"options": [
2018,
2021
],
"variableId": "ano",
"phrasePrefix": "no ano de"
},
"genero": {
"type": "categorical",
"options": [
{
"color": "var(--green)",
"label": "Masculino",
"value": "Masculino"
},
{
"color": "var(--dark-blue)",
"label": "Feminino",
"value": "Feminino"
}
],
"variableId": "genero"
},
"cor_raca": {
"type": "categorical",
"options": [
{
"color": "var(--red)",
"label": "Branca",
"value": "Branca"
},
{
"color": "var(--orange)",
"label": "Parda",
"value": "Parda"
},
{
"color": "var(--green)",
"label": "Preta",
"value": "Preta"
}
],
"variableId": "cor_raca"
},
"sigla_uf": {
"type": "categorical",
"options": [],
"variableId": "sigla_uf"
},
"grau_instrucao": {
"type": "categorical",
"options": [
{
"color": "var(--orange)",
"label": "Até Ensino Médio",
"value": "Até Ensino Médio"
},
{
"color": "var(--green)",
"label": "Até Ensino Superior Completo",
"value": "Até Ensino Superior Completo"
},
{
"color": "var(--red)",
"label": "Até Pós Graduação ou Mestrado",
"value": "Até Pós Graduação ou Mestrado"
},
{
"color": "var(--purple)",
"label": "Até Doutorado",
"value": "Até Doutorado"
}
],
"variableId": "grau_instrucao"
},
"faixa_etaria": {
"type": "categorical",
"options": [
{
"color": "var(--dark-blue)",
"label": "Entre 18-29",
"value": "Entre 18-29"
},
{
"color": "var(--orange)",
"label": "Entre 30-49",
"value": "Entre 30-49"
},
{
"color": "var(--green)",
"label": "Entre 50-64",
"value": "Entre 50-64"
},
{
"color": "var(--red)",
"label": "Acima de 65",
"value": "Acima de 65"
}
],
"variableId": "faixa_etaria"
}
}
}- Tabela
Abaixo está o esquema utilizado para elaboração da tabela referente ao DV chamado de “Legislações de ações afirmativas no serviço público brasileiro”.
Código 7: Esquema em JSON do gráfico de “Legislações de ações afirmativas no serviço público brasileiro”
{
"view": {
"type": "table"
},
"variables": {
"ano": {"variableId":"ano","type":"continuous","label":"Ano"},
"lat": "categorical",
"lng": "categorical",
"sigla_uf": "categorical",
"vigencia": "categorical",
"tipo_cota": "categorical",
"legislacao": "categorical",
"percentual": "categorical",
"abrangencia": "categorical",
"nome_regiao": "categorical",
"nome_municipio": "categorical",
"regulamentacao": "categorical",
"flag_comissionado": "continuous",
"forma_identificacao": "categorical",
"flag_comiss_verificacao": "continuous",
"nomenclatura_legislacao": "categorical"
}
}- Descrição dos campos do esquema
Abaixo serão descritos os campos principais que compõem o esquema e alguns campos específicos a alguns tipos de gráficos.
View: É um parâmetro imprescindível em todos os esquemas, pois é onde se configura e define a especificação dos dados a serem visualizados nos gráficos. Inclui Type, Range, domain, GroupBy, ChartType, DataSourceType.
Type: Esse parâmetro pertence à ‘View’. É uma especificidade que classifica os parâmetros. Pode ser: ‘data_series’ para gráfico em linha de série temporal e gráfico de barras, ‘br_map_categorical’ para mapas categóricos do Brasil, ‘pie’ pra gráficos em pizza e ‘table’ para representação em tabela. Em ‘variables’, temos a classificação da variável como contínua (‘continuous’) ou categórica (‘categorical’). Em ’FilterBy’é possível classificar como filtro único (single) ou múltiplo (multi).
Range: Esse parâmetro pertence à ‘View’. Define quais
variáveis serão exibidas no gráfico e como serão visualizadas. Inclui
“Value” para identificar qual é a variável e “Label” para rotulá-la. A
coluna do gráfico que será o valor principal a ser agregado é inserido
no value com o sufixo de sua agregação: [nome da
coluna]_sum ou [nome da coluna]_count ou [nome
da coluna]_mean.
Domain: É o parâmetro que indica a variável do eixo x, ou seja, o domínio da visualização. Pode-se ter uma representação de dados temporais ou categóricos.
Variables Lista as variáveis da tabela que está sendo requisitada, incluindo informações sobre o tipo de variável (se é contínua ou categórica), a ‘label’ que contém a transposição para o nome que melhor comunique a informação que a variável traz, ’options’ que possui as opções dos valores inclusos na coluna da variável e outras configurações específicas, se for necessário. No gráfico, só aparecerão as variáveis e opções declaradas no esquema neste campo.
ChartType: Define o tipo de gráfico a ser utilizado na
visualização dos dados. Quando o Type é data series ele
deve ser definido nesse parâmetro como bars ou
lines
DataSourceType: Indica o tipo de agregação a ser aplicado no
gráfico. É definido como “aggregation” e sugere que os dados utilizados
para gerar a visualização foram agregados de alguma forma para que sejam
apresentados no gráfico. A forma exata da agregação pode ser soma (sum),
média (mean), contagem (Count). Essa forma de agregação aparece como um
sufixo da variável na especificidade ‘value’, contida na ‘range’. Por
exemplo, no esquema do conjunto de dados
ESTADIC_perfil_gestor_educacao_consolidado.json, a variável
‘quantidade’ contém o número total de determinada informação em cada
linha. Assim, para visualizar a quantidade total, usou-se a soma como
método de agregação, portanto, temos ‘quantidade_sum’.
NumberFormat: Especifica o formato numérico a ser aplicado aos valores apresentados no gráfico (por exemplo, estilo percentual, representado como ‘percent’). Para saber mais possibilidades sobre os formatos é possível consultar a documentação da biblioteca utilizada.
FilterBy: É o parâmetro utilizado para aplicar filtros aos dados exibidos no gráfico. Sempre irá se referir a uma variável já declarada no esquema.
GroupBy: É o parâmetro utilizado para agrupar os dados com base em uma ou mais variáveis, usadas em gráficos que mostram distribuição ou categorização. Sempre irá se referir a uma variável já declarada no esquema.
phrasePrefix: Trata-se de uma frase que antecede um valor a ser exibido na visualização do gráfico. Por exemplo, após a variável ‘ano’, pode-se inserir a frase ‘no ano…’.
stateIdVariableId: É a especificidade presente nos gráficos em mapa. Essa variável contém a identificação da coluna com o código do estado.
municipalityIdVariableId: É a especificidade presente nos gráficos em mapa. Essa variável contém a identificação da coluna com o código do município.
variableId: Encontra-se em ‘variables’. É a especificidade usada para identificar de forma única uma variável nos dados de uma tabela. Desta forma, cada variável deve ter um ‘variableId’ específico que a distingue de outras variáveis.
Color: É usado para especificar a cor associada a uma variável. As cores cadastradas são: light-grey, white, black, green, pale-green, dark-blue, blue, purple, orange, grey, red. Por exemplo, no esquema, pode aparecer de duas formas: var–(green) ou green.
DefaultValues: Encontra-se em ‘view’. Trata-se de um valor padrão, uma variável pré-definida na visualização do gráfico. Por exemplo,
"defaultValues": {
"filterBy": {
"ano": 2021
}Na exemplificação acima, temos um filtro pré-definido na variável ano. Assim, quando alguém abrir esse gráfico, aparecerão os dados do ano de 2021.
Nesta seção será apresentado um passo a passo para criação de um gráfico no RED. Para isso, trabalharemos com o exemplo do DV de vínculos estaduais por tipo de vínculos da ESTADIC.
1º passo: O que eu quero informar?
O primeiro passo é entender o que se quer informar para o usuário do RED. Neste caso, o que queríamos era informar o total de vínculos por tipo para cada Unidade da Federação e também a proporção destes tipos na respectiva UF através de um mapa. A nossa fonte de dados nesse caso foi a ESTADIC e por se tratar de uma base simples, o pré-tratamento foi uma busca simples no datalake da Base dos Dados para validação mas todo o tratamento foi feito em consulta posterior.
Código 8: Query para consulta no datalake da Base dos Dados
SELECT * FROM `basedosdados-dev.br_ibge_estadic.indicadores_quantidade_vinculo`
Após rodar a query direto no GBQ, esse código foi salvo na pasta do drive e no github para registro mas o tratamento completo ficou no script do próximo passo.
2º passo: tratamento da informação:
Nesta etapa, já com a arquitetura em mente, o data view idealizado foi cadastrado na planilha de controle do RED e foi feito um tratamento e subida no GBQ. A seguir, nos códigos escritos em Python, para fins explicativos utiliza-se ‘#’ apenas para comentar o código, sem alterar o script:
Código 9: Script para tratamento e subida no GBQ do mapa de quantidade de vínculos a ESTADIC
import pandas as pd
import time
import numpy as np
import os
import pandas_gbq
from google.cloud import bigquery
import basedosdados as bd
query = "SELECT ano, tipo_vinculo, sigla_uf, sum(quantidade_vinculo) as quantidade_vinculos FROM `basedosdados.br_ibge_estadic.indicadores_quantidade_vinculo` where ano =2021 group by 1, 2, 3"
client = bigquery.Client() # chamo o cliente do GBQ
df = pandas_gbq.read_gbq(query, project_id='repositoriodedadosgpsp') # requisição a partir da consulta
y=df.pivot_table(index={'sigla_uf'},values='quantidade_vinculos', aggfunc=np.sum)
y = pd.DataFrame(y)
total = y.reset_index()
total=total.rename(columns={'quantidade_vinculos':'total_estado'})
df1 = df.merge(total, right_on='sigla_uf', left_on='sigla_uf')
## Subindo para GBQ
dataset_ref = client.dataset ('perfil_remuneracao') # aqui eu escolho o dataset.
schema=[bigquery.SchemaField('ano','INTEGER',description='Ano de referencia da informacao'),
bigquery.SchemaField('tipo_vinculo','STRING',description='Tipo de vinculo.'),
bigquery.SchemaField('sigla_uf','STRING',description='Sigla da Unidade da Federação.'),
bigquery.SchemaField('quantidade_vinculos','INTEGER',description='Quantidade de vinculos'),
bigquery.SchemaField('total_estado','INTEGER',description='Total de vínculos daquela UF')
]
table_ref = dataset_ref.table('ESTADIC_quantidade_vinculos_mapa') # nome da tabela no padrão FONTE_algo_intuitivo_dado
job_config = bigquery.LoadJobConfig(schema=schema)
job = client.load_table_from_dataframe(df1, table_ref, job_config=job_config)
job.result()
3º passo: Cadastro da tabela no painel de
administrador:
Nesta fase o que será usado na parte de Big Query Full Table Id é o
caminho da tabela no GBQ, para esse caso é o
repositoriodedadosgpsp.perfil_remuneracao.ESTADIC_quantidade_vinculos_mapa.
Cadastra-se todas as informações na página de Data Views e o esquema
para esse mapa em específico foi o :
Código 9: Esquema de criação do mapa da ESTADIC
{
"view": {
"type": "br_map_continuous",
"range": [
{
"label": "Quantidade de vinculos",
"value": "quantidade_vinculos"
},
{
"label": "Proporção de vínculos que são",
"value": "proporcao_tipo",
"numberFormat": {
"style": "percent",
"minimumFractionDigits": 2,
"maximumFractionDigits": 2
}}
],
"mapType": "states",
"filterBy": [
{
"type": "single",
"variableId": "tipo_vinculo"
}
],
"defaultValues": {
"filterBy": {
"tipo_vinculo": "Estatutários"
}
},
"stateIdVariableId": "sigla_uf"
},
"variables": {
"ano": {
"type": "continuous",
"categories": [
2021
]
},
"sigla_uf": {
"type": "categorical",
"categories": [],
"variableId": "sigla_uf"
},
"tipo_vinculo": {
"type": "categorical",
"label": "Tipo de vínculo",
"options": [
"Estatutários",
"Celetistas",
"Somente comissionados",
"Estagiários",
"Sem vínculo permanente"
],
"variableId": "tipo_vinculo",
"phrasePrefix": " "
},
"total_estado": {
"type": "continuous"
},
"quantidade_vinculos": {
"type": "continuous"
}
},
"valueExpressions": {
"proporcao_tipo": {
"label": "Proporção por tipo de vínculo",
"value": "sum(quantidade_vinculos) / sum(total_estado) "
},
"quantidade_vinculos": "sum(quantidade_vinculos)"
}
}O resultado do gráfico será como segue abaixo:
- Detalhamento de tecnologias e metodologias
6.1 Tecnologias utilizadas para desenvolvimento das interfaces de usuário (UI - User Interface)
Tabela 2: Tabela com as tecnologias utilizadas no UI
| Tecnologia | Detalhamento |
|---|---|
|
HTML
(5), CSS (3) e JavaScript (ES6 -
ES14) https://www.w3.org/ https://ecma-international.org/ |
Função:
Linguagens de programação fundacionais utilizadas para o desenvolvimento
das interfaces de usuário (front-end) Licenciamento: Padrões W3C e ECMA com distintas implementações. Ampla disponibilidade de implementações licenciadas como software livre. São as linguagens de programação que estão na fundação das tecnologias web. Sobre estas linguagens, utilizamos diversas bibliotecas e frameworks que aceleram e possibilitam o desenvolvimento de interfaces interativas. Qualquer navegador com suporte a estas tecnologias será compatível com a plataforma. Em consulta na plataforma https://caniuse.com/, foi possível identificar que estamos com suporte a todos os navegadores lançados desde 2015 (https://caniuse.com/?search=es6) |
|
React.js https://react.dev/ |
Função:
framework de front-end Licenciamento: MIT License (software livre) Framework open-source para desenvolvimento de interfaces de usuário interativas (front-end) com foco em componentização, performance e escalabilidade. É um framework criado pelo Meta, utilizado em diversos produtos de grande reconhecimento, um dos padrões da indústria. |
|
Next.js https://nextjs.org/ |
Função:
framework de front-end / integração / renderização no
servidor Licenciamento: MIT License (software livre) Framework open-source para desenvolvimento de sites com suporte à renderização no servidor (Server Side Rendering - SSR). A renderização no servidor é uma tecnologia que possibilita que aplicações de interfaces interativas baseadas no uso de JavaScript (JS) possam ser também pré-renderizadas no servidor de forma a ter alta performance para indexação em sistemas de busca (Search Engine Optimization - SEO). |
|
D3.js
(Data-Driven Documents) https://d3js.org/ |
Função:
Biblioteca de utilidades para preparo de dados para visualização e
visualização de dados Licenciamento: ISC License (software livre) Biblioteca referência na criação de interfaces de visualização de dados interativas. Utilizada para criar diversos tipos de visualização (dentre centenas de tipos, nós, redes, linhas, barras, etc.). A biblioteca simplifica e define formas de manipulação de elementos de SVG e HTML com vista à alta performance e orientação a dados. |
|
Recharts.js https://recharts.org/ |
Função:
Componente de front-end para renderização de gráficos
interativos Licenciamento: MIT License (software livre) Componente de front-end desenvolvido para React.js que auxilia na renderização de gráficos interativos. Possui componentes pré-formatados para renderização de gráficos de barras, linhas, áreas, setores, etc. |
|
React
Force
Graph https://github.com/vasturiano/react-force-graph |
Função:
Componente de front-end de renderização de gráficos de
força Licenciamento: MIT License (software livre) Componente que integra a biblioteca D3.js com o framework React.js para renderização de gráficos de força (gráficos que apresentam nós e redes de forma a aproximar nós relacionados e afastar nós distantes). |
6.2 Tecnologias utilizadas para desenvolvimento do sistema de dados (APIs) e integrações de back-end
Tabela 3: Tabela com as tecnologias utilizadas no desenvolvimento do sistema de dados (APIs) e integrações de back-end
| Tecnologia | Detalhamento |
|---|---|
|
Node.js,
Node Package Manager (NPM) e
Yarn https://nodejs.org/ |
Função:
Linguagem e ecossistema base de backend Licenciamento: MIT License (software livre) Node.js é o ecossistema de backend que possibilita o uso da linguagem JavaScript (JS) em ambiente do servidor (server-side JS). Foi criado originalmente em 2009 através de uma integração do motor de JavaScript V8 desenvolvido pelo time do Google Chrome. |
|
Keystone.js https://keystonejs.com/ |
Função:
Framework de desenvolvimento de backend Licenciamento: MIT License (software livre) Keystone.js é um framework de desenvolvimento de backend que define uma estrutura para implementação de sistemas de dados de forma agilizada. O Keystone.js possibilita, dentre outras possibilidades, a definição de modelos de dados no banco de dados e acessíveis via uma API GraphQL, a definição de modelos de autenticação e autorização, a administração de dados através de uma interface de gestão de conteúdo (Content Management System - CMS) |
|
GraphQL https://graphql.org/ |
Função:
Linguagem de consulta de API. Licenciamento: Especificação aberta com implementações em diversas linguagens. É utilizada a versão voltada para JavaScript (JS): GraphQL.js - <span style=“font-weight:400;font-style:normal;text-decoration:underline;color:#15C;background-color:transparent;font-family:Roboto Condensed”;>MIT License (software livre) GraphQL é uma linguagem de consulta voltada para exposição de métodos de busca (query) e mutação (mutation) de dados. A linguagem favorece a exposição de sistemas de dados complexos, possibilitando que aplicações de front-end possam buscar dados de forma altamente flexível conforme suas necessidades. |
|
PostgreSQL https://www.postgresql.org/ |
Função:
Banco de dados Licenciamento: PostgreSQL License - similar à BSD ou MIT PostgreSQL é um software de banco de dados de software livre amplamente utilizado. É um banco de dados que implementa SQL (Structured Query Language), com suporte à todas as características de bancos de dados relacionais, dentre outras: normalização de dados, transações ACID, etc. |
6.3 Tecnologias e serviços comerciais utilizados na hospedagem e armazenagem de dados
Tabela 4: Tabela com as tecnologias e serviços comerciais utilizados na hospedagem e armazenagem de dados
| Tecnologia | Detalhamento |
|---|---|
|
Heroku
Dynos https://www.herok;font-family:Roboto Condensedu.com/dynos |
Função:
Operadora de infraestrutura de servidores Licenciamento: Serviço comercial. Prestadora de serviço de infraestrutura em nuvem. Tecnologia compatível com Linux. A Heroku é uma plataforma PaaS (Platform as a Service) que integra o grupo Salesforce. A plataforma possibilita a implantação (deployment) ágil de aplicações em diversos tipos de ecossistemas. Os Dynos são a solução da Heroku para hospedar servidores de alta escalabilidade de forma flexível. Conforme a demanda pelo serviço aumenta, é possível escalar horizontalmente (aumentar a quantidade de servidores) para atender a demanda. |
|
Heroku
PostgreSQL https://www.heroku.com/postgres |
Função:
Operadora de infraestrutura de banco de dados Licenciamento: Serviço comercial. Prestadora de serviço de infraestrutura em nuvem. A Heroku é uma plataforma PaaS (Platform as a Service) que integra o grupo Salesforce. A plataforma possibilita a implantação (deployment) ágil de aplicações em diversos tipos de ecossistemas. O serviço de PostgreSQL oferece bancos de dados PostgreSQL gerenciados e de alta escalabilidade. |
|
Amazon
Web Services (AWS) S3 - Simple Storage
Service https://aws.amazon.com/pt/s3/ |
Função:
Operadora de infraestrutura de armazenagem de arquivos Licenciamento: Serviço comercial. Prestadora de serviço de infraestrutura em nuvem. A Amazon Web Services é o serviço de infraestrutura de nuvem oferecido pela Amazon. A AWS é uma solução de nuvem muito completa, referência no mercado. O serviço S3 é o serviço de armazenagem de arquivos com diversas opções de configuração de armazenagem. |
|
Google
GCP BigQuery https://cloud.google.com/bigquery |
Função:
Plataforma de data
warehouse
da Google Cloud Platform (GCP) utilizada para armazenar e consultar
dados Licenciamento: Serviço comercial. Prestadora de serviço de infraestrutura em nuvem O Google Cloud Platform é o serviço de infraestrutura de nuvem oferecido pela Google. O serviço GCP BigQuery é um serviço voltado para armazenagem, análise e consulta de dados de grande volume (big data) através de interfaces utilizando uma linguagem próxima ao SQL. A ferramenta permite escalar o processamento e consulta de dados. |
O objetivo desta documentação foi a apresentação das tecnologias que envolvem o RED e a transmissão das informações que possibilitem que outros profissionais cadastrem novos dados e mantenham a plataforma viva.
Para melhor gerenciamento da plataforma República em Dados, é recomendado que o profissional que a gerencie tenha conhecimentos em SQL, python ou R, GBQ e markdown .