Registry: Implementar um serviço de pesquisa para coleções GrSciColl

Coloquei no DEV uma primeira versão do serviço de pesquisa de coleções (ainda não usa as tags da máquina) para ver se era isso que estávamos esperando.

Ele retorna uma lista de correspondências de instituições e outra para correspondências de coleção. É uma lista porque os códigos não são únicos, então pode haver casos em que podemos ter várias opções e não podemos discriminar por nenhum outro campo.

Para cada partida, ele mostra:

• tipo: pode ser exact ou fuzzy . exact é apenas se o código e o identificador corresponderem. Caso contrário, é fuzzy .
• observações: são observações para entender como a partida foi feita. Os valores possíveis são:
  
  
  
  • CODE_MATCH : não ignora o caso
  
  
  • IDENTIFIER_MATCH : não ignora o caso
  
  
  • ALTERNATIVE_CODE_MATCH : não ignora o caso
  
  
  • NAME_MATCH : ignora maiúsculas e minúsculas e remove acentos e espaços em branco, mas não faz correspondências de prefixo ou sufixo
  
  
  • PROBABLY_ON_LOAN : acontece quando a instituição proprietária e a instituição não são a mesma
  
  
  • INST_COLL_MISMATCH : acontece quando a instituição de uma coleção não está presente nas instituições correspondidas.
  
  

Quando há correspondências de instituições, uma coleção só corresponde vagamente se pertencer a qualquer instituição correspondida. As correspondências de coleção exatas sempre serão retornadas.

Você pode verificar estes exemplos para ver como o serviço funciona:

• http://api.gbif-dev.org/v1/grscicoll/lookup?collectionCode=herbarium retorna 567 coleções
• http://api.gbif-dev.org/v1/grscicoll/lookup?collectionCode=herbarium&institutionCode=UNCA retorna 1 instituição e 1 coleção
• http://api.gbif-dev.org/v1/grscicoll/lookup?collectionCode=UNCA&institutionCode=UNCA&institutionId=gbif :ih: irn:240135 retorna 1 instituição e 2 coleções
• http://api.gbif-dev.org/v1/grscicoll/lookup?collectionCode=UIMNH&collectionId=http ://grbio.org/cool/zrdp-fspx&institutionCode=K é um exemplo de INST_COLL_MISMATCH
• http://api.gbif-dev.org/v1/grscicoll/lookup?ownerInstitutionCode=MBMC&institutionCode=K é um exemplo de PROBABLY_ON_LOAN

Estou perdendo alguma coisa @MortenHofft @timrobertson100 ?

Adicionei a verificação de tags de máquina seguindo o formato que já era usado nos pipelines por enquanto:

• Espaço de nomes: processing.gbif.org
• Nomes:
  
  
  
  • institutionCode : mapeia um código de instituição para uma instituição GrSciColl
  
  
  • collectionCode : mapeia um código de coleção para uma coleção GrSciColl
  
  
  • collectionToInstitutionCode : mapeia um código de coleção para uma instituição GrSciColl. Eu provavelmente renomearia para collectionCodeToInstitution (TBD).
  
  
  • institutionToCollectionCode : mapeia um código de instituição para uma coleção GrSciColl. Eu provavelmente renomearia para institutionCodeToCollection (TBD).
  
  

O valor das tags deve seguir o padrão {key}:{code} .

Parece bom - estou muito curioso para vê-lo aplicado a dados reais.

verboso ou não
Devemos ter uma opção "detalhada" como na correspondência de espécies?

Se imaginarmos qualquer pessoa além da equipe usando isso, pode ser útil ter apenas uma opção match or none . Diga Plazi usando-o para criar links de códigos de coleção em artigos.

// plain lookup - not verbose - will at most return one institution and one collection.
{
  institutionMatch: {
    matchType: 'NONE'
  },
  {
    collectionMatch: {
      matchType: 'FUZZY',
      reasons: ['SAME_NAME', 'SAME_CODE', 'SAME_COUNTRY'],
      entity: {
        ...
      }
    }
  }
}

// verbose option
// could be like the one running in dev
{
  "institutionMatches": [],
  "collectionMatches": [
    ...
  ]
}

