Objetos Auxiliares

Referências Bibliográficas

Referências são armazenadas em formato BibTeX e podem ser vinculadas a datasets, Taxons, medições, traits, identificações e outros objetos que precisam documentar uma fonte.

Fluxo de cadastro

1. Pesquise pelo título, autor, chave BibTeX ou DOI para evitar duplicatas.
2. Se a publicação possui DOI, informe-o e solicite a busca externa. O sistema tenta recuperar um registro BibTeX por meio dos resolvedores de DOI.
3. Revise o BibTeX recuperado, principalmente autores, título, ano, tipo da publicação, DOI e chave.
4. Se a busca não encontrar a publicação, cole um registro BibTeX exportado por seu gerenciador bibliográfico ou importe um arquivo .bib.
5. Salve e só então vincule a referência aos objetos correspondentes.

A consulta por DOI é uma ajuda de preenchimento, não uma validação editorial. O usuário deve conferir o resultado. DOI repetido e chave BibTeX repetida são tratados como possíveis registros já existentes; não altere a chave apenas para contornar uma duplicata sem antes comparar as referências.

Essas referências podem ser usadas para:

• Conjuntos de dados - com a opção de definir referências para as quais a citação é obrigatória quando o Conjunto de Dados for usado em publicações; mas todas as referências que usaram o conjunto de dados podem ser vinculadas ao conjunto de dados; os links são feitos com uma tabela dinâmica chamada dataset_bibreference;
• Taxons:
  • para especificar a referência na qual o nome do táxon foi descrito, atualmente obrigatório em algumas revistas taxonômicas como PhytoTaxa. Esta referência de descrição é armazenada no bibreference_id da tabela Taxons.
  • para registrar qualquer referência a um nome de táxon, que são então vinculados por meio de uma tabela dinâmica chamada taxons_bibreference.
• Vincule uma Medição a uma fonte publicada;
• Indique a origem de uma definição de Variável.
• Indique citações obrigatórias para um conjunto de dados ou vincule referências usando os dados para um conjunto de dados

Autores, título, ano, DOI e chave são extraídos do BibTeX. A chave deve ser única; o formulário pode padronizá-la a partir do primeiro autor, ano e título.

Acesso a dados usuários plenos podem registrar novas referências, editar detalhes de referências e remover registros de referência que não têm dados associados. BibReferences tem acesso público!

Identificação Taxonômica

O modelo Identificação representa a identificação taxonômica de Indivíduos.

Tabela identifications

• O modelo de Identificação inclui vários campos opcionais, mas além de taxon_id, os identificadores (ligados via pivô identification_person) e a date de identificação são obrigatórios.

• O valor de date pode ser uma Data Incompleta, por exemplo apenas o ano ou ano + mês podem ser registrados.

• Os seguintes campos são opcionais:
  • modifier - é um código numérico que anexa um modificador taxonômico ao nome. Valores possíveis ’s.s.’ = 1, ’s.l.’ = 2, ‘cf.’ = 3, ‘aff.’ = 4, ‘vel aff.’ = 5, o padrão é 0 (nenhum).
  • notes - um texto de escolha, útil para adicionar comentários à identificação.
  • biocollection_id e biocollection_reference - esses campos devem ser usados ​​para indicar que a identificação é baseada na comparação com um voucher depositado em uma coleção biológica e cria um link entre o indivíduo identificado e o espécime da BioColeção no qual a identificação foi baseada. biocollection_id armazena o id de BioColeção e biocollection_reference o identificador único do espécime comparado, ou seja, seria o equivalente ao biocollection_number do modelo Voucher, mas esta referência não precisa ser de um voucher registrado no banco de dados.
• Cada identificação referencia diretamente individual_id; não há mais relacionamentos polimórficos para identificações.
• Mudanças na identificação atual podem gerar registros no Histórico de Identificações, preservando a interpretação biológica anterior, as pessoas, a data, as referências e as evidências correspondentes.

O Histórico de Identificações e o log de atividades têm finalidades diferentes. O primeiro representa a sequência científica de determinações taxonômicas de um indivíduo. O segundo é uma trilha de auditoria das alterações feitas no sistema. Novas importações de história biológica devem usar o endpoint identification-histories, não atividades.

