Documentação

• 1: Visão geral
• 2: Primeiros passos
• 2.1: Primeira vez?
• 2.2: Instalação padrão
• 2.3: Instalação com Docker
• 2.4: Personalizar a instalação
• 3: Serviços de API
• 3.1: Referência rápida
• 3.2: Obter dados - GET
• 3.3: Inserir dados - POST
• 3.4: Atualizar dados - PUT
• 4: Modelo conceitual
• 4.1: Objetos Centrais
• 4.2: Objetos de Atributos
• 4.3: Objetos de Acesso
• 4.4: Objetos Auxiliares
• 5: Como contribuir
• 6: Tutoriais
• 6.1: Obter dados via R
• 6.2: Importar dados via R
• 6.2.1: Importar Localidades
• 6.2.2: Importar BibReferences
• 6.2.3: Importar Vernacular
• 6.2.4: Importar Media
• 6.2.5: Importar Taxons
• 6.2.6: Importar Pessoas
• 6.2.7: Importar Variáveis
• 6.2.8: Importar Indivíduos & Vouchers
• 6.2.9: Importar Medições

1 - Visão geral

OpenDataBio é uma plataforma-web de código aberto projetada para ajudar pesquisadores e organizações que estudam a biodiversidade em regiões tropicais a coletar, armazenar, relacionar e servir dados. Ele é projetado para acomodar muitos tipos de dados usados ​​em ciências biológicas e suas relações, particularmente para estudos de ecologia e biodiversidade e serve como um repositório de dados que permite a usuários baixar ou solicitar dados de pesquisa bem organizados e documentados.

Porque?

Estudos de biodiversidade freqüentemente requerem a integração de uma grande quantidade de dados, exigindo padronização para uso e compartilhamento. Pesquisadores também precisam gerenciar e manter os seus dados de forma contínua e para além de depositá-los de forma estática em repositórios públicos ou data papers.

O OpenDataBio foi desenhado com base na necessidade de organizar e integrar dados históricos e atuais coletados na região amazônica, levando em consideração as práticas de campo e os tipos de dados utilizados por ecologistas e taxonomistas.

O OpenDataBio visa facilitar a padronização e normalização dos dados, utilizando diferentes serviços disponíveis online, dando flexibilidade aos usuários e grupos de usuários, e criando os links necessários entre Localidades, Táxons, Indivíduos, Vouchers e as Medições e os Arquivos de Mídia associados a eles, ao mesmo tempo em que oferece acessibilidade aos dados por meio de um serviço de API próprio, facilitando a distribuição e análise dos dados.

Características relevantes

1. Variáveis ​​personalizadas - flexibilidade para o usuário definir variáveis incluindo casos especiais como variáveis Espectrais, Cores, Links e GeneBank. Essas variáveis são compartilhadas entre usuários e exigem metadados. Medições para tais características podem ser registradas para Indivíduos, Vouchers, Taxons ou Localidades.
2. Taxons podem ser nomes publicados ou não publicados (por exemplo, um morfotipo), sinônimos ou nomes válidos e qualquer nó da árvore da vida pode ser armazenado. A inserção de táxons é verificada em diferentes bases nomenclaturais (Tropicos, IPNI, MycoBank, ZOOBANK, GBIF), minimizando busca por erros ortográficos, autores e sinônimos.
3. Localidades são armazenadas com suas geometrias espaciais, permitindo consultas espaciais. Localidades como Parcelas e Transectos podem ser definidas, facilitando a organização de dados de métodos usados em estudos de biodiversidade.
4. Controle de acesso e versionamento - os dados são organizados em Conjuntos de dados com política de acesso (público, restrito, projeto) e licença. Versões estáticas com filtros e citações próprias podem ser publicadas e baixadas.
5. Diferentes grupos de pesquisa podem usar uma única instalação OpenDataBio, tendo controle sobre edição e acesso de seus dados particulares, enquanto compartilham bibliotecas comuns como Taxonomia, Localidades, Referências bibliográficas e Variáveis.
6. Interface moderna - formulários, listas e buscas foram migrados para Livewire 3 + Alpine; antigas bibliotecas como DataTables, laravel-multiselect e autocompletes legados foram removidas em favor de componentes reativos.
7. API para acessar dados programaticamente - Ferramentas para exportação e importação de dados são fornecidas por meio de serviços de API junto com um cliente API em R, o pacote OpenDataBio-R.
8. Auditoria - o modelo de atividade audita alterações em qualquer registro e downloads de conjuntos de dados completos.
9. O modelo BioColeção permite que uma Coleção Biológica gerencie seus registros de Vouchers e solicitações realizados por usuários.
10. Coleta móvel com o aplicativo Android OpenDataBio Collect, sincronizando formulários configuráveis e dados de campo online/offline.

Saiba mais

• Primeiros passos: instale o OpenDataBio

2 - Primeiros passos

OpenDataBio é um web-software para Linux nas distribuições Debian, Ubuntu e Arch-Linux e pode ser implementado em qualquer máquina baseada em Linux. Não temos planos de suporte ao Windows, mas pode ser fácil de instalar em uma máquina Windows usando o Docker.

Opendatabio é escrito em PHP e desenvolvido com o framework Laravel. Requer um servidor web (apache ou nginx), PHP e um banco de dados SQL - testado apenas com MySQL e MariaDB .

Você pode instalar o OpenDataBio facilmente usando os arquivos Docker incluídos na distribuição, mas esses arquivos docker fornecidos destinam-se apenas ao desenvolvimento e precisam de ajuste para implementar um site em produção.

Se você deseja testar o OpenDataBio, ajudar no desenvolvimento ou ou ter uma instalação individual no seu computador, siga a instalação do Docker.

Prepare para instalação

1. Você pode solicitar uma chave API Tropicos.org para que o OpenDataBio possa recuperar dados taxonômicos do banco de dados Tropicos.org. Se não for fornecido, principalmente o serviço de nomenclatura do GBIF será usado;
2. OpenDataBio envia e-mails para usuários registrados, seja para informar sobre um job que foi concluído, para enviar solicitações de dados para administradores de Conjuntos de Dados, ou para recuperação de senha. Você pode usar um e-mail do Google para isso, mas precisará alterar as opções de segurança da conta para permitir que o OpenDataBio use a conta para enviar e-mails (você precisa ativar a opção de Acesso a aplicativos menos seguros nas configurações da conta do gmail). Portanto, crie um endereço de e-mail dedicado para sua instalação. Verifique o arquivo “config/mail.php” para mais opções sobre como enviar e-mails.

2.1 - Primeira vez?

OpenDataBio é um software para ser instalado num servidor e acessível online. Você pode instalar localmente no seu computador como ambiente de desenvolvimento ou para seu uso pessoal. A instalação via Docker facilita a instalação do aplicativo.

Tipos de usuário

• Se você estiver instalando, o primeiro login para uma instalação do OpenDataBio deve ser feito com o usuário super-administrador padrão: admin@example.org e password1. Essas configurações devem ser alteradas, senão a instalação fica aberta à qualquer pessoa lendo estas instruções.
• Quando um usuário se auto-cadastra numa instalação do OpenDataBio, ele não tem permissão de edição ou inserção de dados, ele apenas ganha um cadastro e acesso aos conjuntos de dadosabertos para usuários registrados e permite que o usuário faça downloads, os quais exigem login.
• Usuário pleno pode contribuir com dados
• Apenas super-administradores podem atribuir o papel de usuário pleno para usuários registrados - diferentes instalações do OpenDataBio podem ter políticas diferentes sobre como você pode obter acesso de usuário pleno.

Ver mais em Usuários.

Prepare seu perfil de usuário-completo

1. Criar um registro de Pessoa para você, e ligar ele como sua pessoa padrão no seu perfil de usuário. Assim, os formulários da interface utilizarão essa Pessoa facilitando a entrada de dados.
2. Você precisará de pelo menos 1 conjunto de dados para entrar seus dados
   1. isso não é necessário para importar dados de bibliotecas compartilhadas, como Pessoas, Localidades, Taxons e Referências Bibliográficas).
3. Você poderá criar tantos projetos e conjuntos de dados que precisar. Entenda bem esses Objetos de Controle de Acesso do OpenDataBio.

Entrando e editando dados

Existem várias maneiras entrar e editar dados no OpenDataBio:

1. Registro por registro por meio da interface web, com ajuda de serviços de API para taxons e referências bibliográficas.
2. Através de Formulários via interface Web, onde você pode entrar Medições.
3. Através do aplicativo para Android ODBCollect, para o qual você pode criar diferentes tipos de Formulários ODBCollect e usar para coletar dados offline e enviar diretamente para o banco de dados.
4. Usando a Application Programming Interface -API do OpenDataBio, que facilita o processamenta de dados em lote (batch):
   1. importar dados de arquivos CSV, XLXS ou ODS usando a interface (Menu Importar)
   2. através do R, usando o pacote OpenDataBio R, que é um cliente para essa API.
   3. criando o seu próprio cliente em outra linguagem
5. Ao usar os serviços da API OpenDataBio você deve preparar seus dados ou arquivo para importação e atualização de acordo com as opções de campo dos verbos POST e PUT para o endpoint específico que você está tentando importar. Verifique também a referência rápida da API.

Dicas para inserir dados

