# orcid-disambiguation

Cette instance propose un outil de de désambiguisation d'auteur orcid

## Description et utilisation du programme

- [v1/orcidDisambiguation](#v1%2forcidDisambiguation)

Ce web service prend en entrée du JSON avec deux champs, `id` et `value`, et
renvoie un JSON avec un identifiant ORCID dans le champ `value`.  
Le champ `value` doit contenir un json contenant au minimum les deux champs
suivants:

- `firstName` : Le prénom de la personne que l'on souhaite trouver
- `lastName` : Le nom de la personne que l'on souhaite trouver

De plus, d'autres champs facultatifs (mais fortement recommandés d'utiliser pour
plus de précision) sont disponibles :

- `email` : Une liste `[]` d'emails de la personne que l'on souhaite trouver
- `titles` : Une liste `[]` de titres de publication scientifique de la personne
  que l'on souhaite trouver
- `coAuthors` : Une liste `[]` de co-auteurs de la personne que l'on souhaite
  trouver
- `affiliations` : Une liste `[]` d'affiliations (présentes ou passées) de la
  personne que l'on souhaite trouver

Le programme fonctionne de la façon suivante :

- Il fait une requète ORCID pour le `firstName` et `lastName` donnés récupérant
  un nombre `nameDepth` de personnes, `nameDepth` étant un paramètre fixé à 20,
  et pouvant être modifié via l'url.
- L'algorithme va ensuite prendre ces personnes une à une et effectuer dans cet
  ordre :
  - Si une liste d'emails a été fournie en entrée, il va effectuer une
    comparaison avec les emails disponibles pour la personne. Il s'arrète si il
    y en a un en commun, et renvoie l'orcid de la personne.
- L'algorithme va ensuite faire une requête afin de récupérer un nombre
  `worksDepth` maximum de publications de la personne, `worksDepth` étant un
  paramètre fixé à 20, et pouvant être modifié via l'url. De ces publications il
  va extraire les titres ainsi que tous les co-auteurs disponibles.
  - Si une liste de titres a été fournie en entrée, l'algorithme va ensuite
    comparer les titres de ces publications avec la liste d'entrée. Si un titre
    de la liste d'entrée correspond à plus de 70% avec un titre de la liste des
    publications de la personne, l'algorithme s'arrète et renvoie l'orcid de
    cette personne.
  - Si une liste de co-auteurs a été fournie en entrée, l'algorithme va ensuite
    comparer les co-auteurs de ces publications avec la liste d'entrée. Si un
    co-auteur de la liste d'entrée correspond avec un co-auteur de la liste des
    publications de la personne, l'algorithme s'arrête et renvoie l'orcid de
    cette personne.
  - Enfin si aucune des étapes précédentes n'est validée, et si une liste
    d'affiliations a été fournie, l'algorithme va comparer la liste
    d'affiliations d'entrée avec les affiliations présentes et passées de la
    personne. Plus il y a d'affiliations en commun, plus la personne obtiendra
    un score élévé et sera susceptible d'être retenue à la fin.
  - Pour finir, des points sont également ajoutés au score si la personne a le
    même nom, le même prénom ou la même initiale que le prénom de la personne
    que l'on souhaite retrouver. Si au cour de cette boucle l'algorithme ne
    s'est pas arrété suite à un email, titre ou co-auteur, il renverra la
    personne ayant obtenu le plus gros score.

Pour les combinaisons de prénom/nom très communes dans certains pays (par
exemple John Smith, Yue Chen), il est conseillé d'augmenter le paramètre
`nameDepth`. Cependant cela risque également d'augmenter le temps de calcul.  
De plus l'algorithme renverra dans la majorité des cas un résultat, mais il est
possible que celui-ci soit incorrect si aucun des arguments d'entrée n'a aidé à
identifier la personne recherchée.

Remarque : On ne pourra pas trouver une personne à l'aide de titres, co-auteurs,
emails et affiliations si cette personne n'a pas rentré ces données dans son
compte orcid, par conséquent une personne étant sur orcid mais n'ayant mis
aucune information à disposition peut ne pas être trouvée.

## Exemple

```bash
$ cat <<EOF | curl -X POST --data-binary @- "http://orcid-disambiguation-2.tdmservices.intra.inist.fr/v1/orcidDisambiguation"
[{"id":"1","value":[{"firstName" : "Pascal", "lastName" : "Cuxac", "email" : ["blabla@blabla.fr","pascal.cuxac@inist.fr"]}]},
 {"id":"2","value":[{"firstName" : "Rubén", "lastName" : "Vázquez-Cárdenas", "coAuthors" : ["Juan pablo Martínez-Pastor"]}]}]
EOF
```

Sortie

```json
[{"id":"1","value":"0000-0002-6809-5654"},
 {"id":"2","value":"0000-0002-8416-869X"}]
EOF
```

Exemple d'url en modifiant les paramètres `nameDepth` et `worksDepth` :

<http://orcid-disambiguation-1.tdmservices.intra.inist.fr/v1/orcidDisambiguation?nameDepth=50&worksDepth=40>