dg:Workflow: mudanças entre as edições

Edição atual tal como às 00h37min de 14 de dezembro de 2023

Documentação integrante do
projeto Digital-guard

Sobre
Convenções
Gits

Países: AR, BR, CO, CM, CL, PE, SR, VE, UY.

Carlos, Luiz e Igor favor refazer ou revisar esta seção.

Fluxo de trabalho do Igor e do Carlos

Resumo geral e opções

O fluxo de trabalho (workflow) completo envolve diversas etapas, que no futuro poderão vir automatizadas pelo Airflow, mas por hora precisam ser realizadas por uma pessoa previamente treinada no uso do console Linux.

No dia-a-dia da Digita-guard são 3 três serviços relativamente independentes, que não precisam ser realizados simultaneamente:

Pré-Ingestão: são tarefas de preparo dos metadados e dos arquivos de download, durante ou logo após o recebimento. Seu principal resultado é o arquivo make_conf.yaml.
Ingestão: filtra e leva os dados brutos (externos da doação) para dentro do banco SQL, viabilizando todas as demais ações. Seu principal resultado são os dados filtrados, no banco.
Publicação: é a ação mais importante, entrega o produto. Os dados filtrados são preservados no git "preservCutGeo" do país (podendo ser reusados posteriormente pelo banco de dados).

Demais ações são auxiliares, para manutenção da base, do sandbox ou integração com outros recursos, como o site ESRI de publicação amigável.

Pré-Ingestão

Atualização do optim

Se donor.csv (em qualquer jurisdição) ou donatedPack.csv forem alterados ou um novo make_conf.yaml for criado, é necessário atualizar as tabelas do schema optim:

cd /var/gits/_dg/preserv/src
make load_optim_csv pg_datalake=dl05s_main

Atualização de sha256

Se o sha256 de arquivos for alterado em um make_conf existente:

incrementar pkversion;
inserir nova entrada no arquivo donatePack.csv;
Atualizar tabelas de optim.

Ver preserv-BR/issues/68

Gerar sha256

Ver dg:Guia_do_sha256.

Preservação digital

Ver dg:Convenções/Armazenamento_de_dados.

Estrutura do make_conf

Exemplo fictício de make_conf. Reparar nas chaves: comments, comment, test_evidence, standardized_fields, other_fields, other_files e to-do utilizadas na geração automatizada de README.md. Informações extras ou que não se encaixam nas referidas chaves podem ser incluidas no arquivo attachment.md, anexado ao final do README.md na seção Anexo. Templates em ptbr e es.

pack_id: 81.1
pkversion: 001
schemaId_input: 
schemaId_template: 
codec:descr_encode: srid=31983

files:
  -
    p:    1
    file: d9cddc63f7782d250fc80f0572b9fb884ee7ec1911e19deea4381a4ad5d0a172.zip
    name: Bairros
    comments: Comentários sobre o arquivo, se houver.
    size: 1234

layers:

  geoaddress:
    subtype: ext
    method: shp2sql
    file: 1
    sql_select: ['gid', 'numnovo as hnum', 'cod_log', 'geom']
    orig_filename: pg_renumeracoes
    comments: Comentários referente ao layer, se houver.
    test_evidence: endereço da imagem de evidencia do layer.
    
    # dados relevantes, padronizados
    standardized_fields:
     -
      name: nome do campo ou combinação de campos
      standard: 'nome padronizado, por exemplo: hnum'
      comment: comentários sobre o campo, se houver.

    # dados relevantes, NÃO padronizados, se houver
    other_fields:
     -
      name: nome do campo ou combinação de campos
      comment: comentários sobre o campo, se houver.

comments: Comentários gerais sobre os dados, sobre o pacote, etc, se houver.

test_evidence: endereço da imagem de evidencia de todos os dados. 

