Pular para o conteúdo

Empacotar Registros

Use Empacotar registros para reunir os dados do projeto junto com seus metadados e mídias para publicação, arquivamento ou análise reprodutível. Antes de gravar qualquer coisa, Conteúdo do pacote exibe cada arquivo, contagem de registros, colunas e avisos.

FormatoEscolha quandoContémO NAHPU importa
Darwin Core Archive (.dwca.zip)Um museu ou portal de biodiversidade (como o GBIF) solicita DwC-AEspécimes em uma tabela principal plana, com partes, medidas e mídias em tabelas de extensãoNão
Darwin Core Data Package (.dwc-dp.tar.gz)O destinatário aceita o padrão relacional mais recente do Darwin CoreEspécimes, eventos, identificações, partes e pessoas em tabelas Darwin Core vinculadasNão
NAHPU Data Package (.nahpu-dp.tar.gz)Você precisa de tudo para análise em R/Python, arquivamento de longo prazo ou cópia completaO projeto completo, todas as tabelas populadas do NAHPU, configurações do usuário e arquivosSim, via Importar projeto ou Mesclar projeto

Pacotes Darwin Core incluem apenas valores com termo exato registrado em Darwin Core, Dublin Core ou Audubon Core. Escolha NAHPU Data Package quando nada puder ser perdido, incluindo campos personalizados. Ele pode ser lido por qualquer ferramenta Frictionless; veja o Tutorial 3.

  1. Abra o menu do projeto e selecione Empacotar registros.
  2. Escolha o formato do pacote B.
  3. Escolha o formato do arquivo C quando o pacote oferecer mais de um contêiner:
    • TAR.GZ é o padrão para Data Packages.
    • ZIP está disponível para ferramentas e sistemas que preferem arquivos ZIP padrão.
    • Darwin Core Archive sempre usa ZIP.
  4. Para pacotes Darwin Core, escolha Todos os táxons A ou Táxons selecionados. Selecionar Mamíferos também inclui morcegos.
  5. Informe o nome do arquivo D (opcionalmente ative Acrescentar data) e escolha a pasta de destino no desktop.
  6. Revise Conteúdo do pacote E (na aba de conteúdo no celular). Expanda qualquer recurso CSV F para inspecionar suas colunas.
  7. Revise eventuais avisos, como mídias ausentes ou o aviso de compatibilidade ZIP do DwC-DP.
  8. Selecione Criar pacote G. É possível cancelar durante a criação. Ao finalizar, compartilhe, abra a pasta, salve uma cópia ou escolha Empacotar outro.
ContêinerExtensões típicasNotas
TAR.GZ.dwc-dp.tar.gz, .nahpu-dp.tar.gzPadrão para Data Packages e opção recomendada pela especificação DwC-DP. Após extrair, datapackage.json e metadados ficam na raiz.
ZIP.dwca.zip, .dwc-dp.zip, .nahpu-dp.zipObrigatório para Darwin Core Archive; opção normal para NAHPU Data Package; opção de compatibilidade para DwC-DP (exibe aviso pois o guia DwC-DP prefere gzip).

As seções a seguir descrevem os arquivos gerados por cada pacote e como o NAHPU mapeia os registros. Use-as quando um destinatário perguntar sobre a estrutura ou ao processar o pacote em scripts.

Um Darwin Core Archive (DwC-A) é um pacote de intercâmbio focado em espécimes baseado nas Darwin Core Text Guidelines.

Os grupos taxonômicos selecionados determinam as ocorrências exportadas. O NAHPU segue os vínculos desses espécimes para incluir eventos de coleta, partes e entidades materiais, medições, mídias e pessoas (coletores, catalogadores, preparadores e criadores de mídia). Campos opcionais vazios e tabelas de extensão vazias são omitidos.

Uma coluna só é gravada se possuir termo exato registrado em Darwin Core, Dublin Core ou Audubon Core; campos sem termo são omitidos e listados em Conteúdo do pacote antes da exportação. Use um NAHPU Data Package quando precisar preservar todos os valores.

  • meta.xml
  • eml.xml
  • occurrence.csv
  • material.csv
  • measurement_or_fact.csv
  • multimedia.csv
  • Directorymedia/
    • …

Apenas arquivos com dados são criados:

  • meta.xml descreve o núcleo de ocorrências, extensões, posições de coluna e URIs de termos Darwin Core.
  • eml.xml contém metadados do conjunto de dados.
  • occurrence.csv é sempre a tabela principal.
  • Extensões referenciam o núcleo: partes vão para material.csv, medições para measurement_or_fact.csv e multimedia.csv vincula cada ocorrência ao caminho em media/.