1. Se for inserir dados pela primeira vez, recomendamos que você utilize a interface pelo seu navegador e crie pelo menos um registro para cada objeto que atenda às suas necessidades. Em seguida, experimente as configurações de privacidade do seu espaço de trabalho conjunto de dados e verifique se você pode acessar os dados quando estiver conectado ou não. Ou seja, entenda como os dados ficam organizados e veja como obtê-los.
2. Use Conjunto de dados para um conjunto independente de dados que deve ser distribuído como um grupo. Os conjuntos de dados são publicações dinâmicas, têm autor, dados e título e versões estáticas podem ser geradas, facilitando o download e a distribuição.
3. Embora o ODB tente minimizar a redundância, dar flexibilidade aos usuários tem um custo em algumas definições, como por exemplo, Variáveis e [Pessoas](/docs/concepts/objetos auxiliares/#person) que podem receber registros duplicados. Portanto, deve-se ter cuidado ao criar tais registros. Os administradores podem criar um código de conduta para os usuários de uma instalação ODB para minimizar tal redundância, customizando a instalação.
4. Siga uma ordem de importação de novos dados a partir das bibliotecas de uso comum. Por exemplo, você deve primeiro registrar Taxons, Pessoas, Variáveis e qualquer outra biblioteca comum antes de importar Indivíduos ou Medições. Localidades podem ou não ser necessário importar antes. Se for apenas coordenada geográfica não é necessário.
5. OpenDataBio pode ser instalado com dados previamente organizados para algumas Localidades, unidades administrativas, Município, Estado, País, Unidades de Conservação Federais e Terras Indígenas, e uma base da árvore da vida para Taxons complementada pela filogenia das plantas com sementes até o nível de Ordem conforme a árvore do Angiosperm Phylogeny WebSite.
6. Não há nenhuma necessidade de importar localidades do tipo POINT para importar Indivíduos porque o ODB cria a localidade para você se informar latitude e longitude, e detectará para você a qual são as localidades registradas à qual o indivíduo pertence. Ou seja, ODB detecta as unidades administrativas (Município, Estados, Pais), as Unidades de Conservação e Terras Indígenas e também classes ambientais, dependendo das Localidades registradas na base de dados. Você pode usar a API de validação de localidades para validar previamente as coordenadas.
7. Existem diferentes maneiras de criar localidades do tipo PARCELA e TRANSECTOS - saiba mais em Localidades.
8. A criação de taxons exige apenas a especificação de um nome - ODB pesquisará os serviços de nomenclatura para você, encontrará o nome, metadados e taxons pais ou taxons aceitos, se o seu nome for um sinônimo, e importará todos os eles. Se necessário até encontrar na base algum taxon na hierarquia ancestral. Por exemplo, se informar Ocotea guianensis, mas apenas a ordem Laurales estiver cadastrada na base, ODB irá buscar e cadastrar para você todo o caminho Lauraceae >> Ocotea >> Ocotea guianensis, com autoria, referencia bibliográfica e link ao repositório nomenclatural onde encontrou os dados. Se você estiver importando nomes publicados, basta informar este único atributo. Se o nome taxonômico não for publicado é necessário informar campos adicionais. Portanto, separe a importação em lote de nomes publicados e não publicados em dois conjuntos.
9. O campo notes de qualquer modelo é para texto simples ou para dados formatados como objectos JSON. A opção Json permite que você armazene dados estruturados personalizados em qualquer modelo que tenha o campo notes. Você pode, por exemplo, armazenar como notas alguns campos secundários de fontes originais ao importar dados, mas pode armazenar quaisquer dados adicionais que não sejam fornecidos pela estrutura do banco de dados do OpenDataBio. Esses dados não serão validados pelo OpenDataBio e a padronização depende de você. As notas Json serão importadas e exportadas como um texto JSON e serão apresentadas na interface como uma tabela formatada; URLs em seu Json serão apresentados como links.

2.2 - Instalação padrão

Estas instruções são para uma instalação baseada em apache, mas podem ser facilmente ajustadas para funcionar com nginx.

Requisitos do servidor

1. A versão suportada do PHP >= 8.2 (8.3 recomendado).
2. O servidor da web pode ser apache ou nginx. Para nginx, verifique a configuração nos arquivos do docker para ajustar essas instruções, que são para o apache.
3. Requer um banco de dados SQL, MySQL e MariaDB foram testados, mas também pode funcionar com Postgres. Testado com MySQL 8.0 e MariaDB 10.6+.
4. Extensões PHP necessárias: openssl, pdo, pdo_mysql, mbstring, tokenizer, xml, dom, gd, exif, bcmath, zip, curl, redis.
5. Redis Server é necessário para filas e cache.
6. Tectonic é usado para geração de PDFs/etiquetas a partir de LaTeX.
7. Pandoc é usado para traduzir o código LaTeX usado nas referências bibliográficas. Não é necessário para a instalação, mas é sugerido para uma melhor experiência do usuário.
8. Requer Supervisor, que é necessário para os jobs de usuário

Criar usuário dedicado

A maneira recomendada de instalar o OpenDataBio para produção é usando um usuário de sistema dedicado. Nestas instruções, esse usuário é odbserver.

Baixar OpenDataBio

Faça login como seu Usuário dedicado e baixe ou clone este software para onde deseja instalá-lo. Aqui assumimos que é /home/odbserver/opendatabio para que os arquivos de instalação residam neste diretório. Se este não for o seu caminho, altere abaixo sempre que aplicável.

Prepare o Servidor

Primeiro, instale os softwares Apache, MySQL, PHP, Redis, Tectonic, Pandoc e Supervisor. Em um sistema Debian, você também precisa instalar algumas extensões PHP e ativá-las:

#EXEMPLO EM UBUNTU 22.04

#repositórios
apt-get install software-properties-common
add-apt-repository ppa:ondrej/php
add-apt-repository ppa:ondrej/php ppa:ondrej/apache2
add-apt-repository ppa:ondrej/php
add-apt-repository ppa:ondrej/apache2
apt update

#instala o php
apt install php8.3 -y
apt update
apt upgrade

#instala extensoes (modulos) do php
php --version
#quais os modulos instalados?
php -m

#se algum desses nao estive, instale
apt install php8.3-{bcmath,xml,mysql,zip,intl,gd,cli,curl,mbstring,sqlite3,redis}

#install apache
apt install libapache2-mod-php8.3
#instala redis e tectonic
apt install redis-server tectonic
#install pandoc
apt install pandoc
#install supervisor (needed for jobs)
apt-get install supervisor -y

a2enmod php8.3
phpenmod mbstring
phpenmod xml
phpenmod dom
phpenmod gd
a2enmod rewrite
a2ensite
systemctl restart apache2.service

#To check if they are installed:
php -m | grep -E 'mbstring|cli|xml|gd|mysql|redis|bcmath|pcntl|zip'
tectonic --version
redis-server --version

Adicione o seguinte à sua configuração do Apache.

• Mude /home/odbserver/opendatabio para o seu caminho (os arquivos devem estar acessíveis pelo apache)
• Você pode criar um novo arquivo na pasta sites-available: /etc/apache2/sites-available/opendatabio.conf e colocar o seguinte código nele.

<IfModule alias_module>
        Alias /opendatabio      /home/odbserver/opendatabio/public/
        Alias /fonts /home/odbserver/opendatabio/public/fonts
        Alias /images /home/odbserver/opendatabio/public/images
        <Directory "/home/odbserver/opendatabio/public">
                Require all granted
                AllowOverride All
        </Directory>
</IfModule>

Isso fará com que o Apache redirecione todas as solicitações de / para a pasta correta, e também permitirá que o arquivo .htaccess fornecido controle as regras de reescrita, de forma que os URLs sejam bonitos. Se desejar acessar o arquivo apontando o navegador para a raiz do servidor, adicione também a seguinte diretiva:

RedirectMatch ^/$ /

Configure seu arquivo php.ini. O instalador pode reclamar da falta de extensões do PHP, então lembre-se de ativá-las nos arquivos cli (/etc/php/8.3/cli/php.ini e web ini (/etc/php/8.3/fpm/php.ini) para PHP!

Atualize os valores para as seguintes variáveis:

Encontre os arquivos
php -i | grep 'Configuration File'

Mudar:
	memory_limit should be at least 512M
	post_max_size should be at least 30M
	upload_max_filesize should be at least 30M

Algo como:

[PHP]
allow_url_fopen=1
memory_limit = 512M

post_max_size = 100M
upload_max_filesize = 100M

Habilite os módulos Apache ‘mod_rewrite’ e ‘mod_alias’ e reinicie o servidor:

sudo a2enmod rewrite
sudo a2ensite
sudo systemctl restart apache2.service

Mysql Charset e Collation

1. Você deve adicionar o seguinte ao seu arquivo de configuração do SQL (mariadb.cnf ou my.cnf), ou seja, o conjunto de caracteres e o agrupamento que você escolher para sua instalação devem corresponder aos do config/database.php

[mysqld]
character-set-client-handshake = FALSE  #without this, there is no effect of the init_connect
collation-server      = utf8mb4_unicode_ci
init-connect          = "SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci"
character-set-server  = utf8mb4
log-bin-trust-function-creators = 1
sort_buffer_size = 256M  #espaco suficiente para consultas com geometria


[mariadb]
max_allowed_packet=100M
innodb_log_file_size=300M  #no use for mysql

2. Se estiver usando MariaDB e você ainda tiver problemas do tipo #1267 Illegal mix of collations, então verifique aqui sobre como consertar isso.

Configurar o supervisord

Configure o Supervisor, que é necessário para trabalhos. Crie um nome de arquivo opendatabio-worker.conf na pasta de configuração do Supervisor /etc/supervisor/ conf.d/opendatabio-worker.conf com o seguinte conteúdo, ajustando o caminho conforme a sua instalação:

touch /etc/supervisor/conf.d/opendatabio-worker.conf
echo ";--------------
[program:opendatabio-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /home/odbserver/opendatabio/artisan queue:work --sleep=3 --tries=1 --timeout=0 --memory=512
autostart=true
autorestart=true
user=odbserver
numprocs=8
redirect_stderr=true
stdout_logfile=/home/odbserver/opendatabio/storage/logs/supervisor.log
;--------------" > /etc/supervisor/conf.d/opendatabio-worker.conf

Permissões de arquivos e pastas

• As pastas storage e bootstrap/cache precisam ter permissão de escrita para o usuário do servidor (geralmente www-data). Defina 0775 para esses diretórios.
• O arquivo de configuração .env precisa ter permissão 0640 pois contém senhas.
• Este link mostra diferentes métodos de definir permissões para um aplicativo Laravel.

Este é o método recomendado:

cd /home/odbserver

#note que odbserver e www-data podem mudar na sua configuracao

#defia as permissões tanto par ao seu usuário (aqui odbserver) como para o do apache (aqui www-data)
sudo chown -R odbserver:www-data opendatabio
sudo find ./opendatabio -type f -exec chmod 644 {} \;
sudo find ./opendatabio -type d -exec chmod 755 {} \;


cd /home/odbserver/opendatabio
sudo chgrp -R www-data storage bootstrap/cache
sudo chmod -R ug+rwx storage bootstrap/cache

#pasta media ajustar
sudo find ./storage/app/public/media  -type f -exec chmod 664 {} \;
sudo find ./storage/app/public/media  -type d -exec chmod 775 {} \;

#arquivo de configuracao .env para permissao 640 
sudo chmod 640 ./.env

Instale OpenDataBio

1. Muitas distribuições Linux (Ubuntu e Debian) têm arquivos php.ini diferentes para a interface de linha de comando e para o Apache. Recomenda-se usar o arquivo de configuração do Apache ao executar o script de instalação, para que ele possa apontar corretamente as extensões ou configurações ausentes. Para fazer isso, encontre o caminho correto para o arquivo .ini e exporte-o **antes de usar o comando de instalação php install **.

   Por exemplo,

   export PHPRC=/etc/php/8.3/apache2/php.ini
   

2. O script de instalação baixará o gerenciador de dependências Composer e todas as bibliotecas PHP necessárias listadas no arquivo composer.json. No entanto, se o seu servidor estiver atrás de um proxy, você deve instalar e configurar o Composer independentemente. Implementamos a configuração do PROXY, mas não a estamos mais usando e não testamos corretamente (se você precisar de ajustes, coloque um issue no GitLab).

3. O script solicitará opções de configuração, que são armazenadas no arquivo de ambiente .env na pasta raiz do aplicativo.

   Você pode, opcionalmente, configurar este arquivo antes de executar o instalador:

   • Crie um arquivo .env com o conteúdo do cp .env.example .env fornecido
   • Leia os comentários neste arquivo e ajuste de acordo

4. Execute o instalador:

cd /home/odbserver/opendatabio
php install

5. Seed data - o script irá pergunar se você quer instalar Localidades e Taxons distribuídos com aplicativo. Esses dados são específicos de cada versão do OpenDataBio. Ver as notas das versões no repositório desses dados.

Problemas de instalação

Existem inúmeras maneiras possíveis de instalar o aplicativo, mas podem envolver mais etapas e configurações.

• se o navegador retornar 500|SERVER ERROR , você deve olhar para o último error em storage/logs/laravel.log. Se você tiver ERROR: No application encryption key has been specified execute:

chave artesanal php: gerar
php artisan config: cache

• Se você receber o erro failed to open stream: Connection timed out durante a execução do instalador, isso indica uma configuração incorreta do seu roteamento IPv6. A correção mais fácil é desabilitar o roteamento IPv6 no servidor.
• Se você receber erros durante alimentação aleatória do banco de dados, você pode tentar remover o banco de dados inteiramente e reconstruí-lo. Claro, não execute isso em uma instalação de produção.

php artisan migrate: fresh

• Você pode substituir as tabelas Locations e Taxons usando o seed data depois de reconstruir a base:

php seedodb

Configurações pós-instalação

• Se seus Jobs de importação/exportação não estão sendo processados, certifique-se de que o Supervisor esteja executando systemctl start supervisord && systemctl enable supervisord e verifique os arquivos de log em storage/logs/supervisor.log.
• Você pode alterar várias variáveis ​​de configuração para o aplicativo. O mais importante deles provavelmente está definido pelo instalador, mas há outras variáveis em .env e no arquivo config/app.php que você pode alterar. Em particular, você pode querer alterar as configurações de idioma, fuso horário e e-mail. Execute php artisan config: cache após atualizar os arquivos de configuração.
• Para impedir que os rastreadores do mecanismo de pesquisa indexem seu banco de dados, adicione o seguinte ao seu “robots.txt” na pasta raiz do servidor (no Debian, /var/www/html):

User-agent: *
Disallow: /

• As pastas storage e bootstrap/cache devem ser graváveis ​​pelo usuário do Apache (geralmente www-data). Veja este link para um exemplo de como fazer isso. Defina a permissão 0775 para esses diretórios.

Atualizando uma instalação Apache existente

Antes de atualizar, faça backup do banco de dados, do arquivo .env e de storage/app/public/media.

1. Coloque a aplicação em modo de manutenção:

cd /home/odbserver/opendatabio
php artisan down

2. Atualize o código-fonte para a versão desejada:

git fetch --tags
git checkout <tag-ou-branch-de-destino>

3. Atualize dependências e aplique migrações de banco:

composer install --no-dev --optimize-autoloader
php artisan migrate --force

4. Recrie os caches e reinicie os workers de fila:

php artisan optimize:clear
php artisan config:cache
php artisan queue:restart

5. Tire a aplicação do modo de manutenção:

php artisan up

Se a versão de destino incluir novas variáveis de ambiente, adicione-as ao .env antes de recriar os caches. Veja o conteúdo de .env.example para mudanças necessárias.

Armazenamento e backups

Você pode alterar as configurações de armazenamento em config/filesystem.php, onde pode definir o armazenamento baseado em nuvem, que pode ser necessário se muitos usuários enviarem arquivos de mídia, exigindo muito espaço em disco.

1. Downloads de dados são colocados em fila como Jobs e um arquivo é gravado em uma pasta temporária,sendo excluído quando o trabalho é excluído pelo usuário. Esta pasta é definida como download disk no arquivo de configuração filesystem.php, que aponta para storage/app/public/downloads. Apagar esses arquivos temporários depende dos usuários, portanto, um trabalho de limpeza do cron pode ser aconselhável para implementar em sua instalação;
2. Arquivos de mídia são armazenados por padrão no media disk, que coloca os arquivos na pasta storage/app/ public/media;
3. Para configuração regular crie ambos os diretórios storage/app/public/downloads e storage/app/public/media com permissões graváveis ​​pelo usuário do servidor
4. Lembre-se de incluir a pasta de mídia em um plano de backup;

2.3 - Instalação com Docker

A maneira mais fácil de instalar e executar o OpenDataBio é usando o Docker e os arquivos de configuração do docker fornecidos, que contêm todas as configurações necessárias para executar o ODB. Usa nginx e mysql e supervisor.

Arquivos Docker incluídos

laraverl-app/
----docker/*
----./env.docker
----docker-compose.yml
----Dockerfile
----Makefile

Eles foram adaptados deste link, onde você também encontra uma configuração de produção.

Instalação

Pré-requisitos

1. Docker com plugin Compose (docker compose v2).
2. Linux/mac: usuário no grupo docker ou usar sudo.
3. Windows: Docker Desktop (WSL2/Hyper-V habilitados).

Início rápido (Linux/mac, requer make)

cd opendatabio
make docker-init          # copia .env.docker se faltar, sobe containers, instala composer, gera key, migra e faz storage:link
make seed-odb             # seed opcional para Locations/Taxons
#ou tudo junto
make docker-init SEED=1   # igual acima + seed opcional para Locations/Taxons

• Os assets já estão versionados em public/build, então não é necessário rodar npm no Docker.
• App: http://localhost:8081 (usuário admin@example.org / password1)
• phpMyAdmin: http://localhost:8082

Windows (PowerShell)

cd opendatabio
powershell -ExecutionPolicy Bypass -File scripts/docker-init.ps1
# opcional seed
powershell -ExecutionPolicy Bypass -File scripts/docker-init.ps1 -Seed

Comandos manuais (se você não tiver make)

cp .env.docker .env
docker compose up -d
docker compose exec -T -u www-data laravel composer install --optimize-autoloader
docker compose exec -T -u www-data laravel php artisan key:generate --force
docker compose exec -T -u www-data laravel php artisan migrate --force
docker compose exec -T -u www-data laravel php artisan storage:link

Seed opcional sem make:

docker compose exec -T -u www-data laravel php getseeds
docker exec -i odb_mysql mysql -uroot -psecret odbdocker < storage/Location*.sql
docker exec -i odb_mysql mysql -uroot -psecret odbdocker < storage/Taxon*.sql
rm storage/Location*.sql storage/Taxon*.sql

Persistência de dados

As containers criados pelo Docker podem ser excluídos e regerados sem perder os dados As tabelas mysql são armazenadas em um volume, que se apagado irá excluir a base de dados completamente.

docker volume list

Usando

O arquivo Makefile contém os seguintes comandos para interagir com os contêineres do docker e o odb.

Comandos para construir e criar o app

1. make docker-init - copia .env.docker (se faltar), constroi/sobe containers, instala composer, gera key, migra e faz storage:link
2. make build - construir os contêineres
3. make key-generate - gerar a chave do app e adicioná-la ao .env
4. make composer-install - instalar dependências php
5. make composer-update - atualizar dependências php
6. make composer-dump-autoload - executar o dump-autoload do composer dentro do contêiner
7. make migrate - criar ou atualizar o banco de dados
8. make drop-migrate - apaga a base de dados e migra novamente
9. make seed-odb - popular o banco de dados com localizações e táxons

Comandos para acessar os contêineres docker

1. make start - iniciar todos os contêineres
2. make stop - parar todos os contêineres
3. make restart - reiniciar todos os contêineres
4. make ssh - entrar no contêiner principal da aplicação laravel
5. make ssh-mysql - entrar no contêiner mysql, para que você possa acessar o log do banco de dados usando mysql -uUSER -pPWD
6. make mysql - entrar no console docker do mysql
7. make ssh-nginx - entrar no contêiner nginx
8. make ssh-supervisord - entrar no contêiner supervisord

Comandos de manutenção

1. make optimize - limpar caches e arquivos de log
2. make info - mostrar informações do app
3. make logs - mostrar logs do laravel
4. make logs-mysql - mostrar logs do mysql
5. make logs-nginx - mostrar logs do nginx
6. make logs-supervisord - mostrar logs do supervisord

Recriando os containers

Se você tiver problemas e alterou os arquivos do docker, pode ser necessário reconstruir:

#apaga todas as imagens sem apagr a base de dados
make stop #pare todas
docker system prune -a  #aceitar com Yes

#se quiser pagar os dados
docker volume list
docker volume rm VOLUME_ID

#construa novamente
make build
make start

Atualizando uma instalação Docker existente

Antes de atualizar, faça backup do banco de dados e de storage/app/public/media.

1. Atualize o código-fonte para a versão desejada:

cd opendatabio
git fetch --tags
git checkout <tag-ou-branch-de-destino>

2. Reconstrua e reinicie os contêineres:

make stop
make build
make start

3. Atualize dependências PHP e rode as migrações:

make composer-install
make migrate

4. Atualize os caches do Laravel e reinicie os workers de fila:

make optimize
docker compose exec -T -u www-data laravel php artisan queue:restart

Se a nova versão incluir mudanças no .env, adicione as novas chaves antes de reiniciar os workers em produção.

2.4 - Personalizar a instalação

Mudanças simples que podem ser implementadas no layout de um site OpenDataBio

Logo e imagem de fundo

Para substituir o logotipo da barra de navegação e a imagem da página inicial, apenas coloque seus arquivos de imagem substituindo os arquivos em /public/custom/ sem alterar seus nomes.

Textos e informações

Para alterar o texto de boas-vindas da página inicial, altere os valores para cada entrada nos arquivos:

• /resources/lang/en/customs.php
• /resources/lang/pt-br/customs.php
• Não remova as chaves de entrada. Defina como null para suprimir a exibição no rodapé e na página inicial.

Documentação Local

Você pode adicionar documentação em formato *.md para o repositório em arquivos nas seguintes pastas:

• /resources/docs/en/*
• /resources/docs/pt/*

Este espaço é reservado para administradores definirem documentação e diretivas personalizadas para os usuários de uma instalação específica do OpenDataBio. Por exemplo, este é um espaço para adicionar um código de conduta para os usuários, quem contatar para se tornar um usuário pleno,tutoriais específicos, etc.

NavBar e Rodapé

1. Se você deseja alterar a cor da barra de navegação superior e do rodapé, basta substituir a classe css Boostrap 5 nas tags e arquivos correspondentes na pasta /resources/view/layout.
2. Você pode adicionar html adicional ao rodapé e barra de navegação, alterar o tamanho do logotipo, etc… como desejar.

3 - Serviços de API

Cada instalação do OpenDataBio fornece um serviço de API, permitindo aos usuários OBTER, INSERIR, ATUALIZAR dados programaticamente. O serviço é de acesso aberto a dados públicos, e requer autenticação do usuário para INSERIR e ATUALIZAR dados, ou para OBTER dados de acesso restrito.

O pacote OpenDataBio é um cliente para esta API, permitindo a interação com o repositório de dados diretamente do R.

A API OpenDataBio permite a consulta ao banco de dados e a importação/edição de dados por meio de uma interface inspirada em REST.

Todas as solicitações e respostas da API são formatadas em JSON.

A interação com a API do OpenDataBio

Uma simples chamada para a API OpenDataBio possui quatro partes independentes:

1. HTTP-verbo - GET para exportações, POST para importações e PUT para atualizações.
2. URL-base - o URL usado para acessar seu servidor OpenDataBio + mais / api / v0. Por exemplo, http:// opendatabio.inpa.gov.br/api/v0
3. endpoint - representa o objeto ou coleção de objetos que você deseja acessar, por exemplo, para consultar nomes taxonômicos, o endpoint é “taxons”
4. parâmetros de solicitação - representam a filtragem e o processamento que devem ser feitos com os objetos e são representados na chamada da API após um ponto de interrogação. Por exemplo, para recuperar apenas nomes taxonômicos válidos finalize a solicitação com ?valid = 1.

A chamada API acima pode ser inserida em um navegador para OBTER dados de acesso público. Por exemplo, para obter a lista de táxons válidos de uma instalação do OpenDataBio, a solicitação da API poderia ser:

https://opendb.inpa.gov.br/api/v0/taxons?valid=1&limit=10

Quando usar o OpenDataBio R package essa mesma chamada seria algo como odb_get_taxons(list(valid=1,limit=10)).

A resposta será algo como:

{
  "meta":
  {
    "odb_version":"0.9.1-alpha1",
    "api_version":"v0",
    "server":"http://opendb.inpa.gov.br",
    "full_url":"https://opendb.inpa.gov.br/api/v0/taxons?valid=1&limit1&offset=100"},
    "data":
    [
      {
        "id":62,
        "parent_id":25,
        "author_id":null,
        "scientificName":"Laurales",
        "taxonRank":"Ordem",
        "scientificNameAuthorship":null,
        "namePublishedIn":"Juss. ex Bercht. & J. Presl. In: Prir. Rostlin: 235. (1820).",
        "parentName":"Magnoliidae",
        "family":null,
        "taxonRemarks":null,
        "taxonomicStatus":"accepted",
        "ScientificNameID":"http:\/\/tropicos.org\/Name\/43000015 | https:\/\/www.gbif.org\/species\/407",
        "basisOfRecord":"Taxon"
    }]}

Autenticação da API

1. Não é obrigatória para obter quaisquer dados de acesso público numa base de dados ODB, que por padrão inclui Localidades, Taxons, Referências Bibliográficas, Pessoas e Variáveis.
2. Autenticação é necessária para OBTER quaisquer dados que não sejam de acesso público e para INSERIR e ATUALIZAR dados.

• A autenticação é feita usando um token API, que pode ser encontrado no seu perfil de usuário na interface do aplicativo. O token é atribuído a um único usuário do banco de dados e não deve ser compartilhado, exposto, enviado por e-mail ou armazenado em controles de versão.
• Para autenticar na API OpenDataBio, use o token no cabeçalho “Authorization” da solicitação da API.

Os usuários terão acesso somente aos dados para os quais o usuário tem permissão e para quaisquer dados com acesso público na base de dados. O acesso à Medições, Indivíduos, Vouchers e Mídia depende das permissões compreendidas pelo token do usuário.

Versões da API

A API OpenDataBio segue seu próprio número de versão. Isso significa que o cliente pode esperar usar o mesmo código e obter as mesmas respostas, independentemente da versão do OpenDataBio que o servidor está executando. Todas as alterações feitas na mesma versão da API devem ser compatíveis com versões anteriores. Nosso controle de versão da API é controlado pelo URL, portanto, para solicitar uma versão específica da API, use o número da versão entre o URL base e o endpoint:

https://opendb.inpa.gov.br/api/v1/taxons

https://opendb.inpa.gov.br/api/v2/taxons

3.1 - Referência rápida

OBTER DADOS - GET

Parâmetros GET compartilhados

Parâmetros GET específicos

Importar ou Validar dados - POST

Atualizar dados - PUT

Nomenclature Types

Níveis taxonômicos (Ranks)

3.2 - Obter dados - GET

Parâmetros GET compartilhados

Endpoints GET

Links rápidos

• /
• bibreferences
• biocollections
• datasets
• individuals
• individual-locations
• languages
• locations
• measurements
• media
• persons
• projects
• taxons
• traits
• vernaculars
• vouchers
• userjobs
• activities
• tags

/ (GET)

Testa seu acesso/token.

Nenhum parâmetro para este endpoint.

bibreferences (GET)

Referências bibliográficas (GET lista, POST cria).

Campos retornados

Campos (simple): id, bibkey, year, author, title, doi, url, bibtex

Campos (all): id, bibkey, year, author, title, doi, url, bibtex

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 2,
            "bibkey": "Riberiroetal1999FloraDucke",
            "year": 1999,
            "author": "José Eduardo Lahoz Da Silva Ribeiro and Michael John Gilbert Hopkins and Alberto Vicentini and Cynthia Anne Sothers and Maria Auxiliadora Da Silva Costa and Joneide Mouzinho De Brito and Maria Anália Duarte De Souza and Lúcia Helena Pinheiro Martins and Lúcia Garcez Lohmann and Paulo Apóstolo Costa Lima Assunção and Everaldo Da Costa Pereira and Cosme Fernandes Da Silva and Mariana Rabello Mesquita and Lilian Costa Procópio",
            "title": "Flora Da Reserva Ducke: Guia De Identificação Das Plantas Vasculares De Uma Floresta De Terra Firme Na Amazônica Central",
            "doi": null,
            "url": null,
            "bibtex": "@Article{Riberiroetal1999FloraDucke,\r\n  title = {Flora da Reserva Ducke: Guia de Identifica{\\c{c}}{\\~a}o das Plantas Vasculares de uma Floresta de Terra Firme na Amaz{\\^o}nica Central},\r\n  author = {José Eduardo Lahoz da Silva Ribeiro and Michael John Gilbert Hopkins and Alberto Vicentini and Cynthia Anne Sothers and Maria Auxiliadora da Silva Costa and Joneide Mouzinho de Brito and Maria Anália Duarte de Souza and Lúcia Helena Pinheiro Martins and Lúcia Garcez Lohmann and Paulo Apóstolo Costa Lima Assunç{ã}o and Everaldo da Costa Pereira and Cosme Fernandes da Silva and Mariana Rabello Mesquita and Lilian Costa Procópio},\r\n  journal = {Flora da Reserva Ducke: Guia de Identifica{\\c{c}}{\\~a}o das Plantas Vasculares de uma Floresta de Terra Firme na Amaz{\\^o}nica Central},\r\n  year = {1999},\r\n  publisher = {INPA-DFID Manaus},\r\n  pages = {819p},\r\n}"
        },
        {
            "id": 3,
            "bibkey": "Sutter2006female",
            "year": 2006,
            "author": "D. Merino Sutter and P. I. Forster and P. K. Endress",
            "title": "Female Flowers And Systematic Position Of Picrodendraceae (Euphorbiaceae S.l., Malpighiales)",
            "doi": "10.1007/s00606-006-0414-0",
            "url": "http://dx.doi.org/10.1007/s00606-006-0414-0",
            "bibtex": "@article{Sutter2006female,\n     author = {D. Merino Sutter and P. I. Forster and P. K. Endress},\n     year = {2006},\n     title = {Female flowers and systematic position of Picrodendraceae (Euphorbiaceae s.l., Malpighiales)},\n     issn = {0378-2697 | 1615-6110},\n     issue = {1-4},\n     url = {http://dx.doi.org/10.1007/s00606-006-0414-0},\n     doi = {10.1007/s00606-006-0414-0},\n     volume = {261},\n     page = {187-215},\n     journal = {Plant Systematics and Evolution},\n     journal_short = {Plant Syst. Evol.},\n     published = {Springer Science and Business Media LLC}\n}"
        }
    ]
}

biocollections (GET)

Biocoleções (GET lista, POST cria).

Campos retornados

Campos (simple): id, acronym, name, irn

Campos (all): id, acronym, name, irn, country, city, address

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "acronym": "INPA",
            "name": "Instituto Nacional de Pesquisas da Amazônia",
            "irn": 124921,
            "country": null,
            "city": null,
            "address": null
        },
        {
            "id": 2,
            "acronym": "SPB",
            "name": "Universidade de São Paulo",
            "irn": 126324,
            "country": null,
            "city": null,
            "address": null
        }
    ]
}

datasets (GET)

Datasets e arquivos de versões publicadas (GET lista, POST cria via job de importação).

Campos retornados

Campos (simple): id, name, title, projectName, description, notes, contactEmail, taggedWidth, uuid

Campos (all): id, name, title, projectName, notes, privacyLevel, policy, description, measurements_count, contactEmail, taggedWidth, uuid

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 4,
            "name": "PDBFF-FITO 1ha core plots 1-10cm dbh - TREELETS",
            "title": "Arvoretas (1cm>DAP",
            "projectName": "Projeto Dinâmica Biológica de Fragmentos Florestais (PDBFF-Data)",
            "notes": null,
            "privacyLevel": "Restrito a usuários autorizados",
            "policy": null,
            "description": "Contém o único censo de árvores de pequeno porte 1-10cm de diâmetro nas parcelas de 1ha do PDBFF, em 11 das 69 de parcelas permanentes de 1ha do Programa de Monitoramento de Plantas do PDBFF.",
            "measurements_count": null,
            "contactEmail": "example",
            "taggedWidth": "Parcelas florestais | PDBFF | Fitodemográfico",
            "uuid": "e1d8ce8d-4847-11f0-8e9f-9cb654b86224"
        }
    ]
}

individuals (GET)

Indivíduos (GET lista, POST cria, PUT atualiza).

Campos retornados

Campos (simple): id, basisOfRecord, organismID, recordedByMain, recordNumber, recordedDate, family, scientificName, identificationQualifier, identifiedBy, dateIdentified, locationName, locationParentName, decimalLatitude, decimalLongitude, x, y, gx, gy, angle, distance, datasetName

Campos (all): id, basisOfRecord, organismID, recordedByMain, recordNumber, recordedDate, recordedBy, scientificName, scientificNameAuthorship, taxonPublishedStatus, genus, family, identificationQualifier, identifiedBy, dateIdentified, identificationRemarks, identificationBiocollection, identificationBiocollectionReference, locationName, higherGeography, decimalLatitude, decimalLongitude, georeferenceRemarks, locationParentName, x, y, gx, gy, angle, distance, organismRemarks, datasetName, uuid

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 306246,
            "basisOfRecord": "Organism",
            "organismID": "2639_Spruce_1852",
            "recordedByMain": "Spruce, R.",
            "recordNumber": "2639",
            "recordedDate": "1852-10",
            "recordedBy": "Spruce, R.",
            "scientificName": "Ecclinusa lanceolata",
            "scientificNameAuthorship": "(Mart. & Eichler) Pierre",
            "taxonPublishedStatus": "published",
            "genus": "Ecclinusa",
            "family": "Sapotaceae",
            "identificationQualifier": "",
            "identifiedBy": "Spruce, R.",
            "dateIdentified": "1852-10-00",
            "identificationRemarks": "",
            "identificationBiocollection": null,
            "identificationBiocollectionReference": null,
            "locationName": "São Gabriel da Cachoeira",
            "higherGeography": "São Gabriel da Cachoeira < Amazonas < Brasil",
            "decimalLatitude": 1.1841927,
            "decimalLongitude": -66.80167715,
            "georeferenceRemarks": "decimal coordinates are the CENTROID of the footprintWKT geometry",
            "locationParentName": "Amazonas",
            "x": null,
            "y": null,
            "gx": null,
            "gy": null,
            "angle": null,
            "distance": null,
            "organismRemarks": "prope Panure ad Rio Vaupes Amazonas, Brazil",
            "datasetName": "Exsicatas LABOTAM",
            "uuid": "c01000f0-f437-11ef-b90b-9cb654b86224"
        }
    ]
}

individual-locations (GET)

Ocorrências para indivíduos com múltiplas localizações (GET lista, POST/PUT grava).

Campos retornados

Campos (simple): id, individual_id, basisOfRecord, occurrenceID, organismID, recordedDate, locationName, higherGeography, decimalLatitude, decimalLongitude, x, y, angle, distance, minimumElevation, occurrenceRemarks, scientificName, family, datasetName

Campos (all): id, individual_id, basisOfRecord, occurrenceID, organismID, scientificName, family, recordedDate, locationName, higherGeography, decimalLatitude, decimalLongitude, georeferenceRemarks, x, y, angle, distance, minimumElevation, occurrenceRemarks, organismRemarks, datasetName

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 306244,
            "individual_id": 306246,
            "basisOfRecord": "Occurrence",
            "occurrenceID": "2639_Spruce_1852.1852-10",
            "organismID": "2639_Spruce_1852",
            "scientificName": "Ecclinusa lanceolata",
            "family": "Sapotaceae",
            "recordedDate": "1852-10",
            "locationName": "São Gabriel da Cachoeira",
            "higherGeography": "Brasil > Amazonas > São Gabriel da Cachoeira",
            "decimalLatitude": 1.1841927,
            "decimalLongitude": -66.80167715,
            "georeferenceRemarks": "decimal coordinates are the CENTROID of the footprintWKT geometry",
            "x": null,
            "y": null,
            "angle": null,
            "distance": null,
            "minimumElevation": null,
            "occurrenceRemarks": null,
            "organismRemarks": "prope Panure ad Rio Vaupes Amazonas, Brazil",
            "datasetName": "Exsicatas LABOTAM"
        }
    ]
}

languages (GET)

Lista idiomas disponíveis.

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "code": "en",
            "name": "English",
            "is_locale": 1,
            "created_at": null,
            "updated_at": null
        }
    ]
}

locations (GET)

Localidades (GET lista, POST cria, PUT atualiza).

Campos retornados

Campos (simple): id, basisOfRecord, locationName, adm_level, country_adm_level, x, y, startx, starty, distance_to_search, parent_id, parentName, higherGeography, footprintWKT, locationRemarks, decimalLatitude, decimalLongitude, georeferenceRemarks, geodeticDatum

Campos (all): id, basisOfRecord, locationName, adm_level, country_adm_level, x, y, startx, starty, distance_to_search, parent_id, parentName, higherGeography, footprintWKT, locationRemarks, decimalLatitude, decimalLongitude, georeferenceRemarks, geodeticDatum

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 27297,
            "basisOfRecord": "Location",
            "locationName": "Parcela 1105",
            "adm_level": 100,
            "country_adm_level": "Parcela",
            "x": "100.00",
            "y": "100.00",
            "startx": null,
            "starty": null,
            "distance_to_search": null,
            "parent_id": 27277,
            "parentName": "Fazenda Esteio",
            "higherGeography": "Brasil > Amazonas > Rio Preto da Eva > Fazenda Esteio > Parcela 1105",
            "footprintWKT": "POLYGON((-59.81371985 -2.42215752,-59.81360263 -2.42126619,-59.81270751 -2.42136656,-59.81282469 -2.42225788,-59.81371985 -2.42215752))",
            "locationRemarks": "source: Polígono desenhado a partir das coordenadas de GPS dos vértices; georeferencedBy: Diogo Martins Rosa & Ana Andrade; fundedBy: Edital CNPq-Brasil/LBA 458027/2013-8; geometryBy: Alberto Vicentini; geometryDate: 2021-09-29; warning: Conflito com polígono da UC de 2021. Este polígono deveria ter a mesma geometria do polígono correspondente que faz parte da UC ARIE PDBFF, mas como ele foi gerado pelas coordenadas de campo, foi mantida essa geometria. A UC, portanto, não protege adequadamente essa parcela de monitoramento.",
            "decimalLatitude": -2.42215752,
            "decimalLongitude": -59.81371985,
            "georeferenceRemarks": "decimal coordinates are the START POINT in footprintWKT geometry",
            "geodeticDatum": null
        }
    ]
}

measurements (GET)

Medições de traits (GET lista, POST cria via job de importação, PUT atualiza).

Campos retornados

Campos (simple): id, basisOfRecord, measured_type, measured_id, measurementType, measurementValue, measurementUnit, measurementDeterminedBy, measurementDeterminedDate, scientificName, datasetName, family, sourceCitation

Campos (all): id, basisOfRecord, measured_type, measured_id, measurementType, measurementValue, measurementUnit, measurementDeterminedDate, measurementDeterminedBy, measurementRemarks, resourceRelationship, resourceRelationshipID, relationshipOfResource, scientificName, family, datasetName, measurementMethod, sourceCitation, measurementLocationId, measurementParentId, decimalLatitude, decimalLongitude

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "basisOfRecord": "MeasurementsOrFact",
            "measured_type": "App\\Models\\Individual",
            "measured_id": 86947,
            "measurementType": "treeDbh",
            "measurementValue": 13,
            "measurementUnit": "cm",
            "measurementDeterminedDate": "1979-11-14",
            "measurementDeterminedBy": "Menezes, J.F. | Bahia, R.P. | Lima, J. | Santos, R.M. | Ferreira, A.J.C. | Cardoso, Romeu M.",
            "measurementRemarks": null,
            "resourceRelationship": null,
            "resourceRelationshipID": "1202-1371_Menezes_1979",
            "relationshipOfResource": "measurement of",
            "scientificName": "Paramachaerium ormosioides",
            "family": "Fabaceae",
            "datasetName": "Censos 01 - PDBFF-FITO ForestPlots - 1979-1980",
            "measurementMethod": "Name: Diameter at breast height - DBH | Definition:Diameter at breast height,, i.e. ca. 1.3 meters from the base of the trunk",
            "sourceCitation": null,
            "measurementLocationId": 28280,
            "measurementParentId": null,
            "decimalLatitude": -2.40371599,
            "decimalLongitude": -59.87090972
        }
    ]
}

media (GET)

Metadados de mídia (GET lista, POST cria, PUT atualiza).

Campos retornados

Campos (simple): id, model_type, model_id, basisOfRecord, recordedBy, recordedDate, dwcType, resourceRelationship, resourceRelationshipID, relationshipOfResource, scientificName, family, datasetName, projectName, taggedWith, accessRights, license, file_name, file_url, citation, uuid

Campos (all): id, model_type, model_id, basisOfRecord, recordedBy, recordedDate, dwcType, resourceRelationship, resourceRelationshipID, relationshipOfResource, scientificName, family, datasetName, projectName, taggedWith, accessRights, bibliographicCitation, license, file_name, file_url, citation, uuid, bibtex, userName, created_at

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 20211,
            "model_type": "App\\Models\\Individual",
            "model_id": 111785,
            "basisOfRecord": "MachineObservation",
            "recordedBy": "Francisco Javier Farroñay Pacaya",
            "recordedDate": "2025-03-09",
            "dwcType": "StillImage",
            "resourceRelationship": "Organism",
            "resourceRelationshipID": "3402-1134_Pereira_1986",
            "relationshipOfResource": "StillImage of ",
            "scientificName": "Sacoglottis guianensis",
            "family": "Humiriaceae",
            "datasetName": "Unknown dataset",
            "projectName": "Projeto Dinâmica Biológica de Fragmentos Florestais",
            "taggedWith": "Folha abaxial",
            "accessRights": "Open access.",
            "bibliographicCitation": "Sacoglottis guianensis (Humiriaceae). (2025). By Francisco Javier Farroñay Pacaya. Collection: Pereira, M.J.R. #3402-1134 on 1986-01-24, from Quadrante 52, Parcela 3402-3, Reserva 3402, Cabo Frio, Fazenda Porto Alegre, Amazonas, Brasil (PDBFF). Project: PDBFF-Data. Instituto Nacional de Pesquisas da Amazônia (INPA), Manaus, Amazonas, Brasil. Type: Image. License: CC-BY-NC-SA 4.0. uuid: inpa-odb-3f139ba4-f22b-42d8-9e74-c340309061c2, url: http://localhost/opendatabio",
            "license": "CC-BY-NC-SA 4.0",
            "file_name": "67ce28cd76f4a.jpg",
            "file_url": "http://localhost/opendatabio/storage/media/20211/67ce28cd76f4a.jpg",
            "citation": "Sacoglottis guianensis (Humiriaceae). (2025). By Francisco Javier Farroñay Pacaya. Collection: Pereira, M.J.R. #3402-1134 on 1986-01-24, from Quadrante 52, Parcela 3402-3, Reserva 3402, Cabo Frio, Fazenda Porto Alegre, Amazonas, Brasil (PDBFF). Project: PDBFF-Data. Instituto Nacional de Pesquisas da Amazônia (INPA), Manaus, Amazonas, Brasil. Type: Image. License: CC-BY-NC-SA 4.0. uuid: inpa-odb-3f139ba4-f22b-42d8-9e74-c340309061c2, url: http://localhost/opendatabio",
            "uuid": "3f139ba4-f22b-42d8-9e74-c340309061c2",
            "bibtex": "@misc{Farronay_2025_20211,\n{\n    \"title\": \" Sacoglottis guianensis (Humiriaceae)\",\n    \"year\": \"(2025)\",\n    \"author\": \"Francisco Javier Farroñay Pacaya\",\n    \"howpublished\": \"{http:\\/\\/localhost\\/opendatabio\\/media\\/uuid\\/3f139ba4-f22b-42d8-9e74-c340309061c2}\",\n    \"license\": \"CC-BY-NC-SA 4.0\",\n    \"note\": \"Type: Image; Collection: Pereira, M.J.R. #3402-1134 on 1986-01-24, from Quadrante 52, Parcela 3402-3, Reserva 3402, Cabo Frio, Fazenda Porto Alegre, Amazonas, Brasil (PDBFF); Coordinates: POINT(-59.91500315727877 -2.3929141688648765); License: CC-BY-NC-SA 4.0; Project: PDBFF-Data.; Accessed: 2026-02-04\",\n    \"publisher\": \"Instituto Nacional de Pesquisas da Amazônia (INPA), Manaus, Amazonas, Brasil\"\n}\n}",
            "userName": "example",
            "created_at": "2025-03-09T23:48:29.000000Z"
        }
    ]
}

persons (GET)

Pessoas (GET lista, POST cria, PUT atualiza).

Campos retornados

Campos (simple): id, full_name, abbreviation, emailAddress, institution, notes

Campos (all): id, full_name, abbreviation, emailAddress, institution, notes

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 3127,
            "full_name": "Raimundo Afeganistão",
            "abbreviation": "AFEGANISTÃO, R.",
            "emailAddress": null,
            "institution": null,
            "notes": "PDBFF"
        },
        {
            "id": 14,
            "full_name": "Maria de Fátima  Agra",
            "abbreviation": "Agra, M.F.",
            "emailAddress": null,
            "institution": null,
            "notes": null
        },
        {
            "id": 15,
            "full_name": "J. L. A. Aguiar Jr",
            "abbreviation": "Aguiar Jr., J.L.A.",
            "emailAddress": null,
            "institution": null,
            "notes": null
        }
    ]
}

projects (GET)

Projetos (GET lista).

Campos retornados

Campos (simple): id, acronym, name, description

Campos (all): id, acronym, name, description, pages, urls, created_at, updated_at

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "acronym": "PDBFF-Data",
            "name": "Projeto Dinâmica Biológica de Fragmentos Florestais",
            "description": "Este espaço agrega conjuntos de dados de monitoramentos e pesquisas realizadas nas áreas amostrais do PDBFF,  localizadas na Área de Relevante Interesse Ecológico - ARIE PDBFF.",
            "pages": {
                "en": null,
                "pt-br": null
            },
            "urls": [
                {
                    "url": "https://alfa-pdbff.site/",
                    "label": null,
                    "icon": "fa-solid fa-globe"
                }
            ],
            "created_at": "2022-10-31T07:01:18.000000Z",
            "updated_at": "2023-11-17T21:08:55.000000Z"
        }
    ]
}

taxons (GET)

Nomes taxonômicos (GET lista, POST cria).

Campos retornados

Campos (simple): id, parent_id, author_id, scientificName, taxonRank, scientificNameAuthorship, namePublishedIn, parentName, family, taxonRemarks, taxonomicStatus, scientificNameID, basisOfRecord

Campos (all): id, senior_id, parent_id, author_id, scientificName, taxonRank, scientificNameAuthorship, namePublishedIn, parentName, family, higherClassification, taxonRemarks, taxonomicStatus, acceptedNameUsage, acceptedNameUsageID, parentNameUsage, scientificNameID, basisOfRecord

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 16332,
            "senior_id": null,
            "parent_id": 16331,
            "author_id": null,
            "scientificName": "Aiouea grandifolia",
            "taxonRank": "Species",
            "scientificNameAuthorship": "van der Werff",
            "namePublishedIn": null,
            "parentName": "Aiouea",
            "family": "Lauraceae",
            "higherClassification": "Eukaryota > Plantae > Viridiplantae > Embryophytes > Spermatopsida > Angiosperms > Magnoliidae > Laurales > Lauraceae > Aiouea",
            "taxonRemarks": null,
            "taxonomicStatus": "accepted",
            "acceptedNameUsage": null,
            "acceptedNameUsageID": null,
            "parentNameUsage": "Aiouea",
            "scientificNameID": "https://tropicos.org/Name/17806050 | https://www.gbif.org/species/4175896",
            "basisOfRecord": "Taxon"
        }
    ]
}

traits (GET)

Definições de traits (GET lista, POST cria).

Campos retornados

Campos (simple): id, type, typename, export_name, unit, range_min, range_max, link_type, value_length, name, description, objects, measurementType, categories

Campos (all): id, type, typename, export_name, measurementType, measurementUnit, range_min, range_max, link_type, value_length, name, description, objects, measurementMethod, MeasurementTypeBibkeys, TaggedWith, categories

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 206,
            "type": 1,
            "typename": "QUANT_REAL",
            "export_name": "treeDbh",
            "measurementType": "treeDbh",
            "measurementUnit": "cm",
            "range_min": 0.1,
            "range_max": 700,
            "link_type": null,
            "value_length": null,
            "name": "Diâmetro à altura do peito – DAP",
            "description": "Diâmetro à altura do peito, i.e. medido a ca. 1.3m desde a base do caule",
            "objects": "App\\Models\\Individual | App\\Models\\Voucher | App\\Models\\Location | App\\Models\\Taxon | App\\Models\\Media",
            "measurementMethod": "Name: Diameter at breast height - DBH | Definition:Diameter at breast height,, i.e. ca. 1.3 meters from the base of the trunk",
            "MeasurementTypeBibkeys": "",
            "TaggedWith": "",
            "categories": null
        },
        {
            "id": 207,
            "type": 1,
            "typename": "QUANT_REAL",
            "export_name": "treeDbhPom",
            "measurementType": "treeDbhPom",
            "measurementUnit": "m",
            "range_min": 0,
            "range_max": 15,
            "link_type": null,
            "value_length": null,
            "name": "Ponto de medição do DAP",
            "description": "Ponto de medição do DAP, necessário quando impossível medir a 1.3 m",
            "objects": "App\\Models\\Individual",
            "measurementMethod": "Name: DBH Point of Measurement | Definition:DAP measuring height, necessary when impossible to measure at 1.3 m",
            "MeasurementTypeBibkeys": "",
            "TaggedWith": "",
            "categories": null
        },
        {
            "id": 524,
            "type": 2,
            "typename": "CATEGORICAL",
            "export_name": "stemType",
            "measurementType": "stemType",
            "measurementUnit": null,
            "range_min": null,
            "range_max": null,
            "link_type": null,
            "value_length": null,
            "name": "Tipo de fuste",
            "description": "Tipo de fuste",
            "objects": "App\\Models\\Voucher | App\\Models\\Individual | App\\Models\\Taxon",
            "measurementMethod": "Name: Type of stem | Definition:Type of stem | Categories: CategoryName: Main stem | Definition:The main trunk, usually the thickest. | CategoryName: Secondary stem | Definition:A secondary trunk, there is a thicker one, which defines the area better. A shoot below 1.3 m high is a secondary trunk.",
            "MeasurementTypeBibkeys": "",
            "TaggedWith": "",
            "categories": [
                {
                    "id": 12990,
                    "name": "Fuste principal",
                    "description": "O tronco principal, geralmente o mais grosso.",
                    "rank": 1,
                    "belongs_to_trait": "stemType"
                },
                {
                    "id": 12991,
                    "name": "Fuste secundário",
                    "description": "Um tronco secundário, há outro mais grosso, que define melhor a área. Um rebroto abaixo de 1.3 m de altura é um tronco secundário.",
                    "rank": 2,
                    "belongs_to_trait": "stemType"
                }
            ]
        }
    ]
}

vernaculars (GET)

Nomes vernáculos (GET lista, POST cria).

Campos retornados

Campos (simple): id, name, languageName, notes, locationsList, taxonsList, individualsList, citationsArray

Campos (all): id, name, languageName, languageCode, notes, taxonsList, taxonsListArray, individualsList, individualsListArray, locationsList, locationsListArray, variantsList, variantsListArray, citationsArray, createdBy, created_at, updated_at

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 1,
            "name": "itaúba-preta",
            "languageName": "Portuguese",
            "languageCode": "pt-br",
            "notes": null,
            "taxonsList": "Mezilaurus duckei",
            "taxonsListArray": [
                {
                    "id": 19774,
                    "scientificName": "Mezilaurus duckei",
                    "family": "Lauraceae"
                }
            ],
            "individualsList": "7739_Macedo_2023",
            "individualsListArray": [
                {
                    "id": 510747,
                    "uuid": "c75d9233-f437-11ef-b90b-9cb654b86224",
                    "organismId": "7739_Macedo_2023",
                    "scientificName": "Mezilaurus duckei",
                    "family": "Lauraceae"
                }
            ],
            "locationsList": null,
            "locationsListArray": [],
            "variantsList": "itaúba",
            "variantsListArray": [
                {
                    "id": 2,
                    "name": "itaúba",
                    "languageName": "Tupi",
                    "languageCode": "tup"
                }
            ],
            "citationsArray": [
                {
                    "id": 2,
                    "citation": "ita = pedra; uba = árvore;  preta em referência a cor da madeira",
                    "bibreference_id": null,
                    "bibreference_name": null,
                    "notes": null,
                    "type": "etimology",
                    "createdBy": "example"
                }
            ],
            "createdBy": "example",
            "created_at": "2025-12-15T20:17:16.000000Z",
            "updated_at": "2025-12-15T21:04:53.000000Z"
        }
    ]
}

vouchers (GET)

Vouchers de coleção (GET lista, POST cria, PUT atualiza).

Campos retornados

Campos (simple): id, individual_id, basisOfRecord, occurrenceID, organismID, collectionCode, catalogNumber, typeStatus, recordedByMain, recordNumber, recordedDate, recordedBy, scientificName, family, identificationQualifier, identifiedBy, dateIdentified, identificationRemarks, locationName, decimalLatitude, decimalLongitude, occurrenceRemarks, datasetName

Campos (all): id, individual_id, basisOfRecord, occurrenceID, organismID, collectionCode, catalogNumber, typeStatus, recordedByMain, recordNumber, recordedDate, recordedBy, scientificName, scientificNameAuthorship, taxonPublishedStatus, genus, family, identificationQualifier, identifiedBy, dateIdentified, identificationRemarks, locationName, higherGeography, decimalLatitude, decimalLongitude, georeferenceRemarks, occurrenceRemarks, datasetName, uuid

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 72209,
            "individual_id": 306246,
            "basisOfRecord": "PreservedSpecimens",
            "occurrenceID": "2639.Spruce.K.K000640463",
            "organismID": "2639_Spruce_1852",
            "collectionCode": "K",
            "catalogNumber": "K000640463",
            "typeStatus": "Tipo",
            "recordedByMain": "Spruce, R.",
            "recordNumber": "2639",
            "recordedDate": "1852-10",
            "recordedBy": "Spruce, R.",
            "scientificName": "Ecclinusa lanceolata",
            "scientificNameAuthorship": "(Mart. & Eichler) Pierre",
            "taxonPublishedStatus": "published",
            "genus": "Ecclinusa",
            "family": "Sapotaceae",
            "identificationQualifier": "",
            "identifiedBy": "Spruce, R.",
            "dateIdentified": "1852-10-00",
            "identificationRemarks": "",
            "locationName": "São Gabriel da Cachoeira",
            "higherGeography": "Brasil > Amazonas > São Gabriel da Cachoeira",
            "decimalLatitude": 1.1841927,
            "decimalLongitude": -66.80167715,
            "georeferenceRemarks": "decimal coordinates are the CENTROID of the footprintWKT geometry",
            "occurrenceRemarks": "OrganismRemarks = prope Panure ad Rio Vaupes Amazonas, Brazil",
            "datasetName": "Exsicatas LABOTAM",
            "uuid": "6302316f-2b48-43b5-816b-005df70d15c9"
        }
    ]
}

userjobs (GET)

Jobs em background (importações/exportações) (GET lista).

Campos retornados

Campos (simple): id, dispatcher, status, percentage, created_at, affected_ids, affected_model

Campos (all): id, dispatcher, status, percentage, created_at, updated_at, affected_ids, affected_model, log

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 23652,
            "dispatcher": "App\\Jobs\\BatchUpdateIndividuals",
            "status": "Success",
            "percentage": "100%",
            "created_at": "2025-12-10T14:36:25.000000Z",
            "updated_at": "2025-12-10T14:36:28.000000Z",
            "affected_ids": [
                86136,
                57362,
                85053,
                72256,
                74543
            ],
            "affected_model": "App\\Models\\Individual",
            "log": "[]"
        }
    ]
}

activities (GET)

Lista entradas do log de atividades.

Campos retornados

Campos (simple): id, log_name, description, subject_type, subject_name, subject_id, modified_by, properties, created_at, updated_at

Campos (all): id, log_name, description, subject_type, subject_id, subject_name, modified_by, properties, created_at, updated_at

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "field_key": "taxon_id",
            "field": "Taxon",
            "old_value": "Burseraceae",
            "new_value": "Protium hebetatum forma.b.fito",
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        },
        {
            "field_key": "person_id",
            "field": "Person",
            "old_value": "Macedo, M.T.S",
            "new_value": "Pilco, M.V.",
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        },
        {
            "field_key": "notes",
            "field": "Notes",
            "old_value": "Identificação feita em campo, anotada na planilha de dados.",
            "new_value": null,
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        },
        {
            "field_key": "date",
            "field": "Date",
            "old_value": "2022-06-17",
            "new_value": "2022-11-23",
            "id": 1411696,
            "log_name": "individual",
            "description": "identification updated",
            "subject_type": "App\\Models\\Individual",
            "subject_id": 301705,
            "subject_name": null,
            "modified_by": "example"
        }
    ]
}

tags (GET)

Tags/palavras-chave (GET lista).

Campos retornados

Campos (simple): id, name, description

Campos (all): id, name, description, counts

Exemplo de resposta

{
    "meta": {
        "odb_version": "0.10.0-alpha1",
        "api_version": "v0",
        "server": "http://localhost/opendatabio"
    },
    "data": [
        {
            "id": 11,
            "name": "Folhas adaxial",
            "description": "Images of the adaxial surface of leaves",
            "counts": {
                "Media": 1852,
                "Project": 0,
                "Dataset": 0,
                "ODBTrait": 0
            }
        },
        {
            "id": 12,
            "name": "Folha forma",
            "description": "Imagem mostrando uma folha ou o formato da folha.",
            "counts": {
                "Media": 713,
                "Project": 0,
                "Dataset": 0,
                "ODBTrait": 0
            }
        },
        {
            "id": 13,
            "name": "Frutos",
            "description": "Imagens com frutos",
            "counts": {
                "Media": 2595,
                "Project": 0,
                "Dataset": 0,
                "ODBTrait": 0
            }
        }
    ]
}

3.3 - Inserir dados - POST

Importando dados

Dados estruturados perzonalizados no campo notes

No campo notes de qualquer modelo, você pode armazenar texto simples ou um texto formatado como um objeto JSON contendo dados estruturados. A opção Json permite que você armazene dados estruturados personalizados em qualquer modelo que tenha o campo notes. Esses dados não serão validados pelo OpenDataBio e a padronização de tags e valores depende de você.

Endpoints POST

Links rápidos

• bibreferences
• biocollections
• individuals
• individual-locations
• locations
• locations-validation
• measurements
• media
• persons
• taxons
• traits
• vernaculars
• vouchers
• datasets

bibreferences (POST)

Referências bibliográficas (GET lista, POST cria).

biocollections (POST)

Biocoleções (GET lista, POST cria).

individuals (POST)

Indivíduos (GET lista, POST cria, PUT atualiza).

individual-locations (POST)

Ocorrências para indivíduos com múltiplas localizações (GET lista, POST/PUT grava).

locations (POST)

Localidades (GET lista, POST cria, PUT atualiza).

locations-validation (POST)

Valida coordenadas com locais registrados (POST).

measurements (POST)

Medições de traits (GET lista, POST cria via job de importação, PUT atualiza).

media (POST)

Metadados de mídia (GET lista, POST cria, PUT atualiza).

persons (POST)

Pessoas (GET lista, POST cria, PUT atualiza).

taxons (POST)

Nomes taxonômicos (GET lista, POST cria).

traits (POST)

Definições de traits (GET lista, POST cria).

vernaculars (POST)

Nomes vernáculos (GET lista, POST cria).

vouchers (POST)

Vouchers de coleção (GET lista, POST cria, PUT atualiza).

datasets (POST)

Datasets e arquivos de versões publicadas (GET lista, POST cria via job de importação).

3.4 - Atualizar dados - PUT

Links rápidos

• individuals
• individual-locations
• locations
• measurements
• media
• persons
• vouchers

individuals (PUT)

Indivíduos (GET lista, POST cria, PUT atualiza).

individual-locations (PUT)

Ocorrências para indivíduos com múltiplas localizações (GET lista, POST/PUT grava).

locations (PUT)

Localidades (GET lista, POST cria, PUT atualiza).

measurements (PUT)

Medições de traits (GET lista, POST cria via job de importação, PUT atualiza).

media (PUT)

Metadados de mídia (GET lista, POST cria, PUT atualiza).

persons (PUT)

Pessoas (GET lista, POST cria, PUT atualiza).

vouchers (PUT)

Vouchers de coleção (GET lista, POST cria, PUT atualiza).

4 - Modelo conceitual

4.1 - Objetos Centrais

Os objetos centrais são: Localidades, Vouchers, Indivíduos, Taxons e Arquivos de Mídia. Essas entidades são consideradas “centrais” porque podem receber Medições, ou seja, você pode registrar valores para qualquer Variável.

• O objeto Indivíduo refere-se a um organismo individual que foi observado uma vez (uma ocorrência) ou foi marcado para monitoramento, como uma árvore em uma parcela permanente, uma ave anilhada, um morcego rastreado por rádio. Os indivíduos podem ter um ou mais Vouchers em uma BioColeção e um ou vários Localidades e terão uma Identificação taxonômica. Qualquer atributo medido ou tomado para um individuo pode ser associado a este objeto por meio do modelo Medição.

• O objeto Vouchers é para registros de espécimes coletados de Indivíduo e depositados em uma BioColeção. A identificação taxonômica e a localização de um voucher é aquela do próprio indivíduo a que pertence. Medições podem ser vinculadas a um Voucher quando você deseja registrar explicitamente os dados para aquela amostra específica (por exemplo, medições morfológicas; um marcador molecular de uma extração de uma amostra em um coleta de tecido). Caso contrário, você pode simplesmente registrar a medição para o indivíduo ao qual o voucher pertence. O modelo de voucher também está disponível como tipo especial de Variável, o LinkType, tornando possível registrar contagens para o táxon do voucher em um determinado local.

• O objeto Localidades contém geometrias espaciais, como pontos e polígonos, e inclui parcelas e transectos como casos especiais. Um Indivíduo pode ter uma localidade (por exemplo, uma planta) ou multiplas localidades (por exemplo, um animal monitorado). As localidades do tipo PARCELA e TRANSECTO podem ser registradas como geometria espacial ou apenas com geometria de ponto, e podem ter dimensões cartesianas (metros) registradas. Os indivíduos também podem ter posições cartesianas (X e Y ou angle e distance) em relação à sua Localidade, permitindo contabilizar o mapeamento tradicional de indivíduos em unidades de amostragem. Medições ecológicas relevantes, como dados de solo ou clima, são exemplos de Medições que podem ser vinculadas a localidades.

• O objeto Taxon, além de seu uso para a Identificação taxonômica de Indivíduos, pode receber Medições, permitindo a organização de dados secundários publicados ou qualquer tipo de informação ligada a um nome taxonômico. Uma Referência Bibliográfica pode ser incluída para indicar a fonte de dados. Além disso, o modelo Taxon está disponível como tipo especial de Variável, o LinkType, tornando possível registrar contagens de Taxons em um determinado local.

Localidades

O modelo Localidades armazena dados que representam locais do mundo real. Eles podem ser países, cidades, unidades de conservação ou qualquer polígono espacial, ponto ou trilha na superfície da Terra. Esses objetos são hierárquicos e possuem um relacionamento pai-filho implementado pelo Nested Set Model para dados hierárquicos da biblioteca Laravel Baum que facilita tanto a validação quanto as consultas.

Tipos de Localidades especiais são parcelas e transectos, que juntamente com pontos permitem diferentes métodos de amostragem usados ​​em estudos de biodiversidade. Esses tipos de Localidades também podem ser vinculados a uma localidade administrativa pai e, além disso, a três tipos adicionais de localidades pai como Unidades de Conservação, Territórios Indígenas e qualquer camada Ambiental representando classes de vegetação, classes de solo , etc … com geometrias espaciais definidas.

Tabela locations

• As colunas parent_id junto com rgt, lft e deph são usadas para definir o modelo de conjunto aninhado para consultar ancestrais e descendentes de forma rápida. Apenas parent_id é especificado pelo usuário, as outras colunas são calculadas pela biblioteca Baum a partir dos valores id+parent_id que definem a hierarquia. O mesmo modelo hierárquico é usado para o Taxons, mas para locais há uma restrição espacial, ou seja, um filho deve estar dentro de uma geometria pai.
• A coluna adm_level indica o nível administrativo, ou tipo, de localidade. Por padrão, os seguintes adm_level são configurados no OpenDataBio:
  • 2 para o país, 3 para a primeira divisão dentro do país (província, estado), 4 para a segunda divisão (por exemplo, município), … até adm_level = 10 como áreas administrativas (o código do país é 2 para permitir a padronização com OpenStreeMaps, que é recomendado seguir se sua instalação incluir dados de diferentes países). Os níveis administrativos podem ser configurados em um OpenDataBio antes de importar quaisquer dados para o banco de dados, consulte o guia de instalação para obter detalhes sobre isso.
  • 99 é o código para Unidades de Conservação - uma unidade de conservação é uma location que pode estar vinculada a vários outros locais (qualquer local pode pertencer a uma única UC). Assim, uma localidade pode ter como pai um município e como uc a unidade de conservação a que pertence.
  • 98 é o código para Territórios Indígenas - mesmas propriedades das Unidades de Conservação, mas tratadas separadamente apenas porque algumas UCs ​​e TIs podem se sobrepor amplamente como é o caso da região amazônica
  • 97 é o código para Camadas ambientais - mesmas propriedades das Unidades de Conservação e Territórios Indígenas, ou seja, podem ser vinculadas como localidade pai adicional a qualquer Ponto, Parcela ou Transecto e, portanto, seus indivíduos relacionados. Armazene polígonos e geometrias de multipolígonos representando classes ambientais, como unidades de vegetação, biomas, classes de solo, etc …
  • 100 é o código para parcelas e sub-parcelas - as localidades de tipo parcelas podem ser registradas com geometria de ponto ou polígono, e também devem ter dimensões cartesianas associadas em metros. Se for uma localização de ponto, a geometria é definida a partir do ponto informado. As dimensões cartesianas de uma localidade de tipo parcela também podem ser combinadas com posições cartesianas de subparcelas (ou seja, uma localidade de parcela cujo pai também é uma localidade de parcela) e/ou de indivíduos dentro de tais parcelas, permitindo que indivíduos e subparcelas sejam mapeados dentro de uma subparcela sem especificações de geometria. Em outras palavras, se a geometria espacial da Parcela for desconhecida, ela pode ter como geometria um único ponto GPS ao invés de um polígono, mais suas dimensões x e y. Uma subparcela é uma parcela cuja localidade pai também é uma parcela, e deve consistir em um ponto marcando o início da subparcela mais suas dimensões cartesianas X e Y. Se a geometria do início da subplot for subparcela, ela pode ser armazenada como uma posição relativa à parcela pai usando startx e starty.
  • 101 para transectos - como parcelas, os transectos podem ser registrados tendo uma geometria LineString ou simplesmente uma única coordenada de Latitude e Longitude e uma dimensão. A dimensão cartesiana x para transectos representa o comprimento em metros e é usada para criar linha (orientada para o Norte) quando apenas um ponto é informado. A dimensão y é usada para validar os indivíduos como pertencentes à uma localidade do tipo transecto e representa a distância máxima da linha que um indivíduo deve cair para ser detectado naquele local.
  • 999 para localidades ‘POINT’ como waypoints GPS - isto é para registro de qualquer ponto no espaço
• A coluna datum pode registrar a propriedade do datum da geometria, se conhecida. Se deixado em branco, o local é considerado armazenado usando o datum WGS84. Porém, não há conversor embutido de outros tipos de dados. Portanto os mapas exibidos podem ficar incorretos se diferentes projeções forem usadas. Fortemente recomendado projetar dados como WSG84 para padronização.
• A coluna geom armazena a geometria da localização no banco de dados, permitindo consultas espaciais em linguagem SQL, como detecção das localidades pai. A geometria de um local pode ser POINT, POLYGON, MULTIPOLYGON ou LINESTRING e deve ser formatada usando Well-Known-Text representação geométrica da localidade. Quando um POLYGON é informado, o primeiro ponto dentro da string geométrica é privilegiado, ou seja, pode ser utilizado como referência para marcações relativas. Por exemplo, tal ponto será a referência para as colunas startx e starty de uma subparcela. Portanto, para as geometrias plot e transect, importa qual ponto é listado primeiro na geometria WKT

Acesso a dados usuários completos podem registrar novas Localidades, editar detalhes de Localidades e remover registros de Localidades que não têm dados associados. As Localidades têm acesso público.

Indivíduos

O objeto Indivíduo representa um registro para um organismo individual. Pode ser uma única ocorrência no espaço-tempo de um animal, planta ou fungo, ou um indivíduo monitorado ao longo do tempo, como uma planta em parcela florestal permanente, ou um animal de captura-recaptura ou rádio-rastreamento.

Um Indivíduo pode ter um ou mais Vouchers representando amostras físicas do indivíduo armazenadas em uma ou mais BioColeção e pode ter um ou mais Localidades, representando o local ou locais onde o indivíduo foi registrado.

Indivíduos também podem ter uma Identificação taxonômica, que pode ser própria ou pode depender da identificação de outro indivíduo (identificação-dependente). A identificação é herdada por todos os Vouchers registrados para o Indivíduo. Portanto, os vouchers não têm sua identificação própria. A tabela de Identificações agora referencia sempre individual_id (sem relacionamento polimórfico), e os identificadores são vinculados via pivô identification_person.

Tabela individuals

• Um registro de um Indivíduo deve especificar pelo menos uma Localidade onde foi registrado, a date do registro, o identificador local tag e o collectors do registro e o dataset ao qual o indivíduo pertence.
• A localidade pode ser qualquer localidade cadastrado, independente do nível, permitindo armazenar registros históricos cujo georreferenciamento é apenas um local administrativo. Localidades são armazenadas na tabela individual_location, tendo colunas date_time, altitude,notes e relative_position.
• A coluna relative_position armazena as coordenadas cartesianas do Indivíduo em relação à sua localidade. Isso é apenas para indivíduos localizados em locais do tipo plot, transect ou point. Por exemplo, uma parcela com dimensões de 100x100 metros (1ha) pode ter um indivíduo com posição relativa = PONTO (50 50), que colocará o indivíduo no centro do local (isso é mostrado graficamente na interface da web conforme definido pelas coordenadas x e y do indivíduo). Se a localidade for uma subparcela, a posição dentro da parcela pai também pode ser calculada (isso foi projetado com as parcelas do ForestGeo em mente e é uma coluna na API individual GET. Se a localidade for um PONTO, a posição_relativa pode ser informada como angle (= azimute) e distance, atributos frequentemente medidos em métodos de amostragem. Se a localidade for um TRANSECT, a posição_relativa posiciona o indivíduo em relação à linha, sendo x a distância ao longo do transecto a partir do primeiro ponto, e o y a distância perpendicular onde o indivíduo está localizado, também levando em consideração alguns métodos de amostragem;
• O campo date nos modelos Indivíduo, Voucher, Medição e Identificação pode ser uma Data Incompleta, ou seja, apenas o ano ou ano + mês podem ser registrados.
• A tabela Collector representa os coletores para um indivíduo ou voucher e está vinculada ao Modelo de pessoa. A tabela de coletores possui uma relação polimórfica com os objetos Voucher e Individual, definidos pelas colunas object_id e object_type, permitindo múltiplos coletores para cada registro individual ou voucher. O main_collector indicado é apenas o primeiro coletor listado para essas entidades.
• O campo tag é um código identificador para o indivíduo. Pode ser o número escrito na etiqueta de alumínio de uma árvore em uma parcela florestal, o número de uma anilha numa ave, ou o número de coletor de um espécime. A combinação de main_collector + tag + first_location é restrita a ser única no OpenDataBio. A identificação taxonômica de um indivíduo pode ser definida de duas maneiras:
  • para identificação-própria um registro de Identificação taxonômica é criado na tabela de identifications e a coluna identification_individual_id é preenchida com o próprio id do indivíduo
  • para identificação-dependente, o id do Indivíduo que possui a Identificação é armazenado na coluna identification_individual_id.
  • Conseqüentemente, o modelo Indivíduo contém dois métodos para se relacionar com o modelo de Identificação: um que define identificação-própria e outro que recupera as identificações taxonômicas usando a coluna identification_individual_id.
• Os indivíduos podem ter um ou mais Vouchers depositados em uma BioColeção.
  
  Acesso a dados Indivíduos pertencem a conjuntos de dados, então a política de acesso do conjuntos de dados se aplica aos indivíduos nele inseridos. Apenas os colaboradores e administradores do Conjunto de Dados podem inserir ou editar indivíduos, mesmo se o conjunto de dados for de acesso público.

Taxons

A ideia geral por trás do modelo Taxon é ferramentas para incorporar facilmente nomes taxonômicos válidos de repositórios Taxonômicos Online (atualmente Tropicos.org, GBIF e ZOOBANK estão implementados), mas permitindo a inclusão de nomes que também não são considerados válidos porque eles ainda são não publicados (por exemplo, um morfotipo), ou o usuário discorda da sinonímia publicada, ou o usuário deseja que todos os sinônimos sejam registrados como táxons inválidos no sistema. Além disso, permite definir um nível taxonômico de tipo clado, permitindo armazenar, além das categorias de classificação taxonômica, qualquer nó da árvore da vida. Qualquer táxon registrado pode ser usado em identificações de Indivíduos e Medições podem ser vinculadas a nomes taxonômicos.

Tabela Taxon

• Como, Localidades, o modelo Taxon tem um relacionamento pai-filho, implementado usando o modelo de conjunto aninhado para dados hierárquicos da biblioteca Laravel Baum que permite consultar ancestrais e descendentes. Consequentemente, as colunas rgt, lft e deph da tabela de taxons são preenchidas automaticamente por esta biblioteca na inserção ou atualização dos dados.
• Para ambos, Taxon author e Taxon bibreference, existem duas opções:
  • Para nomes publicados, a autoria da string recuperada pelas APIs será colocada na coluna author = string. Para nomes não publicados, o autor é uma pessoa e será armazenado na coluna author_id.
  • Somente nomes publicados podem ter relação com BibReferences. O campo de string bibreference da tabela Taxon armazena as strings recuperadas por meio de APIs externas, enquanto o bibreference_id se vincula a um objeto Referência Bibliográfica. Eles são usados ​​para armazenar a publicação onde o nome do táxon é descrito e pode ser inserido em ambos os formatos.
  • Além disso, um registro de táxon também pode ter muitas outras referências de Bib por meio de uma tabela dinâmica (taxons_bibreference), permitindo vincular qualquer número de referências bibliográficas a um nome de táxon.

• A coluna level representa a classificação taxonômica (como ordem, gênero, etc.). Ele é numericamente codificado e padronizado de acordo com as regras gerais do IAPT, mas deve acomodar também categorias de nível de táxon relacionadas a animais. Consulte os códigos disponíveis na API Taxon para obter a lista de códigos.
• A coluna parent_id indica o pai do táxon, que pode estar vários níveis acima dele. O nível dos pais deve ser estritamente mais alto do que o nível do táxon, mas você não precisa seguir a hierarquia completa. É possível registrar um táxon sem os pais, por exemplo, um morfotipo não publicado para o qual o gênero e a família são desconhecidos pode ter uma ordem como pai.
• Os nomes das classificações taxonômicas são traduzidos de acordo com o locale definido pelo sistema, que também traduz a interface da web (atualmente implementados apenas em português e inglês).
• O campo nome da tabela de táxons contém apenas a parte específica do nome (no caso de espécies, o epíteto específico), mas a inserção e exibição dos táxons por meio da API ou interface web deve ser feito com a combinação fullname.
• É possível incluir sinônimos na tabela Taxon. Para isso, deve-se preencher o relacionamento senior, que é o id do nome aceito (valid) para um táxon invalid. Se senior_id for preenchido, o táxon é um sinônimo junior e deve ser marcado como invalid.
• Ao inserir um novo táxon publicado, apenas o nome é necessário. O nome será validado e o autor, referência e sinônimos serão recuperados usando os seguintes serviços de API:
  1. BackBone Taxonômico do GBIF - esta será a primeira verificação, da qual links para Tropicos e IPNI também podem ser recuperados se registrar um nome de planta.
  2. Tropicos - se não for encontrado no GBIF, o ODB pesquisará o nome no banco de dados de nomenclatura do Jardim Botânico do Missouri.
  3. IPNI - o Índice Internacional de Nomes Individuais é outro banco de dados usado para validar nomes individuais (temporariamente desativado)
  4. MycoBank - usado para validar um nome se não for encontrado pelos Tropicos nem IPNI apis, e usado para validar nomes para Fungi. Temporariamente desativado
  5. ZOOBANK - quando GBIF, Tropicos, IPNI e MycoBank não conseguem encontrar um nome, então o nome é testado contra a api ZOOBANK, que valida os nomes dos animais. Não fornece publicação de táxons, no entanto.
• Se um nome de táxon for encontrado nos bancos de dados Nomenclatural, o respectivo ID do repositório é armazenado nas tabelas taxon_external, criando um link entre o registro do táxon OpenDataBio e o banco de dados nomenclatural externo.
• Pessoas pode ser definidas como especialistas em táxons por meio de uma tabela dinâmica. Assim, um objeto Taxon pode ter vários especialistas taxonômicos registrados no OpenDataBio.

Acesso a dados: usuários plenos podem registrar um novo táxon e editar os registros existentes se eles não tiverem sido usados ​​para identificação. Atualmente é impossível remover um táxon do banco de dados. A lista de táxons tem acesso público.

Vouchers

O modelo Voucher é usado para armazenar registros de espécimes ou amostras de indivíduos depositados em BioColeções. Portanto, as únicas informações obrigatórias exigidas para registrar um Voucher são individual, biocollection e se o espécime é um tipo de nomenclatural (o padrão é non-type se não informado).

Vouchers table explained

• O Voucher pertence a um Indivíduo e a uma Biocoleção, portanto o individual_id e o biocollection_id são obrigatórios nesta tabela;
• biocollection_number é o código alfanumérico do Voucher na Biocoleção, pode ser ’nulo’ para usuários que desejam apenas indicar que um Indivíduo registrado tem Vouchers em uma Bicoleção específica, ou para Vouchers registrados para biocoleções que não tem um código identificador;
• biocollection_type - é um código numérico que especifica se o Voucher na BioCollection é um tipo nomenclatural. O padrão é 0 (não é um tipo); 1 apenas para ‘Tipo’, uma forma genérica e outros números para outros tipos nomenclaturis
• collectors, um ou múltiplos, são opcionais para Vouchers, exigidos apenas se forem diferentes dos Coletores do Indivíduo. Caso contrário, os coletores do Indivíduo são herdados pelo Voucher. Como para indivíduos, eles são implementados por meio de uma relações polimórfica com a tabela de collectors e o primeiro coletor é o coletor_principal para o voucher, ou seja, aquele que se relaciona com number.
• number, este é o número do coletor, mas como coletores, só deve ser preenchido se for diferente do valor da tag do indivíduo. Portanto, collectors, number e date são úteis para registrar Vouchers para Indivíduos que têm Vouchers coletados em momentos diferentes por pessoas diferentes.
• O campo date nos modelos indivíduos e Voucher pode ser uma data incompleta. Exigido apenas se for diferente do indivíduo a quem o voucher pertence.
• dataset_id o Voucher pertence a um Dataset, que controla a política de acesso;
• notes qualquer anotação de texto para o Voucher.
• O modelo de Voucher interage com o modelo BibReference, permitindo vincular citações múltiplas a Vouchers. Isso é feito através da table voucher_bibreference.

Acesso a dados Os vouchers pertencem a Conjuntos de Dados, portanto, a política de acesso a conjuntos de dados se aplica aos vouchers nele contidos. Os vouchers podem ter um conjunto de dados diferente de seus indivíduos. Se a política do conjunto de dados do Voucher for de acesso aberto e a Indivíduo não, o acesso aos dados do voucher será incompleto, portanto, o conjunto de dados do Voucher deve ter a mesma política de acesso ou uma política de acesso menos restrito do que o conjunto de dados do Indivíduo. Apenas os colaboradores e administradores do conjunto de dados podem inserir ou editar vouchers em um conjunto de dados, mesmo se o conjunto de dados for de acesso público.

Arquivos de Mídia

Arquivos de mídia (imagens, vídeos, áudios) são objetos centrais e podem receber Medições, além de descrições, tags e links para Localidades, Indivíduos, Vouchers ou Taxons.

• Relacionamento principal: polimórfico (model_type, model_id) para Individual, Voucher, Localidade, Táxon ou Projeto.
• dataset_id opcional: quando presente, a licença e o acesso herdam do Dataset; quando ausente, a mídia pode usar apenas project_id ou ficar solta (ainda com controles básicos).
• project_id opcional: útil para agrupar e controlar acesso de mídia mesmo sem dataset.
• Coletores: créditos via tabela polimórfica collectors (múltiplas Pessoas).
• Tags: muitas-para-muitas com Tags, facilitando filtros.
• Custom properties (Spatie Media Library): license (fallback se não houver dataset), date (usada em citações), notes, user_id, voucher_id e location_id auxiliares, citation_fields (define o que entra na citação), além de uuid e URLs gerados pela biblioteca.
• Citações: geradas automaticamente a partir de autores, táxon, dataset/projeto, localização, licença e uuid; BibTeX disponível (generate_citation).
• Armazenamento: usa o pacote spatie/laravel-medialibrary; arquivos ficam no disco configurado e metadados na tabela media.
• Upload: interface web aceita lote (zip + csv) e metadados; API media segue a mesma lógica.
• Medições: aceitam medições via relação polimórfica.

Acesso a dados: se houver dataset_id, a política/licença seguem o Dataset; caso contrário, valem as permissões do Projeto ou as regras gerais de mídia. Usuários completos podem registrar mídia; administradores do dataset (quando existir) também podem excluí-la.

4.2 - Objetos de Atributos

Medições

A tabela measurements armazena os valores para variáveis medidas para os objetos centrais, incluindo Arquivos de Mídia. Seu relacionamento com os objetos centrais é definido por uma relações polimórficas usando as colunas measured_id e measured_type.

• medições devem pertencer a um Conjuntos de dados - coluna dataset_id, que controla a política de acesso
• Uma Pessoa deve ser indicada como o medidor (person_id);
• A coluna bibreference_id pode ser usada para vincular medições extraídas de publicações à sua fonte fonte Bibliográfica
• O valor para a variável medida (trait_id) será armazenado em colunas diferentes, dependendo do tipo de variável:
  • value - esta coluna flutuante armazenará valores para características reais quantitativas;
  • value_i - esta coluna inteira armazenará valores para características Quantitative Integer; e é um campo opcional para características do tipo Link, permitindo, por exemplo, armazenar contagens para uma espécie (uma característica Link Taxon) em um local.
  • value_a - esta coluna de texto armazenará valores para os tipos de traço Texto, Cor e Espectral.
• Valores para variáveis categóricas e ordinais são armazenados na tabela measurement_category
• data - a data de medição é obrigatória em todos os casos

Acesso a dados As medições pertencem a Conjuntos de dados, portanto, a política de acesso a conjuntos de dados se aplica às medições nele. Apenas os colaboradores e administradores do conjunto de dados podem inserir ou editar medições em um conjunto de dados, mesmo se o conjunto de dados for de acesso público.

Variáveis

A tabela traits representa as variáveis ​​definidas pelo usuário para coletar Mediçõespara um dos objetos centrais.

Essas características personalizadas fornecem enorme flexibilidade aos usuários para registrar suas variáveis ​​de interesse. Obviamente, tal flexibilidade tem um custo na padronização dos dados, pois uma mesma variável pode ser registrada de forma diferentes em qualquer instalação do OpenDataBio. Para minimizar a redundância na ontologia de características, os usuários que criam características são avisados ​​sobre esse problema e uma lista de características semelhantes é apresentada no caso de ser encontrada por comparação de nomes de características.

As variáveis têm restrições de edição para evitar perda de dados ou alteração não intencional do significado dos dados. Portanto, embora a lista de variáveis esteja disponível para todos os usuários, as definições de variáveis não podem ser alteradas se outra pessoa também usou a variável para armazenar medições.

Variáveis são entidades traduzíveis, então seus valores de name e description podem ser armazenados em vários idiomas (veja traduções de usuário. Isso é colocado na tabela user_translations através de uma relação polimórfica.

A definição da variável deve ser tão específica quanto necessário. A medição da altura das árvores usando medição direta ou um clinômetro, por exemplo, pode não ser facilmente convertida de uma para outra e deve ser armazenada em variáveis diferentes. Portanto, é altamente recomendável que o campo de definição de variável inclua informações como instrumento de medição e outros metadados que permitam que outros usuários entendam se podem usar sua variável ou criar uma nova.

• A definição da variável deve incluir um export_name, que será usado durante as exportações de dados nos formulários de entrada da interface. Os nomes de exportação devem ser únicos e não devem ter tradução. São recomendados nomes de exportação curtos e [camelCase]​​(https://en.wikipedia.org/wiki/Camel_case) ou [PascalCase]​​(https://en.wikipedia.org/wiki/pascal_case).
• Os seguintes tipos de características estão disponíveis:
  • Quantitativo real - para números reais;
  • Número inteiro quantitativo - para contagens;
  • Categórico - para varáveis categóricas de seleção única;
  • Múltiplo categórico - para muitas categorias selecionáveis;
  • Ordinal categórico - para uma categoria ordenada selecionável (dados semiquantitativos);
  • Texto - para qualquer valor de texto;
  • Cor - para qualquer valor de cor, especificado pelo código de cor hexadecimal (paleta de cores)
  • Link - este é um tipo de variável especial no OpenDataBio. Apenas links para Taxons e Vouchers estão implementados. Exemplo de uso: se você deseja armazenar contagens de espécies conduzidas em uma Localidade, você pode criar uma variável do tipo de link_taxon ou link_voucher. A medição para tal variável terá um campo opcional value para armazenar as contagens. Este tipo de característica também pode ser usado para especificar o hospedeiro de um parasita ou o número de insetos predadores.
  • Espectral - projetado para acomodar dados espectrais, compostos de vários valores de absorbância ou refletância para diferentes números de onda.
  • GenBank - armazena os números de acesso do GenBank que permitem recuperar dados moleculares vinculados a indivíduos ou vouchers armazenados no banco de dados através do GenBank Serviço API.
• A tabela Traits contém campos que permitem a validação do valor da medição, dependendo do tipo de variável:
  • range_max e range_min - se definido para variáveis quantitativas, as medições terão que se ajustar ao intervalo especificado;
  • value_length - obrigatório apenas para variáveis espectrais, valida o comprimento (número de valores) de uma medição espectral;
  • link_type - se a variável for do tipo Link, a medição em value_i deve ser um id do objeto do tipo de link;
  • Para variáveis do tipo cor, os valores são validados no processo de criação da medição e devem estar em conformidade com um código hexadecimal de cores. Um seletor de cores é apresentado na interface web para inserção e edição de medições de cores;
  • Variáveis categóricas e ordinais serão validadas para as categorias registradas ao importar medições por meio da API;
• A coluna unit define a unidade de medida para a variável.
• A coluna bibreference_id é a chave de uma única Referência Bibliográfica que pode ser vinculad à definição da variável.
• A tabela trait_objects armazena o tipo de objetos centrais para o qual a variável pode ter uma medição;

Acesso aos dados O nome, definição, unidade e categorias de uma variável não podem ser atualizados ou removidos se houver alguma medição registrada no banco de dados. As únicas exceções são: (a) é permitido adicionar novas categorias para variáveis categóricas (não ordinais); (b) o usuário atualizando a variavel é a única pessoa que possui medições para a característica; (c) o usuário que atualiza a variável é um administrador de todos os conjuntos de dados com medições usando a variável.

Formulários (web e coleta móvel)

A table formulários armazena formulários do usuário de dois tipos:

1. Formulários para uso na interface web:

• este formulário simplesmente agrega variáveis para capturar medições simultaneamente.
• você pode usar esse tipo de formulário para agregar medições a um determinado objeto central, individualmente
• ou criar uma Tarefa de preenchimento - FormTask, através da interface web, que serve para coletar um conjunto de variáveis para um conjunto de objetos de forma sequencial, garantindo que dados são coletados para todos os objetos alvo; pode definir que usuários tem permissão para incluir dados em uma tarefa

2. Formulários para uso pelo aplicativo Opendatabio ODBCollect

• esse tipo de formulário visa facilitar a coleta de dados atravé de dispositivos Android
• você define o tipo de formulário segundo o tipo de informação que deseja coletar, define várias opções do que irá coletar, pode incluir bibliotecas de nomes taxonômicos, captura de imagens e geolocalização, e onde os dados devem ser salvos;
• define também quem pode usar o formulário
• coleta os dados offline usando o ODBCollect e quando houver conexão o usuário envia os registros coletados que são armazenados no servidor

As definições do usuário para os formulários são salvas no attributo definition da tablea forms. O job odbCollectPrepare é executado quando a definição é alterada para os formulários de tipo ODBCollect, e através desse job as bibliotecas indicadas nas definições (taxons, registros a serem medidos) são geradas e o formulário fica habilitado para ser usado.

A API importOdbCollect recebe os dados enviados pelo usuário e armazena no banco de dados conforme o tipo de formulário e dado informado e uma resposta é enviada ao ODBCollect indicando o status do registro.

4.3 - Objetos de Acesso

Os objetos centrais são: Localidades, Vouchers, Individual, Taxons e Arquivos de Mídia. Essas entidades são consideradas “centrais” porque podem receber Medições, ou seja, você pode registrar valores para qualquer Variável.

Conjuntos de dados controlam acesso aos dados e representam um publicação de dados dinâmica, cuja versão é definida pela data da última edição do registros incluídos. Conjuntos de dados contém Medições, Indivíduos, Vouchers e Arquivos de Mídia.

Projetos são apenas grupos de Conjuntos de dados e de Usuários, representando grupos de usuários com acessibilidade comum a conjuntos de dados cuja privacidade é definida para ser controlada por um projeto.

BioColeções - este modelo serve para criar uma lista reutilizável de acrônimos de Coleções Biológicas no registro de Vouchers. Mas tem opcionalmente a possibilidade de gerir uma coleção de registros de Vouchers e seus Indivíduos, paralelamente ao controle provido por Conjuntos de dados. O controle é apenas na edição e na entrada de dados. Neste caso a BioColeção é administrada pelo sistema.

Projetos e BioColeções devem ter pelo menos um Usuário definido como administrador, que tem controle total sobre o conjunto de dados ou projeto, incluindo a atribuição das seguintes funções a outros usuários: administrador, colaborador ouvisualizador:

• Colaboradores podem inserir e editar objetos, mas não podem excluir registros, nem alterar o conjunto de dados ou a configuração do projeto.
• Visualizadores têm acesso somente de leitura aos dados que não são de acesso aberto.
• Apenas usuários plenos e super-admins podem ser designados como administradores ou colaboradores. Assim, se um usuário que era administrador ou colaborador de um conjunto de dados for rebaixado a “Usuário registrado”, ele se tornará um visualizador.
• Super-admins apenas podem habilitar uma BioColeção para ser administrada pelo sistema.

BioColeções

O modelo Biocollection tem duas funções: (1) prover uma lista de acrônimos para registrar Vouchers de qualquer Coleção Biológica ; (2) gerir os dados de uma Coleção Biológica, facilitando o registro de novos dados (qualquer usuário entra seus dados usando as validações realizadas pelo software e solicita pela interface aos curadores da Coleção o registro dos dados que é feito pelos usuários autorizados na BioColeção, que a partir da transferência passa a controlar a edição dos dados dos Indivíduos. A opção (2) precisa ser implementada por um usuário SuperAdministrador do sistema, que ao habilitar a BioColeção para ser administrada pelo sistema, implementa o modelo de solicitações ODBRequest para que usuários possam pedir dados, amostras, ou registros e mudanças nos dados.

O objeto Biocollection pode ser uma Coleção Biológica formal, como as registradas no Index Herbariorum, ou qualquer outra Coleção Biológica.

O objeto Biocollection também interage com o modelo Person. Quando uma Pessoa está vinculada a uma Biocoleção, ela será listada como especialista taxonômico e pode ter também um vínculo com Taxons.

Acesso a dados - Usuários plenos podem registrar BioColeções, mas apenas usuários super-administradores podem tornar uma BioColeção adminstrável pelo sistema. Remover BioColeções pode ser feito se não há Vouchers ligados e se não é administrada pelo sistema. Se administrável, o modelo interage com Usuários, que podem ser administradores (curadores, pode tudo) ou colaboradores (podem entrar e editar dados, mas não podem apagar registros). Dados de outros Conjuntos de Dados podem fazer parte da BioColeção, permitindo que usuários tenham seus dados completo, mas o controle da edição dos registros é da BioColeção.

Conjuntos de Dados

Conjuntos de Dados são grupos de Medições, Indivíduos, Vouchers Arquivos de Mídia, e podem ter um ou mais Usuários administrators, collaborators ou viewers.

Administradores podem definir o nível de acesso para:

• acesso público
• restrito à usuários cadastrados
• restrito à usuários autorizados
• restrito à usuários do projeto.

Conjuntos de dados podem ter muitas Referências bibliográficas, que junto com os campos policy, metadata permitem anotar o conjunto de dados com informações relevantes para o compartilhamento de dados: * Vincule qualquer publicação que tenha usado o conjunto de dados e, opcionalmente, indique se são de citação obrigatória ao usar os dados; * Defina uma política de dados específica ao usar os dados além de uma licença pública [CreativeCommons.org]((https://creativecommons.org/licenses/) * Detalhe quaisquer metadados relevantes, além daqueles que são automaticamente recuperados do banco de dados, como as definições das Variáveis medidas.

Versionamento de Conjuntos de Dados

Você pode gerar uma ou mais versões estáticas (dataset_versions) para cada conjunto de dados. Quando fizer isso serão gerados arquivos em csv com todos os dados e metadados para distribuição e acesso rápido. O versionamento inclui:

• version - versionamento semântico para o conjunto de dados
• date - a data da versão
• license/license_version - a licença pública [CreativeCommons.org]((https://creativecommons.org/licenses/)
• policy (opcional) - um markdown para você definir a política de uso dos dados
• citation - você define o que seja incluir na citação para a versão e o Opendatabio gera a citação e fornece um bibtex para ela
• metadata (opcional) - um espaço para você falar dos metadados primários
• filters (opcional) - filtros permitem gerar versões para uma parte dos dados num conjunto de dados (por táxons, localidades, pessoas, traits, datas), registrando exatamente o escopo dos arquivos gerados.
• As versões mantêm a lista de autores (pivô dataset_version_person) do conjunto de dados
• Um identificador único UUID é gerado para cada versão
• Os arquivos gerados são armazenados e referenciados em metadata['files'] e metadata['archives'] com o UUID.
• O nível de acesso da versão (dataset_access) pode ser igual ou menos restritivo que o do conjunto de dados, mas o principal objetivo é que versões tenha acesso público.
• Downloads são auditados, mantendo um log do uso e do acesso;
• A API datasets expõe as versões para listagem e download; a interface web usa um componente Livewire para criar/editar versões com pré-visualização da política e citação.

Projetos

Projetos são apenas grupos de Conjuntos de dados e interagem com Usuários, tendo administradores,colaboradores ou visualizadores. Esses usuários podem controlar todos os conjuntos de dados dentro do Projeto que tenham como política de acesso restrita aos usuários do projeto.

Usuários

O tabela users armazena informações sobre os usuários e administradores do banco de dados. Cada Usuário pode ser associado a uma Pessoa. Quando esse usuário insere novos dados, essa pessoa é usada como a pessoa padrão nos formulários. A pessoa só pode estar associada a um único usuário.

Existem três níveis de acesso possíveis para um usuário: * Usuário registrado (o nível mais baixo) - tem muito poucas permissões * Usuário pleno ou completo - podem ser atribuídos como administradores ou colaboradores de Projetos e Conjuntos de Dados; * SuperAdmin (o nível mais alto). - os superadministradores têm acesso a todos os objetos, independentemente da configuração do conjunto de dados. Categoria para os administradores da instalação.

Cada usuário é atribuído ao nível usuário registrado ao se auto-cadastrar numa instalação do OpenDataBio. Depois disso, alguém que seja SuperAdmin pode promovê-lo a Usuário Pleno ou SuperAdmin. SuperAdmins também podem definir se um usuário pleno tem permissão para promover usuários registrados para usuário pleno. Apenas superAdmins podem remover usuários do banco de dados.

Se o adminstrador do sistema configurar a opção EMAIL_VERIFICATION_ENABLED = true nas configurações do Opendatabio, usuários registrados receberão um link via email para validar o email registrado.

Acesso a dados: os usuários são criados no momento do registro e o acesso aos dados são restritos ao próprio usuário e aos administradores. Usuários registrados autorizados tem acesso apenas ao nome.

4.4 - Objetos Auxiliares

Referências Bibliográficas

A tabela bib_references contém basicamente referências formatadas em BibTex armazenadas na coluna bibtex. Você pode facilmente importar referências para o OpenDataBio através da interface, apenas especificando o doi ou simplesmente enviando um registro bibtex ou um arquivo .bib. Essas referências bibliográficas 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

Tabela Bibreferences

• A bibtexKey, autores e outros campos relevantes são extraídos do registro em formato bibtex armazenado na coluna bibtex.
• A ** bibtexkey deve ser única** no banco de dados e uma função auxiliar é fornecida para padronizá-la com o formato <von? sobrenome> <ano> <primeira palavra do título>. A “parte von” do nome é “von”, “di”, “de la”, que fazem parte do sobrenome de alguns autores. A primeira palavra do título ignora palavras de interrupção comuns, como “a”, “o” ou “em”.
• DOI para uma referencia pode ser especificado no campo BibTex relevante ou em uma entrada de texto separada, e são armazenados no campo doi quando presente. Uma API externa encontra o registro bibliográfico quando um usuário informa o doi na interface.

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 de Indivíduos são auditadas para rastrear o histórico de mudanças

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

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

A tabela user_jobs é usada para armazenar temporariamente tarefas que são executadas em segundo plano, como a importação e exportação de dados. Qualquer usuário tem permissão para criar um Job; cancelar seus próprios Jobs; listar os Jobs que não foram excluídos.

A tabela jobs contém os dados usados ​​pelo framework Laravel para interagir com a Queue. Os dados desta tabela são excluídos quando o trabalho é executado com êxito. A tabela user_jobs é usada para manter essas informações, além de permitir logs do processo, repetir tarefas com erros e cancelar tarefas que ainda não foram concluídas.

Jobs com mais de 30 dias podem ser removidos automaticamente para todos os usuários através do comando CleanOldUserJobs, que o administrador pode rodar manualmente ou colocar num cron job para rodar com certa frequência automaticamente.

Acesso a dados: Cada usuário registrado pode ver, editar e remover seus próprios Jobs.

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.

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
    }
}

5 - Como contribuir

Reportar bugs e sugerir melhorias

Criar um issue em um dos repositórios GitLab abaixo, dependendo do problema.

Antes de postar, verifique se o que você quer relatar, perguntar ou propor já não está num issue aberto.

Identifique seu problema com uma ou mais etiquetas.

Colabore com o desenvolvimento, traduções de idiomas e documentos

Esperamos que este projeto cresça de forma colaborativa, necessário para o seu desenvolvimento e utilização no longo prazo. Portanto, colaboradores são bem-vindos para ajudar a corrigir e melhorar o OpenDataBio. A lista de problemas ou melhorias é um lugar para começar a saber o que é necessário fazer. Você pode também contribuir com Tutorias, melhorando a documentação.

As seguintes diretrizes são recomendadas se você deseja colaborar:

1. Comunique-se com o administrador do repositório OpenDataBio indicando em quais questões deseja trabalhar e junte-se à equipe de desenvolvimento.
2. Faça um Fork do repositório
3. Boa prática criar um branch para guardar suas modificações ou adições
4. Quando estiver satisfeito com os resultados, faça uma solicitação de pull-request ao mantenedor do projeto para revisar sua contribuição e mesclá-la com o código do repositório. Consulte a Ajuda do GitLab para obter mais informações sobre pull requests.

Diretivas de programação

1. Use a instalação do docker para desenvolvimento, compartilhada entre os desenvolvedores. A interface agora usa Livewire 3 + Alpine para formulários e tabelas; novos CRUDs e filtros devem seguir esse padrão.
2. Este software deve aderir ao Controle de Versão Semântico, a partir da versão 0.1.0-alpha1. O pacote R complementar e a Documentação (este site) devem seguir um esquema de controle de versão semelhante. Ao alterar a versão, uma tag de lançamento (release) deve ser criada com a versão antiga.
3. Todas as variáveis ​​e funções devem ser nomeadas em Inglês, com as entidades e campos relacionados ao banco de dados sendo nomeados no singular. Todas as tabelas (quando apropriado) devem ter uma coluna “id” e as chaves estrangeiras devem fazer referência à tabela base com o sufixo “_id”, exceto em casos de autojunções (como “taxon.parent_id”) ou chaves estrangeiras polimórficas. O id de cada tabela tem tipo INT e deve ser autoincrementado.
4. Use a classe laravel migration para adicionar qualquer modificação à estrutura do banco de dados. A migração deve incluir, se aplicável, a manipulação de dados existentes, permitindo upgrades.
5. Use camelCase para métodos (ou seja, relacionamentos) e snake_case para funções.
6. Documente o código com comentários e crie páginas de documentação neste site, se necessário.
7. Deve haver uma estrutura para armazenar quais plugins estão instalados em uma determinada versão do banco de dados quais são as versões de sistema compatíveis.
8. Este sistema usa Vite para compilar o código SASS e JavaScript. Se você adicionar ou modificar esses arquivos, utilize npm run build (ou npm run dev durante o desenvolvimento).

Colabore com a documentação

Tutoriais para lidar com tarefas específicas são bem vindos!

Para criar um tutorial:

1. Fork o repositório de documentação. Ao clonar este repositório ou do seu fork inclua a opção de submódulo para obter também o repositório de tema Docsy incluído. Você precisará de Hugo para executar este site em seu localhost.
2. Crie um branch para confirmar suas modificações ou adições
3. Adicione seu tutorial:

• Crie uma pasta dentro de contents/{lang}/docs/Tutorials usando kebab-case para o nome da pasta. Ex. primeiro-tutorial
• Você pode criar um tutorial em um único idioma ou em vários idiomas. Basta colocá-lo na pasta correta
• Dentro da pasta criada, crie um arquivo chamado _index.md e crie o conteúdo de markdown com seu tutorial.
• Você pode começar copiando o conteúdo de um tutorial já incluído ou veja a documentação do Docsy

1. Quando estiver satisfeito com os resultados, faça uma solicitação de pull para pedir ao mantenedor do projeto para revisar sua contribuição e mesclá-la com o repositório. Consulte a Ajuda do GitLab para obter mais informações sobre o uso de solicitações pull.

Colabore com traduções

Você pode ajudar com as traduções da interface do aplicativo ou deste site com a documentação. Se quiser ter um novo idioma para sua instalação, compartilhe sua tradução, criando um pull request com os novos arquivos.

Novo idioma para a interface da web:

1. faça um fork e crie um branch para o repositório principal
2. crie uma pasta para o novo idioma usando o Código ISO 639-1 dentro da pasta resources/lang

cd opendatabio
cd resources/lang
cp en es

1. traduza todos os valores para todas as variáveis ​​dentro de todos os arquivos na nova pasta (pode usar a tradução do google para começar, apenas certifique-se de que os nomes das variáveis ​​não sejam traduzidos, caso contrário, não funcionará).
2. adicione o idioma ao array em config/languages.php
3. adicionar o idioma à tabela de languages do banco de dados criando uma migração laravel
4. solicite um pull request

Novo idioma para o site de documentação

1. faça um fork e crie um branch para o repositório de documentação
2. crie uma pasta para o novo idioma usando o Código ISO 639-1 dentro da pasta content

bash
cd opendatabio.gitlab.io
cd content
cp pt es

1. verifique todos os arquivos dentro da pasta e traduza onde necessário (pode usar a tradução do google, apenas certifique-se de traduzir apenas o que pode ser traduzido)
2. Veja se funciona bem na sua máquina local (precisa installar Hugo e servir digitando hugo serve na pasta do site, que ficará visível pelo navegador no endereço http://localhost:1313/.
3. empurre para o seu branch e faça um pull request

Relações polimóficas

Algumas das relações dentro da OpenDataBio são mapeadas usando Relações polimórficas. Elas são indicadas em um modelo por ter um campo terminando em _id e um campo terminando em _type. Por exemplo, todos os Objetos Centrais podem ter Medições, e essas relações são estabelecidas na tabela measurements pelas colunas measured_id e measured_type, o primeiro armazenando a id do modelo relacionado, o segundo é a classe do modelo medido em strings como ‘App\Models\Individual’, ‘App\Models\Voucher’, ‘App\Models\Taxon’, ‘App\Models\Location’.

Imagens do modelo conceitual

A maioria das figuras para explicar o modelo de dados foram geradas usando Laravel ER Diagram Generator, que permite mostrar todos os métodos implementados em cada modelo e não apenas os links diretos da tabela:

Para gerar essas figuras, um comando personalizado php artisan foi gerado. Esse commando está definido no arquivo app/Console/Commands/GenerateOdbErds.php.

Para atualizar as figuras siga os seguintes passos:

• As figuras são configuradas no arquivo config/erd-generator-odb.php. Existem muitas opções adicionais para personalizar as figuras alterando ou adicionando variáveis ​​graphviz ao arquivo config/erd-generator-base.php.
• O comando personalizado é php artisan odb: erd {$ model}, onde model é a chave dos arrays em config / erd-generator-odb.php, ou a palavra" all “, para regenerar todas as figuras doc. `bash cd opendatabio fazer ssh php artisan odb: erd all `
• As figuras serão salvas em storage / app / public / dev-imgs
• Copie as novas imagens para a pasta do site de documentação. Eles precisam ser colocados em contents / {lang} / concepts / {subfolder} para todos os idiomas e nas respectivas subpastas.

6 - Tutoriais

6.1 - Obter dados via R

Configure a conexão

1. Configure a conexão com o servidor OpenDataBio usando a função odb_config() do pacote. Os parâmetros mais importantes para esta função são base_url, que deve apontar para a URL da API do seu servidor OpenDataBio e token, que é o token de acesso usado para autenticar seu usuário.
2. O token só é necessário para obter dados de conjuntos de dados que possuem uma das políticas de acesso restrito. Os dados dos conjuntos de dados de acesso público podem ser extraídos sem a especificação do token.
3. Seu token está disponível em seu perfil na interface web

library(opendatabio)
base_url="https://opendb.inpa.gov.br/api"
token ="O SEU TOKEN AQUI"
cfg = odb_config(base_url=base_url, token = token)

A configuração mais avançada envolve a definição de uma versão de API específica, um agente de usuário personalizado ou outros cabeçalhos HTTP, mas isso não é coberto aqui.

Teste sua conexão

A função odb_test() pode ser usada para verificar se a conexão foi bem sucedida e se seu usuário foi identificado corretamente:

odb_test(cfg)
#will output
Host: https://opendb.inpa.gov.br/api/v0
Versions: server 0.9.1-alpha1 api v0
$message
[1] "Success!"

$user
[1] "admin@example.org"

Como alternativa, você pode especificar esses parâmetros como variáveis ​​de sistema. Antes de iniciar o R, configure isso em seu shell (ou adicione ao final de seu arquivo .bashrc):

export ODB_TOKEN="YourToken"
export ODB_BASE_URL="https://opendb.inpa.gov.br/api"
export ODB_API_VERSION="v0"

Obter dados

Verifique a Referência rápida da API GET para obter uma lista completa de endpoints e parâmetros de solicitação. Veja também os parâmetros genéricos, em especial save_job que é importante para baixar grandes conjuntos de dados.

Para dados de acesso público o token é opcional. Abaixo alguns exemplos. Siga um raciocínio semelhante para usar os demais endpoints. Veja a ajuda do pacote R para todas as funções odb_get_{endpoint} disponíveis.

Obtendo nomes de táxons

Consulte GET API Taxon Endpoint para uma lista dos parâmetros de solicitação e uma lista de campos de resposta.

base_url="https://opendb.inpa.gov.br/api"
cfg = odb_config(base_url=base_url)
#get id for a taxon
mag.id = odb_get_taxons(params=list(name='Magnoliidae',fields='id,name'),odb_cfg = cfg)
#use this id to get all descendants of this taxon
odb_taxons = odb_get_taxons(params=list(root=mag.id$id,fields='id,scientificName,taxonRank,parent_id,parentName'),odb_cfg = cfg)
head(odb_taxons)

Algo como, dependo da sua base:

  id scientificName taxonRank parent_id  parentName
1 25    Magnoliidae     Clado        20 Angiosperms
2 43     Canellales     Ordem        25 Magnoliidae
3 62       Laurales     Ordem        25 Magnoliidae
4 65    Magnoliales     Ordem        25 Magnoliidae
5 74      Piperales     Ordem        25 Magnoliidae
6 93  Chloranthales     Ordem        25 Magnoliidae

Obtendo Localidades e geometrias

Consulte GET API Location Endpoint para os parâmetros de solicitação e uma lista de campos de resposta.

Obtenha alguns campos listando todas as Unidades de Conservação (adm_level=99) registradas no servidor:

base_url="https://opendb.inpa.gov.br/api"
cfg = odb_config(base_url=base_url)
odblocais = odb_get_locations(params = list(fields='id,name,parent_id,parentName',adm_level=99),odb_cfg = cfg)
head(odblocais)

Se o servidor usar os dados de seed fornecidos o resultado será:

id                                                           name
1 5628                              Estação Ecológica Mico-Leão-Preto
2 5698          Área de Relevante Interesse Ecológico Ilha do Ameixal
3 5700 Área de Relevante Interesse Ecológico da Mata de Santa Genebra
4 5703     Área de Relevante Interesse Ecológico Buriti de Vassununga
5 5707                                Reserva Extrativista do Mandira
6 5728                                   Floresta Nacional de Ipanema
parent_id parentName
1         6  São Paulo
2         6  São Paulo
3         6  São Paulo
4         6  São Paulo
5         6  São Paulo
6         6  São Paulo

Localidades como objetos espaciais em R

Para obter um objeto espacial em R, use o pacote sf. O exemplo abaixo plota um gráfico e seus subgráficos e também exporta as localizações como kml e shapefile.

library(sf)
library(opendatabio)

#download dados de uma parcela
cfg <- odb_config(base_url = "https://opendb.inpa.gov.br/api")

#daddos da parcela
parcela = odb_get_locations(params = list(fields='all',name='Parcela 25ha'), odb_cfg = cfg)
parcela$type = 'main plot'

#subparcelas
subplots = odb_get_locations(params = list(fields='all',location_root=parcela$id), odb_cfg = cfg)
subplots = subplots[subplots$adm_level==100 & subplots$id!=parcela$id,]
subplots$type = 'sub plot'

#convert footprintWKT para sf geometries
geoms <- st_as_sfc(parcela$footprintWKT, crs = 4326)
parcela_sf <- st_sf(parcela, geometry = geoms)

geoms <- st_as_sfc(subplots$footprintWKT, crs = 4326)
subplots_sf <- st_sf(subplots, geometry = geoms)

#imprime
png("plots_with_subplots.png", width = 15, height = 15,units='cm',res=300)
  par(mar=c(2,2,3,2))
  plot(st_geometry(subplots_sf),border='green',main = parcela$locationName)
  plot(st_geometry(parcela_sf),border='red',add=T)
  labs = gsub("Quadrat ","",subplots_sf$locationName)
  text(
   st_coordinates(st_centroid(subplots_sf)),
   labels = labs,
   cex = 0.2, col = "blue"
  )
dev.off()


#salva como kml
locais = rbind(parcela_sf,subplots_sf)
locais$name <- locais$locationName
cols_to_include <- setdiff(names(locais), c("footprintWKT",'locationName'))
locais_kml <- locais[, c("name", cols_to_include[cols_to_include != "name"])]
st_write(locais_kml, "plots_and_subplots.kml", layer=parcela$locationName, driver = "KML", delete_dsn = TRUE)
#salva como shapefile
st_write(locais_kml, "plots_and_subplots.shp", layer=parcela$locationName, delete_layer = TRUE)

Figura gerada:

Validando coordendas geográficas

Ver POST Locations-Validation Endpoint para parametros e campos resposta.

#sua conexao
library(opendatabio)
base_url="http://localhost/opendatabio/api"
token ="o seu token aqui"
cfg = odb_config(base_url=base_url, token = token)
odb_test(cfg)

#dados fake
dados = data.frame(
  latitude = sample(seq(-2,2,by=0.00001),10),
  longitude = sample(seq(-60,-59,by=0.00001),10)
)

#envia para validar
jb = odb_validate_locations(dados,odb_cfg = cfg)

#monitora execução
odb_get_jobs(params=list(id=jb$id),odb_cfg = cfg)

#pega resultado
dadosValidados = odb_get_jobs(params=list(id=jb$id,get_file=T),odb_cfg = cfg)