diff --git a/orcid-disambiguation/README.md b/orcid-disambiguation/README.md index 1026be7..8e71e2c 100644 --- a/orcid-disambiguation/README.md +++ b/orcid-disambiguation/README.md @@ -6,33 +6,73 @@ - [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 suivant: -- '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és) de la personne que l'on souhaite trouver +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: -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 en extraire les titres ainsi que tout 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és de la personne. Plus il y a d'affiliation 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. +- `firstName` : Le prénom de la personne que l'on souhaite trouver +- `lastName` : Le nom de la personne que l'on souhaite trouver -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. +De plus, d'autres champs facultatifs (mais fortement recommandés d'utiliser pour +plus de précision) sont disponibles : -Remarque : On ne pourra pas trouver une personne à l'aide de titres, co-autheurs, 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. +- `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 -## Exemple +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 <