Saída: <nome-arquivo>.dwca.zip.

Um Darwin Core Data Package (DwC-DP) representa dados Darwin Core como tabelas relacionais normalizadas segundo a especificação Darwin Core Data Package e o modelo Frictionless Data Package.

  • datapackage.json
  • eml.xml
  • occurrence.csv
  • identification.csv
  • event.csv
  • material.csv
  • occurrence-assertion.csv
  • media.csv
  • agent.csv
  • occurrence-agent-role.csv
  • event-agent-role.csv
  • material-agent-role.csv
  • media-agent-role.csv
  • occurrence-media.csv
  • Directorymedia/
    • …

Tabelas opcionais aparecem somente quando há dados. datapackage.json declara o perfil DwC-DP, cada recurso CSV, ordem de campos, chaves primárias, chaves estrangeiras e predicados de relação. Colunas estruturais _pk e _fk preservam vínculos relacionais junto aos identificadores legíveis.

O NAHPU grava cada dado na classe definida pelo padrão em vez de repeti-lo em occurrence.csv:

  • occurrence: ocorrência do espécime;
  • identification: determinação e categorias taxonômicas;
  • event: atividade de coleta e contexto geográfico;
  • material: partes do espécime, catálogo e preparação;
  • occurrence-assertion: medições e asserções sem coluna própria (como associação a hospedeiro);
  • agent e *-agent-role: pessoas e papéis (preferindo URLs canônicas ORCID, com UUIDs do NAHPU como alternativa);
  • media e occurrence-media: metadados e vínculos de mídia.

Aplica-se a mesma regra estrita de termos registrados do DwC-A. Coordenadas DDM, DMS ou UTM originais ficam nos termos de coordenadas literais, a extensão positiva de captura soma-se à incerteza de coordenadas e as unidades de peso escolhidas são mantidas.

Para invertebrados, sexo, estágio de vida, casta, associação a hospedeiro e observações são termos de ocorrência; parte do hospedeiro e morfometria opcional (largura da cabeça, comprimento corporal, envergaduras superior e inferior) saem como asserções MeasurementOrFact em milímetros. Cobertura de dossel e parâmetros ambientais ligam-se ao evento de coleta com unidades definidas (°C, %, mg/L, m/s, mm, okta).

Saída: <nome-arquivo>.dwc-dp.tar.gz (padrão) ou <nome-arquivo>.dwc-dp.zip (compatibilidade, com aviso).

O NAHPU Data Package é o formato completo e reprodutível do NAHPU — um Frictionless Data Package enriquecido com metadados do NAHPU. Diferentemente dos pacotes Darwin Core, não filtra por grupo taxonômico: inclui o JSON completo de transferência do projeto ativo, tabelas CSV tipadas equivalentes, mapeamentos de enums, instantâneos dos vocabulários controlados, configurações do usuário e arquivos relacionados.

É o único pacote que preserva campos personalizados sem termo Darwin Core. Apenas tabelas preenchidas no projeto são exportadas (um projeto somente de mamíferos não leva tabelas de aves, herpetofauna, invertebrados nem peixes), e mappings/sqlite_enums.csv lista apenas as colunas enum dessas tabelas presentes.

  • datapackage.json
  • nahpu.toml
  • nahpu-project.json
  • Directorytables/
    • project.csv
    • ...
  • Directoryconfigs/
    • user_configs.json
  • Directorymappings/
    • sqlite_enums.csv
  • Directoryvocabularies/
    • site.csv
    • events.csv
    • specimens.csv
    • symbionts.csv
  • Directoryfiles/
    • ...
  • Directorymedia/
    • ...