# outros arquivos que podem ser úteis
other_files:
  -
    p: 2
    file: pg_div_municipio.zip
    name: pg_div_municipio
    format: shp
    comment: Arquivo com a divisa territorial de guarulhos e vizinhos.

# Lista de tarefas
to-do: 
  - Tarefa 1.

Arquivos não compactados

Em casos que o arquivo original doado não for compactado^[1]:

compactar (em zip, preferencialmente), informar o hash do arquivo compactado ao doador (respondendo email);
preservar o arquivo compactado;
usar hash do arquivo compactado no make_conf.

Ingestão

Devido à hardcoding, qualquer base ingest depende da dl05s_main.
Vamos usar apenas a base ingest1, e não adulterar mais nada no servidor.
É possível trocar ingest1 por outra com os devidos cuidados e parametrizações.

Preparo do ambiente e da base

cd /var/gits/_a4a/pg_pubLib-v1
git pull

cd /var/gits/_dg/preserv/src
git pull

make fix_permissions # vai solicitar sudor

make # vai listar as opções

make ini_ingest pg_db=ingest1 # cria base ingest1

Preparo do processo de ingestão

make fix_permissions # vai solicitar sudor

cd /var/gits/_dg/preserv-BR/src
git pull

make # vai listar as opções

make all # copia makefile inicial em todos pacotes de dados

cd /var/gits/_dg/preserv-BR/data/

ls  # vamos seguir a ordem alfabética

Exemplo do pk42.01

Verificando a situação no filesystem:

make fix_permissions # vai solicitar sudor

cd /var/gits/_dg/preserv-BR/data/
ls AC/RioBranco/_pk0042.01/
grep "^42" donor.csv
grep ",42,1" donatedPack.csv
cd  AC/RioBranco/_pk0042.01/
more sha256sum.txt
grep file  make_conf.yaml
# ... até aqui foi só conferir se batem IDs, hashes e títulos

more make_conf.yaml # detectamos problemas por ser antigo: falta licença, faltam file sizes, etc.

make me # responder senhas ENTERs etc. use pg_db=ingestXX para uma ingest diferente de commomFirst.yaml. Idem para qualquer target em preserv-BR

make insert_size # inserir tamanho dos arquivos se necessário

#make insert_license # inserir licença. Cuidado, experimental!

make all_layers # para ingerir todos os layers ou make <nome_do_layer> para ingerir um layer especifico.

make all_joins # para executar todos os joins ou se existir a necessidade.

Exemplo do pk0004.01 (OpenStreetMap)

make fix_permissions # vai solicitar sudor

cd /var/gits/_dg/preserv-BR/data/_pk0004.01
ls _pk0004.01/
grep "^4," donor.csv
grep ",4,1" donatedPack.csv
cd  _pk0004.01/
more sha256sum.txt
grep file  make_conf.yaml
# ... até aqui foi só conferir se batem IDs, hashes e títulos

more make_conf.yaml # detectamos problemas por ser antigo: falta licença, faltam file sizes, etc.

make me # para a ingest indicada em commomFirst.yaml ou make me pg_db=ingestXX para uma ingest diferente.

# caso falte file sizes:
make wget_files orig=/tmp/pg_io/tmpfolder
make insert_size orig=/tmp/pg_io/tmpfolder
rm -rf /tmp/pg_io/tmpfolder

make openstreetmap # executar antes da ingestão, apenas uma vez.
# .. responder senhas ENTERs etc.

make all_layers

Publicação

Gerar os arquivos

Para gerar os arquivos que serão publicados no respectivo preservCutGeo do país:

cd /var/gits/_dg/preserv-<caminho_do_pacote_de_dados>
make publicating_geojsons_<nome_do_layer>
# exemplo: make publicating_geojsons_via` gera os arquivos em `/var/gits/_dg/preservCutGeo-BR2021/data/AC/RioBranco/_pk0042.01/via/`

ou, para gerar todos os arquivos (verificar se todos foram gerados):