Acesso aos dados: as identificações são atributos dos Indivíduos e não possuem acesso independente!

Pessoas

O modelo Persons armazena nomes de pessoas que podem ou não ser um Usuário diretamente envolvido com a base de dados. Pessoas podem ser: * coletores de Vouchers, Indivíduos e Arquivos de Mídia * identificadores taxonômicos de Indivíduos; * medidores de Medições; * autores para nomes não publicados de Taxons; * especialistas taxonômicos - ligados ao modelo Taxon pela tabela person_taxon; * autores de Conjuntos de Dados

Antes de criar uma Pessoa, pesquise nome, abreviatura, instituição e ORCID. Uma Pessoa é uma identidade compartilhada para autoria, coleta, medição e identificação; não é apenas um contato dentro de um projeto. Usuários plenos podem editar sua própria Pessoa padrão e registros ainda não utilizados. Uma Pessoa usada como padrão por outro usuário ou já relacionada a dados possui restrições de edição e exclusão.

A união de Pessoas duplicadas é uma operação exclusiva de superadministradores, pois substitui relações em várias partes do sistema. Veja Curadoria de bibliotecas compartilhadas.

Tabela persons

• as colunas obrigatórias são a pessoa full_name e abbreviation;
• ao cadastrar uma nova pessoa, o sistema sugere o nome abbreviation, mas o usuário é livre para alterá-lo para melhor adaptá-lo à abreviatura usual de cada pessoa. A ** abreviatura deve ser única ** no banco de dados, duplicatas não são permitidas na tabela Pessoas. Portanto, duas pessoas com exatamente o mesmo nome devem ser diferenciadas de alguma forma na coluna abbreviation.
• A coluna biocollection_id da tabela Pessoas é usada para listar a qual BioColeção uma pessoa está associada, que pode ser usada quando a Pessoa também é um especialista taxonômico.
• Adicionalmente, também podem ser informados o e-mail e a institution a que pertence a pessoa.
• Cada usuário pode ser vinculado a uma pessoa pelo person_id na tabela Usuário. Essa pessoa é então usada como a pessoa ‘padrão’ quando o usuário está logado no sistema.

Acesso a dados usuários plenos podem registrar novas pessoas e editar as pessoas inseridas e remover pessoas que não possuem dados associados. Os administradores podem editar qualquer pessoa. A lista de pessoas tem acesso público.

Tag Model

O modelo Tag permite que os usuários definam palavras-chave traduzíveis que podem ser usadas para sinalizar Conjuntos de dados, Projetos ou Arquivos de Mídia. O modelo Tag está vinculado a esses objetos por meio de uma tabela para cada um, denominada dataset_tag, project_tag e media_tag, respectivamente.

Um Tag pode ter name e description em cada idioma configurado na tabela de Idiomas, que serão armazenados na tabela user_translations. As entradas para cada idioma são mostradas nos formulários da interface.

Acesso a dados usuários plenos podem registrar tags, editar as inseridas e excluir as que não foram usadas. As tags têm acesso público, pois são apenas palavras-chave para facilitar a navegação.

Jobs do usuário

UserJobs representam importações, exportações e outras operações executadas em segundo plano. Cada tarefa apresenta estado, progresso e logs e pode guardar resultados estruturados para cada registro processado, distinguindo sucesso, aviso e erro. Portanto, uma tarefa concluída ainda pode conter linhas que precisam de revisão.

O usuário pode acompanhar suas tarefas, examinar resultados, baixar identificadores afetados e, quando a operação permitir, cancelar ou retomar o processamento. Excluir o registro de um UserJob não substitui o cancelamento de uma tarefa ainda em execução.

Administradores da instalação devem manter os workers da fila e definir uma política para retenção de logs e arquivos. Usuários são responsáveis por revisar os resultados de suas próprias operações.

Traduções do usuário

O modelo UserTranslation armazena as traduções de dados do usuário para: descrições e nomes de Variáveis e de categorias para variáveis categóricas; descrições de Arquivos de Mídia e para Tags. As relações com esses modelos são estabelecidas por relações polimórfica usando os campos translatable_type e translatable_id. Este modelo permite traduções para qualquer idioma listado na tabela languages, atualmente acessível apenas para inserção e edição diretamente no banco de dados SQL. Os formulários de entrada na interface web serão listados para os idiomas registrados.