em nomear
a API de correspondência de espécies usa matchType em vez de type e os clusters usam reasons em vez de remarks .

Dados reais
Antes de executá-lo em dados reais, gostaria de saber se valeria a pena apenas verificar as 500 principais combinações distintas de código da instituição/id colelctionCode/ID e avaliar manualmente algumas delas? Podemos aprender algo (digamos que precisamos tentar inverter id e código)

O que constitui uma partida?
Quando você imagina que isso vai desencadear uma partida?

• Exatamente apenas?
• Fuzzy, mas apenas um resultado
• Instituição exata, mas apenas uma coleção difusa?

País como desambiguador
Faria sentido adicionar país como um parâmetro de pesquisa? Ao indexar as ocorrências, poderíamos adicionar o país do editor para desambiguar quando houver, por exemplo, 2 correspondências de coleção? Ou isso é melhor feito pelo consumidor iterando os resultados?

Eu apenas tentei combinar com base em um extrato csv que eu tinha há algum tempo.
O csv é distinto institutionId, institutionCode, datasetKey, publisherKey com uma contagem de ocorrências para cada um.

Peguei qualquer coisa com mais de 2500 ocorrências e tentei compará-las com o serviço.

105,871,241 occurrences had a single match
 24,553,278 with an exact singular match
 27,113,941 occurrences had multiple matches
 34,998,066 occurrences had no match

2,374 combinations was tested against the service (multiple can be the same since it included dataset and publisher)

Isso não é um mau começo. Ainda não avaliei a qualidade das partidas.

_O que constitui uma partida?_
Quando você imagina que isso vai desencadear uma partida?

• Exatamente apenas?
• Fuzzy, mas apenas um resultado
• Instituição exata, mas apenas uma coleção difusa?

Para isso você quer dizer para a versão não detalhada onde mostramos apenas 1 correspondência, certo?

Pode ser algo como:

• Para instituições
  
  
  
  • Apenas uma correspondência exata
  
  
  • Apenas uma partida difusa
  
  
• Para coleções
  
  
  
  • Apenas uma correspondência exata
  
  
  • Se houve correspondência de instituição, apenas uma correspondência difusa cuja instituição seja a mesma da instituição correspondida
  
  
  • Se não houvesse uma correspondência de instituição, apenas uma correspondência difusa
  
  

Você acha que também devemos fornecer um status geral de correspondência?

_O que constitui uma partida?_
Quando você imagina que isso vai desencadear uma partida?

• Exatamente apenas?
• Fuzzy, mas apenas um resultado
• Instituição exata, mas apenas uma coleção difusa?

Para isso você quer dizer para a versão não detalhada onde mostramos apenas 1 correspondência, certo?

Eu quis dizer ao usá-lo em pipelines para atribuir IDs GrSciColl a ocorrências. Imaginava que esse serviço incluía a decisão e toda a lógica. Como funciona para outros serviços de pesquisa?

Isso me lembra que você mencionou outro dia que considerou adicionar todos os IDs correspondentes ao índice de ocorrência.
Acho que existem 2 versões possíveis:

• Adicionando todos os candidatos possíveis. Isso efetivamente empurra a carga para a interface do usuário ou usuário. E os mesmos espécimes apareceriam em várias coleções.
• Adicione um link apenas quando tivermos uma correspondência confiável. O serviço assume a responsabilidade da declaração. Seremos capazes de igualar menos.

Sou mais a favor da versão 2. Só adicionamos um GrSciColl ID a uma ocorrência quando temos 1 correspondência confiável. Não é uma matriz de correspondências de candidatos. E se quisermos mais correspondências, nos dirigimos aos editores para adicionar identificadores melhores ao GrSciColl ou às ocorrências. Ou adicionamos tags de máquina aos conjuntos de dados no caso.

Se for útil ter todos os candidatos indexados, poderíamos considerar um campo separado para isso?

Deve O serviço retornar sinalizadores. CORRESPONDÊNCIA DE CÓDIGO DE COLEÇÃO FUZZY. NENHUMA CORRESPONDÊNCIA DO CÓDIGO DE COBRANÇA. Semelhante ao serviço de correspondência de espécies.