cd /var/gits/_dg/preserv-<caminho_do_pacote_de_dados>
make all_publications

make target audit-geojsons_<nome do layer>
# exibe informações sobre os arquivos gerados.

Atualmente, apenas em casos excepcionais é necessário recorrer a busca de parâmetros de distribuição.

Subir para o repositório

Concluída a geração dos arquivos publicáveis, fazer o pull dos arquivos gerados na branch main do no respectivo preservCutGeo do país:

cd /var/gits/_dg/<repositorio CutGeo>
git pull

Copiar para datalake

Para copiar o conteúdo da tabela ingest.donated_packcomponent para optim.donated_PackComponent_not_approved em DL05s_main:

cd /var/gits/_dg/preserv/src
make to_donated_packcomponent pg_db=<nome_base_ingest> pg_datalake=dl05s_main

Aprovação

A aprovação se dá pela avaliação dos arquivos e movendo os dados de optim.donated_PackComponent_not_approved para optim.donated_PackComponent em DL05s_main:

# obter a variavel id
psql postgres://postgres@localhost/dl05s_main <<< "SELECT * FROM optim.donated_PackComponent_not_approved;"

cd /var/gits/_dg/preserv/src
make approved_donated_packcomponent id=ZZ pg_datalake=dl05s_main

Comando para gerar uma lista de comandos, escolher os que precisar por meio do id:

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT packvers_id, 'make approved_donated_packcomponent pg_datalake=dl05s_main id=' || id FROM optim.donated_packcomponent_not_approved ORDER BY 1;"

Escolhido o que será aprovado executar, por exemplo:

cd /var/gits/_dg/preserv/src
make approved_donated_packcomponent pg_datalake=dl05s_main id=2

Nesse momento, os novos dados fazem parte das estatísticas disponibilizadas em API. Também, listas disponibilizadas no site addressforall e em documentações podem ser atualizadas.

Reprodutibilidade

Como gerar

cd /var/gits/_dg/preserv-<caminho_do_pacote_de_dados>
make me_reproducibility # gerar/atualizar script reproducibility.sh

Filtrados

São os arquivos utilizados para publicação no provedor de visualizaçao de dados.

Como gerar

Para gerar Shapefile ou CSV dos dados ingeridos:

cd /var/gits/_dg/preserv-<caminho_do_pacote_de_dados>
make all_filtered

# exemplo de output:
/var/gits/_dg/preserv-BR/data/RS/NovoHamburgo/_pk0063.01
/tmp /var/gits/_dg/preserv-BR/data/RS/NovoHamburgo/_pk0063.01
Generating ziped shapefile...
Initializing... 
Done (postgis major version: 3).
Output shape: Polygon
Dumping: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
...
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX [130936 rows].
  adding: a4a_br_rs_novohamburgo_building_7600006301101/ (stored 0%)
  adding: a4a_br_rs_novohamburgo_building_7600006301101/a4a_br_rs_novohamburgo_building_7600006301101.shx (deflated 58%)
  adding: a4a_br_rs_novohamburgo_building_7600006301101/a4a_br_rs_novohamburgo_building_7600006301101.dbf (deflated 87%)
  adding: a4a_br_rs_novohamburgo_building_7600006301101/a4a_br_rs_novohamburgo_building_7600006301101.prj (deflated 40%)
  adding: a4a_br_rs_novohamburgo_building_7600006301101/a4a_br_rs_novohamburgo_building_7600006301101.cpg (stored 0%)
  adding: a4a_br_rs_novohamburgo_building_7600006301101/a4a_br_rs_novohamburgo_building_7600006301101.shp (deflated 59%)
Upload and get uri cloud...
Insert infos in optim.donated_PackComponent_cloudControl...
File available at: http://dl.digital-guard.org/out/a4a_br_rs_novohamburgo_building_7600006301101.zip
File available at: https://addressforall-my.sharepoint.com/personal/operacao_addressforall_org/_layouts/15/download.aspx?share=EaJb5nvzNblLthafTgulxToBYNG-bvSbv3Q7oPNiUGwYnw
File available at: /tmp/a4a_br_rs_novohamburgo_building_7600006301101.zip
End.