Vernacular - Nome Popular

Os modelos Vernacular e VernacularCitation permitem registrar nomes populares de organismos, relacionando-os à Taxons e/ou Individuals, ou de paisagens e tipos de ambiente e vegetação, relacionando-os à Locations. A combinação nome+idioma deve ser única na tabela vernaculars e cada registro pode ser vinculado a múltiplos Táxons e/ou Indivíduos, ou Localidades, dependendo das fontes de informação. Cada registro também pode ter uma ou mais citações (texto de citação + BibReference + nota).

• Suporta múltiplos idiomas para o nome popular; o idioma é obrigatório em cada registro e a interface já tem cadastrada uma lista ampla de valores possíveis em config/languagesISO6393.php
• VernacularCitations permite adicionar várias citações sobre os nomes populares.
• Formulários ODBCollect podem exigir nomes populares, permitindo capturar o vernacular no campo junto com medições, táxon e/ou indivíduo, e/ou com uma localidade.

O idioma é parte do significado do registro. Antes de criar um nome, procure a mesma grafia e confira suas relações e citações. Em muitos casos, o correto é acrescentar uma nova citação ou relação ao nome existente. Usuários plenos podem criar nomes populares, mas apenas o criador ou um superadministrador pode editá-los. A exclusão não é permitida quando existem citações registradas por outros usuários. Veja o fluxo de curadoria.

Formulários

Consulte a seção de Formulários em Objetos de Atributos, que detalha o uso na interface web e no aplicativo OpenDataBio Collect.

Datas incompletas

Datas para Vouchers, Indivíduos, Medições e Identificações podem ser incompletas, mas pelo menos ano é obrigatório em todos os casos. As colunas date nas tabelas são do tipo ‘date’ e as datas incompletas são armazenadas com 00 na parte ausente: ‘2005-00-00’ quando apenas o ano é conhecido; ‘1988-08-00’ quando apenas o mês é conhecido.

Auditando mudanças

As modificações nos registros do banco de dados são registradas na tabela activity_log. Esta tabela é gerada pelo pacote ActivityLog. As atividades são mostradas em um link ‘Histórico’ fornecido no show.view dos modelos.

1. O pacote armazena as alterações como json no campo properties, que contém dois elementos: attribute e old, que são basicamente os valores novos vs antigos que foram alterados. Essa estrutura deve ser respeitada.
2. A classe ActivityFunctions contém funções personalizadas para ler as propriedades do registro Json armazenado na tabela activity_log e encontra os valores para mostrar na tabela de dados History;
3. A maioria das mudanças são registradas pelo pacote como um ’trait’ chamada dentro da classe. Estes permitem registrar automaticamente a maioria das atualizações e são configurados para registrar apenas os campos que foram alterados, não registros inteiros (opção dirty). Além disso, a criação de registros não é anotada como atividade, apenas as alterações.
4. Algumas alterações, como de coletores e de identificações indivíduos são registradas separadamente, pois envolvem tabelas relacionadas e o registro é especificado nos arquivos do Controlador;
5. O registro contém um campo log_name que agrupa os tipos de registro e é usado para distinguir os tipos de atividade e é útil para pesquisar a tabela de dados do histórico;
6. Dois registros especiais também são feitos para Conjuntos de Dados:
7. Qualquer download de um Conjunto de Dados pela interface é registrado, então os administradores podem rastrear quem e quando o conjunto de dados foi baixado;
8. Qualquer solicitação de conjunto de dados também é registrada pelo mesmo motivo

O clean-command do pacote NÃO DEVE ser usado durante uma instalação em produção, caso contrário, apagará todas as alterações registradas. Se executado, apagará os logs anteriores ao tempo especificado no arquivo /config/activitylog.php.

{
    "attributes":
    {
        "person_id":"2",
        "taxon_id":"1424",
        "modifier":"2",
        "biocollection_id":"1",
        "biocollection_reference":"1234",
        "notes":"A new fake note has been inserted",
        "date":"2020-02-08"},
    "old":{
        "person_id":674,
        "taxon_id":1413,
        "date":"1995-00-00",
        "modifier":0,
        "biocollection_id":null,
        "notes":null,
        "biocollection_reference":null
    }
}