Eu posso pensar nessas bandeiras:

• AMBIGUOUS_INSTITUTION : mais de 1 instituição foi encontrada e não conseguimos desempate
• AMBIGUOUS_COLLECTION : igual acima, mas para coleções
• FUZZY_INSTITUTION_MATCH : 1 instituição correspondente, mas indistinta
• FUZZY_COLLECTION_MATCH : igual acima, mas para coleções
• INSTITUTION_NAME_USED : o campo institutionCode contém o nome da instituição em vez do código
• OWNER_INSTITUTION_NAME_USED : igual acima, mas para a instituição proprietária
• COLLECTION_NAME_USED : igual acima, mas para coleções
• NO_COLLECTION_CODE_MATCH : o código fornecido não corresponde
• NO_INSTITUTION_CODE_MATCH : igual acima
• NO_COLLECTION_ID_MATCH : o ID fornecido não corresponde
• NO_INSTITUTION_ID_MATCH : igual acima
• INSTITUTION_COLLECTION_MISMATCH : a coleção encontrada não pertence à instituição correspondente

EDIT: os INSTITUTION_NAME_USED talvez possam ser removidos e apenas usei o FUZZY_INSTITUTION_MATCH para esses casos. Não sei o que seria mais útil para os editores

Eu gosto disso - tenho a impressão de que muitos editores apreciam essas bandeiras e agem de acordo com elas. Isso dará a eles os insights para modificar os dados e melhorar a correspondência.

O serviço agora retorna uma resposta como:

{
  "institutionMatch": {
    ...
  },
  "collectionMatch": {
    ...
  },
  alternativeMatches { 
    institutionMatches: []
    collectionMatches: []
  }
}

As correspondências alternativas são mostradas apenas se o parâmetro verbose estiver definido como verdadeiro. As partidas difusas são limitadas a 20 resultados por motivos de desempenho.

Também foi adicionado um parâmetro Country usado para desempate: http://api.gbif-dev.org/v1/grscicoll/lookup?institutionCode=BR&country=BE&verbose=true

Uma correspondência acontece se alguma destas condições for atendida:

• Há apenas 1 correspondência de tag de máquina
• Há apenas 1 correspondência exata
• Existem várias correspondências exatas, mas apenas uma corresponde ao parâmetro de país recebido
• Há apenas 1 correspondência difusa
• Existem várias correspondências difusas, mas apenas uma corresponde pelo menos ao código ou ao id e mais um campo (nome ou código alternativo)
• Existem várias correspondências difusas, mas apenas uma corresponde ao parâmetro de país recebido

Além disso, as instituições cuja instituição proprietária é diferente da instituição não são consideradas compatíveis. Além disso, as coleções cuja instituição não corresponde à correspondência aceita pela instituição também não são consideradas uma correspondência.

Eu não adicionei os sinalizadores, mas um campo de status:

• ACCEPTED : partida aceita
• AMBIGUOUS : mais de 1 resultado foi encontrado e não conseguimos desempate
• AMBIGUOUS_MACHINE_TAGS : o mesmo que acima, mas com correspondências de tag de máquina
• AMBIGUOUS_OWNER : há resultados, mas não coincidem com o proprietário da instituição, por isso os ignoramos para não vincular as cobranças de empréstimos
• AMBIGUOUS_INSTITUTION_MISMATCH : existem correspondências difusas, mas não pertencem à instituição correspondida
• DOUBTFUL : a correspondência encontrada é difusa

O resto das bandeiras podem ser inferidas do campo reasons da partida. Os problemas podem ser definidos nesse campo em pipelines.

Extraí dos nossos dados no PROD combinações desses campos que estão presentes em mais de 1000 registros:

• v_institutionid
• v_institutioncode
• v_ownerinstitutioncode
• v_collectioncode
• v_collectionid
• datasetkey

Além disso, peguei o país da organização de publicação do conjunto de dados.

Então eu os passei para o serviço de pesquisa no UAT. Os resultados estão nesta planilha