Visualização

Ver a seção dg:Workflow#Visualização_de_filtrados.

Gerar README

Como gerar

Para gerar README.md:

cd /var/gits/_dg/preserv-BR/src
make all
cd /var/gits/_dg/preserv-BR/data/AC/RioBranco/_pk0042.01
make readme pg_db=ingest99

Exemplos

Atualizar Listas e site

Downloads por jurisdição

MediaWiki

Para atualizar a página dg:Listagem_dos_downloads_por_jurisdição gerar a lista em formato mediawiki com o comando

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.generate_list('/tmp/pg_io/list_jurisd_without_filtered_mediawiki.txt','/var/gits/_dg/preserv/src/list_jurisd_without_filtered_mediawiki.mustache');"

e copiar e colar o conteúdo do arquivo /tmp/pg_io/list_jurisd_without_filtered_mediawiki.txt na referida página.

Notar que não é exibido os arquivos filtrados na lista.

Caso seja necessário exibir os filtrados usar o comando

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.generate_list('/tmp/pg_io/list_jurisd_mediawiki.txt','/var/gits/_dg/preserv/src/list_jurisd_mediawiki.mustache');"

e então utilizar o conteúdo do arquivo /tmp/pg_io/list_jurisd_mediawiki.txt.

Consulte README.md para entender como gerar o site.

Markdown

Para atualizar a seção http://addressforall.org/en/downloads atualizar o arquivo https://github.com/AddressForAll/site-v2/blob/main/content/list_downloads.md com o conteúdo do arquivo gerado pelo comando a seguir no formato markdown

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.generate_list('/tmp/pg_io/list_jurisd_with_filtered_markdown.txt','/var/gits/_dg/preserv/src/list_jurisd.mustache');"

Notar que são exibidos os arquivos filtrados na lista.

Caso seja necessário não exibir os filtrados usar o comando

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.generate_list('/tmp/pg_io/list_jurisd_with_filtered_markdown.txt','/var/gits/_dg/preserv/src/list_jurisd_without_filtered.mustache');"

Downloads por hash

MediaWiki

Para atualizar a página dg:Listagem_dos_downloads_por_hash gerar a lista em formato mediawiki com o comando

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.generate_list_hash('/tmp/pg_io/list_hash_mediawiki.txt','/var/gits/_dg/preserv/src/list_hash_wiki.mustache');"

e copiar e colocar o conteúdo na referida página.

Markdown

Se for necessário gerar a lista em formato Markdown, usar o comando

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.generate_list_hash('/tmp/pg_io/list_hash_markdown.txt');"

Páginas viz

Para atualizar o conteúdo de http://addressforall.org/viz selecionar o comando referente ao pacote de dados desejado da lista de comandos gerada por

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT 'make generate_pages pg_datalake=dl05s_main folder=/tmp/pg_io/genpages isolabel=' || isolabel_ext || ' pk=' || pack_number FROM optim.vw03publication ;"

Por exemplo, para gerar em /tmp/pg_io/genpages as páginas referentes ao pk=_pk0063.01 do isolabel=BR-RS-NovoHamburgo utilizando os dados presentes em optim.donated_PackComponent do pg_datalake=dl05s_main executar:

cd /var/gits/_dg/preserv/src
make generate_pages pg_datalake=dl05s_main folder=/tmp/pg_io/genpages isolabel=BR-RS-NovoHamburgo pk=_pk0063.01

Notar que é gerado um index.html atualizado, contendo lista não ordenada com os hiperlinks para todos pacotes publicados.

Depois de gerar as páginas, movê-las para /var/www/addressforall.org/teste2:

mv /tmp/pg_io/genpages/*.html /var/www/addressforall.org/viz
rm -rf /tmp/pg_io/genpages

Por fim, para atualizar a seção http://addressforall.org/en/visualization atualizar o arquivo https://github.com/AddressForAll/site-v2/blob/main/content/list_visualization.md com o conteúdo do arquivo /tmp/pg_io/index_teste2.md gerado pelo comando a seguir, já no formato markdown (conteúdo equivalente ao index.html gerado anteriormente)

psql postgres://postgres@localhost/dl05s_main -qtAX -c "SELECT optim.publicating_index_pagemd('/tmp/pg_io/index_teste2.md','/var/gits/_dg/preservDataViz/src/preservCutGeo/index_page_markdown.mustache');"

Consulte README.md para entender como gerar o site.

Clean sandbox

O processo de ingestão utiliza subpastas no caminho informado em sandbox, cujo valor default é informado no commomFirst.yaml. Antes na execução da ingestão de cada layer, o target makedirs cria ou limpa a subpasta utilizada pelo layer. Após a execução, o target clean-sandbox remove a subpasta, evitando que arquivos não mais necessários permanecem no sistema de arquivos.

cd /var/gits/_dg/preserv-<caminho_do_pacote_de_dados>
make clean_sandbox

Visualização de filtrados

Os dados gerados em dg:Workflow#Filtrados são publicados em provedor externo para visualização.

Publicar layers

Descrever aqui o processo de publicação no provedor externo para visualização de camadas de dados.

Atualizar redirecionador

Após publicar no provedor externo, ver a4a:Convenções/Visualização_de_dados para atualizar o redirecionador.

Diagrama

https://lucid.app/lucidchart/03536d69-dd73-4f38-92ec-4d32542b29c0/edit?invitationId=inv_9b03ed68-54ce-4d0f-ad77-da1eff87ed43&page=0_0#

Workflow da DG.

Outros

Inserir size no make_conf

Para inserir size em files de um make_conf a qualquer tempo:

cd /var/gits/_dg/preserv-BR/src
make all
cd /var/gits/_dg/preserv-BR/data/AC/RioBranco/_pk0042.01
make me
make wget_files orig=/tmp/pg_io/tmpfolder
make insert_size orig=/tmp/pg_io/tmpfolder
rm -rf /tmp/pg_io/tmpfolder

Inserir Licenças no make_conf

Executar o target make insert_license utiliza os dados de digital-guard/licenses para gerar no respectivo make_conf.yaml o seguinte, por exemplo:

license_evidences:
    definition: [ODbL-1.0, odbl, http://www.opendefinition.org/licenses/odc-odbl]

onde definition: equivale a [name, family, url] conforme discutido em https://github.com/digital-guard/preserv/issues/32

Manualmente, inserir file e uri_evidency, conforme discutido em https://github.com/digital-guard/preserv/issues/19:

    file: f0cbf591bda09880dc27cdbfcf4ee45189eb1e2c3742800c066f0b5576d81744.zip
    uri_evidency: http://web.archive.org/web/20211012105347/https://www.openstreetmap.org/copyright

onde file indica o sha256 do arquivo compactado contendo as evidencias e uri_evidency indica o sha256.eml ou archive.org/url como discutido aqui https://github.com/digital-guard/preserv/issues/32#issuecomment-998347112.

Resultando em:

license_evidences:
    definition: [ODbL-1.0, odbl, http://www.opendefinition.org/licenses/odc-odbl]
    file: f0cbf591bda09880dc27cdbfcf4ee45189eb1e2c3742800c066f0b5576d81744.zip
    uri_evidency: http://web.archive.org/web/20211012105347/https://www.openstreetmap.org/copyright

Exemplo utilizado em https://github.com/digital-guard/preserv-CO/blob/main/data/_pk0004.01/make_conf.yaml

No rule to make target

Ao executar make layer ou make all_layers, caso encontre um erro do tipo

make: *** No rule to make target '/var/www/dl.digital-guard.org/bae2054448855305db0fc855d2852cd5a7b369481cc03aeb809a0c3c162a2c04.zip', needed by 'parcel'.  Stop.

o arquivo especificado não está no diretório default /var/www/dl.digital-guard.org, informado na chave orig de uma jurisdição, por exemplo, em commomFirst.yaml. Significando que o arquivo está armazenado em outro lugar. Isso está indicado na tabela de-para.

Nesse caso usar:

wget -P /diretorio/para/arquivo/baixado http://dl.digital-guard.org/bae2054448855305db0fc855d2852cd5a7b369481cc03aeb809a0c3c162a2c04.zip

make me pg_db=ingestXX

make parcel orig=/diretorio/para/arquivo/baixado pg_db=ingestXX

Se o download for realizado em /var/www/dl.digital-guard.org utilizar apenas

make parcel pg_db=ingestXX

uma vez que o valor default de orig é /var/www/dl.digital-guard.org.

Observação: atualmente, common002_layerHeader.mustache interage com o usuário solicitando a confirmação de download de dl.digital-guard.org ou o fornecimento do valor correto de orig. Caso o download seja realizado, o arquivo estará localizado na respectiva sandbox do layer. Notar que se nointeraction=y não haverá interação com o usuário e o download será feito.

make com nointeraction

Para rodar um target sem serem solicitadas confirmações do usuário, utilizar nointeraction=y.

Por exemplo, make block nointeraction=y faz a ingestão dos dados sem solicitar confirmações do usuário.^[2]

Essa variável só produz efeito em target layer, publicating_geojsons_layer ou me. Para os demais, não.

Workflow da edição de planilhas

Os arquivos CSV do Github infelizmente não são amigavelmente editáveis. Algumas planilhas todavia são ainda dependentes da interface humana nas primeiras etapas do workflow do trabalho, ao dar entrada em um novo donor ou donatedPack. Este é o passo-a-passo a ser seguido:

Editar a planilha colaborativa amigável;
Baixar e normalizar com make getEdits ou os comandos curl do target (ver exemplo)
fazer git diff -wb para conferir.
se tudo ok fazer git pull, git add, commit e push.

Exemplo

cd preserv-BR/data/

curl "https://docs.google.com/spreadsheets/d/1-FQjjhHjJnAOxSWYEdFU_RePxAJDsJCnLviOyDo3QMM/gviz/tq?tqx=out:csv&gid=815577163" \
   | csvformat > donor.csv
git diff -wb donor.csv

curl "https://docs.google.com/spreadsheets/d/1-FQjjhHjJnAOxSWYEdFU_RePxAJDsJCnLviOyDo3QMM/gviz/tq?tqx=out:csv&gid=42455849" \
  | csvformat > donatedPack.csv
git diff -wb donatedPack.csv

A solução CSVkit requer instalar, sudo pip install csvkit, que instala também o comando csvformat.

PS1: conforme discutido API do Gogle está baixando com um monte de aspas, diferente do download direto da interface. Uma solução seria baixar manualmente... O melhor é normalizar. No futuro o comando frictionless talvez incorpore a normalização. Sugiro incluir normalização UTF8 que usamos no PostgreSQL.

PS2: o google/spreadsheets também oferece opção de sql_query na API, o que permite descartar os campos de cache da planilha donatedPack... ver aqui.

Referências

↑ https://github.com/digital-guard/preserv-BR/issues/149#issuecomment-1810758833
↑ Layer com method que utiliza o ogr2ogr via docker, ou target me, podem solicitar a senha do usuário.

[1] ttps://github.com/digital-guard/preserv-BR/issues/149#issuecomment-1810758833

[2] Layer com method que utiliza o ogr2ogr via docker, ou target me, podem solicitar a senha do usuário.

[1]

[2]