Tabelas vazias são omitidas de tables/ e datapackage.json, enquanto os recursos de metadados (mappings/sqlite_enums.csv e vocabularies/*.csv) permanecem sempre presentes (apenas com cabeçalho se vazios).

nahpu-project.json é o mesmo payload versionado gerado por Exportar projeto (projeto ativo, registros relacionados, manifesto de mídia, metadados e avisos), preservando distinções como null versus string vazia sem exigir SQLite. Os CSVs em tables/ vêm do mesmo payload para manter consistência; coleções vazias permanecem em nahpu-project.json para transferência mesmo quando omitidas como CSV.

mappings/sqlite_enums.csv traduz índices inteiros armazenados nas tabelas exportadas. Cada linha informa tabela SQLite, coluna, tipo enum, índice baseado em zero, nome estável em código e rótulo legível no NAHPU.

Os mapeamentos incluídos (filtrados às tabelas presentes no pacote) abrangem:

  • sexo do espécime (mammalAttribute, birdAttribute, herpAttribute, invertebrateAttribute, fishAttribute e specimenIndividual), usando códigos estáveis onde 0, 1 e 2 preservam o significado histórico;
  • confiança da identificação (specimen.iDConfidence);
  • tipo de espécime de peixes (Individual / Lot) e casta de invertebrados;
  • campos reprodutivos de mamíferos e categorias de ecolocalização;
  • campos reprodutivos e de muda de aves.

Inteiros booleanos e medições numéricas não são índices enum e não constam no arquivo.

Quatro recursos CSV registram os vocabulários controlados ativos nas Configurações do NAHPU (ou os padrões se não modificados):

  • vocabularies/site.csv: tipos de local e tipos de hábitat;
  • vocabularies/events.csv: métodos de coleta e papéis de pessoal de coleta;
  • vocabularies/specimens.csv: tipos de espécime, tratamentos, condições, opções de sexo habilitadas, métodos de identificação e estágios de vida;
  • vocabularies/symbionts.csv: tipos de interação, categorias, métodos de detecção, métodos de preparação, localizações anatômicas, armazenamento e tratamentos de simbiontes.

Cada linha guarda chave de configuração, nome do vocabulário, posição baseada em zero e valor, facilitando leitura direta sem analisar configs/user_configs.json.

datapackage.json usa o perfil padrão data-package, declarando cada tabela populada como recurso tabular UTF-8 com ordem de colunas, tipos, restrições, chaves primárias e estrangeiras, além dos esquemas de enums, vocabulários e recursos não tabulares.

Extraia o arquivo antes de carregar datapackage.json, pois os caminhos são relativos à raiz do pacote. Verifique se uma tabela opcional existe antes de lê-la:

from collections import Counter
from frictionless import Package
package = Package("/path/to/extracted-package/datapackage.json")
print(package.resource_names)
if package.has_resource("specimen"):
specimens = package.get_resource("specimen").read_rows()
counts = Counter(row["taxonGroup"] or "Unspecified" for row in specimens)
print(counts)
library(frictionless)
package <- read_package("/path/to/extracted-package/datapackage.json")
resource_names(package)
if ("specimen" %in% resource_names(package)) {
specimens <- read_resource(package, "specimen")
print(table(specimens$taxonGroup, useNA = "ifany"))
}

Manifesto de reprodutibilidade, configurações e arquivos

Seção intitulada “Manifesto de reprodutibilidade, configurações e arquivos”
  • nahpu.toml registra nome e versão do formato, carimbo de data/hora, versão e compilação do aplicativo, versões de esquema de banco de dados e configurações, contagens de tabelas/enums/vocabulários e versões dos crates de nahpu_api (nahpu_dp, nahpu_dwc, nahpu_db, nahpu_configs etc.).
  • configs/user_configs.json armazena a exportação versionada de configurações do usuário (configurações gerais, predefinições de exportação tabular, modelos de documentos e layouts de impressão).
  • media/ e files/ levam mídias referenciadas do projeto, fotos de pessoal referenciado (em media/ com caminhos compatíveis com transferência) e fontes personalizadas (em files/). Arquivos ausentes geram avisos.

Saída: <nome-arquivo>.nahpu-dp.tar.gz (padrão) ou <nome-arquivo>.nahpu-dp.zip, com conteúdo interno idêntico.

Pacote Darwin CoreNAHPU Data PackageBackup do banco de dados
Restaura um projeto no NAHPUNãoSim (Importar projeto ou Mesclar projeto)Sim (toda a instalação)
Finalidade principalIntercâmbio com sistemas externosCópia documentada e reutilizável de um projetoRecuperação completa do dispositivo

O NAHPU Data Package cobre apenas um projeto, portanto continue fazendo backups do banco de dados regulares.

Colaboradores que ampliam campos de pacotes ou grupos taxonômicos podem ler Fluxos de exportação e Adicionar um grupo taxonômico.

Antes de gravar, o NAHPU valida campos obrigatórios e relações; depois, reabre o arquivo para confirmar os metadados raiz. Avisos — como mídia vinculada ausente ou modo de compatibilidade ZIP no DwC-DP — nem sempre bloqueiam a exportação, então revise-os antes de compartilhar ou depositar o pacote.