pyprocessors-coreference 1.6.26__tar.gz → 1.6.29__tar.gz

{pyprocessors_coreference-1.6.26 → pyprocessors_coreference-1.6.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyprocessors-coreference
-Version: 1.6.26
+Version: 1.6.29
 Summary: Processor grouping the mentions of the same entity
 Project-URL: Homepage, https://bitbucket.org/kairntech/pyprocessors_coreference
 Author-email: Olivier Terrier <olivier.terrier@kairntech.com>
@@ -69,6 +69,12 @@ Pour chaque document, entre mentions de même famille de labels :
   groupes possibles pour que l'étape de linking tranche ;
 - **la règle du nom partiel ne vaut que pour les personnes** : « Airbus » ne rejoint pas
   « Airbus Defence and Space ».
+- **les formes d'un acronyme rejoignent l'entité trouvée sur l'une d'elles** : les
+  annotations de `pyannotators_acronyms` (forme courte et forme développée, liées par
+  leur term `short#long` du lexique `acronyms`) prennent le label le plus fréquent parmi
+  les entités de leurs spans exacts et entrent dans son groupe (« MS » rejoint
+  « multiple sclerosis »). Une forme déjà annotée n'est pas dupliquée ; un acronyme sans
+  entité disparaît de la sortie ([ADR-0002](docs/adr/0002-acronymes-mentions-de-l-entite.md)).
 
 Sur chaque annotation d'un label regroupé, il écrit dans `properties` :
 

{pyprocessors_coreference-1.6.26 → pyprocessors_coreference-1.6.29}/README.md

@@ -39,6 +39,12 @@ Pour chaque document, entre mentions de même famille de labels :
   groupes possibles pour que l'étape de linking tranche ;
 - **la règle du nom partiel ne vaut que pour les personnes** : « Airbus » ne rejoint pas
   « Airbus Defence and Space ».
+- **les formes d'un acronyme rejoignent l'entité trouvée sur l'une d'elles** : les
+  annotations de `pyannotators_acronyms` (forme courte et forme développée, liées par
+  leur term `short#long` du lexique `acronyms`) prennent le label le plus fréquent parmi
+  les entités de leurs spans exacts et entrent dans son groupe (« MS » rejoint
+  « multiple sclerosis »). Une forme déjà annotée n'est pas dupliquée ; un acronyme sans
+  entité disparaît de la sortie ([ADR-0002](docs/adr/0002-acronymes-mentions-de-l-entite.md)).
 
 Sur chaque annotation d'un label regroupé, il écrit dans `properties` :
 

pyprocessors_coreference-1.6.29/docs/adr/0002-acronymes-mentions-de-l-entite.md

@@ -0,0 +1,52 @@
+---
+status: proposed
+date: 2026-10-14
+---
+
+# ADR-0002 — Les formes d'un acronyme deviennent des mentions de l'entité trouvée sur l'une d'elles
+
+- **Décision** — Quand `pyannotators_acronyms` a annoté les formes courtes et développées des acronymes d'un document, le processeur les rattache à la vraie entité (NER) trouvée sur l'une d'elles : elles prennent son label, entrent dans son groupe, et les acronymes sans entité disparaissent de la sortie.
+- **Pourquoi** — Le NER biomédical rate une bonne partie des formes courtes. Dans l'article de la fixture (`quantigraph_ot-document-s10571-026-01785-9_reference.pdf.json`), il annote 6 « MS » sur 27, 35 « BBB » sur 58. L'acronyme dit que « MS » est « multiple sclerosis » partout dans le document : c'est un regroupement de mentions, l'étape que porte ce dépôt ([ADR-0001](0001-linking-candidats-entityfishing-decision-jev.md)).
+- **Statut** — `proposed`.
+
+## Le contexte
+
+`pyannotators_acronyms` (`AcronymsAnnotator`, ou `AcronymsListProcessor` avec `drop_annotations=False`) annote :
+- la forme développée et la forme courte d'une définition (« multiple sclerosis (MS) ») ;
+- avec `propagate`, chaque forme courte qui suit sa définition.
+
+Le lien entre les formes est leur term `{identifier: "MS#multiple sclerosis", lexicon: "acronyms"}`. Une forme courte propagée porte un term par forme développée connue : les variantes d'écriture d'une même forme développée (« blood-brain barrier », « blood brain barrier ») en font plusieurs.
+
+L'export Sherpa (*download document*) perd les `terms` des annotations ; le processeur, lui, les reçoit. La fixture, elle, les contient.
+
+Sur les 45 acronymes de l'article :
+
+| Cas | Nb | Exemples |
+|---|---|---|
+| entité sur la forme courte et la développée | 17 | AD, BBB, CNS, MS |
+| entité sur la forme courte seulement | 6 | ACE2, TREM2, HSV-1 |
+| entité sur la forme développée seulement | 2 | UPR, BCB |
+| aucune entité | 19 | AI, KG, GWAS, instituts (LIH, ICREA) |
+| labels en conflit | 1 | PD : `diseases_and_syndromes` et `comorbidities` |
+
+## Les règles
+
+1. **Une annotation d'acronyme se reconnaît à son term du lexique `acronyms`**, pas à son label : `short_label` et `long_label` sont libres. Pas de nouveau paramètre.
+2. **Un acronyme est sa forme courte**, prise dans l'identifiant du term (`MS#…` → `MS`) : toutes les formes qui la partagent sont une seule entité, quelles que soient les écritures de la forme développée.
+3. **Le label est celui des entités trouvées sur l'empan exact de ses formes, le plus fréquent.** Le vote tranche les labels en conflit (PD → `diseases_and_syndromes`).
+4. **Une forme dont l'empan porte déjà une entité est supprimée** : c'est un doublon. L'entité garde son label, même minoritaire.
+5. **Les autres formes prennent le label** (`labelName` et `label`) et perdent leur term `acronyms` : c'est un signal d'entrée, consommé ici.
+6. **Les formes et les entités au label retenu forment un seul groupe** : « MS » et « multiple sclerosis » ont le même `entity_group`, et la forme développée, plus longue, devient `canonical_form`.
+7. **Un acronyme sans entité disparaît de la sortie** : ses formes ne sont pas des entités du projet, et des groupes `short` / `long` n'ont rien à faire au linking.
+
+## Les limites connues
+
+- **Empan exact seulement** : une entité qui déborde ou coupe la forme développée ne compte pas. Une règle d'inclusion viendra si ces ratés se voient dans les données.
+- **Une forme courte à deux sens dans un même document** (MS pour *multiple sclerosis* et *mass spectrometry*) fait une seule entité. Marqué `ponytail:` dans le code.
+- **Les incohérences du NER restent** : il annote aussi « BBB » en `diseases_and_syndromes` ; ces annotations gardent leur label et leur propre groupe, à côté du groupe `tissues` des formes de l'acronyme.
+
+## Les options écartées
+
+- **Garder les acronymes sans entité** : ils remonteraient au linking sous des labels `short` / `long` sans base de connaissances.
+- **Lire le lien dans l'altText `acronyms`** de `AcronymsListProcessor` : présent dans l'export, mais c'est une dépendance de plus, sur un format texte, quand les terms sont la sortie native de l'annotateur.
+- **Un acronyme par identifiant `court#long`** : les variantes d'écriture de la forme développée scindaient l'acronyme, et une forme courte propagée avec deux terms ne pouvait être rangée nulle part.

{pyprocessors_coreference-1.6.26 → pyprocessors_coreference-1.6.29}/docs/sherpa/coreference.en.md

@@ -18,6 +18,7 @@ Groups the mentions of the same entity in a document: "Emmanuel Macron", "M. Mac
 | Prerequisite | Required | Why |
 |---|---|---|
 | Entity annotations | **Yes** | The processor only groups existing annotations. A document without annotation is returned as is. |
+| Acronyms annotator (`acronyms`), or Acronyms list processor (`acronyms_list`) with **Drop Annotations** off | No | Its short and expanded forms become mentions of the entity found on one of them. Placed before this processor. |
 
 <!-- generated:languages -->
 
@@ -29,7 +30,7 @@ Name comparison does not depend on the language, but the default **Honorifics**
 
 ## What it produces
 
-The processor neither creates nor removes annotations. It adds **properties** to each annotation it groups:
+The processor creates no annotation, and only removes acronym annotations (see **How it works**). It adds **properties** to each annotation it groups:
 
 | Property | Content | Example |
 |---|---|---|
@@ -61,6 +62,10 @@ Two mentions go in the same group in the following cases:
 1. **Same form and same label family.** The comparison ignores case and apostrophe variants: "Airbus" and "AIRBUS" are grouped. A label whose name ends with another grouped label is of its family: a "Washington" annotated `location` by a model and `afplocation` by a lexicon forms a single group, as do `organization` and `afporganization`.
 2. **Same family of persons.** All person labels count as one, whatever their name: a "George Lucas" annotated `person` by a model and `afpperson` by a lexicon forms a single group.
 3. **Partial name, for persons only.** A name that ends a longer name joins this name, whether it appears before or after it in the document: "Macron" and "M. Macron" join "Emmanuel Macron". The **Honorifics** titles are ignored for the comparison.
+4. **Forms of one acronym.** When the Acronyms annotator ran before, the short form ("SEP") and the expanded form ("sclérose en plaques") of an acronym join the entity found exactly on one of them, everywhere in the document:
+   - they take its label, the most frequent one if the entities of their forms have several;
+   - a form already annotated by an entity is not duplicated: the acronym annotation is removed;
+   - an acronym without any entity on its forms is gone from the output, short and expanded annotations included.
 
 Are **never** grouped:
 
@@ -223,6 +228,39 @@ Output annotations:
 
 <!-- /generated:example:labels -->
 
+### 6. The forms of an acronym
+
+Only the first "SEP" is a `maladie` entity: on input it carries two annotations, the entity and the short form of the acronym. The expanded form and the second "SEP" join it; the acronym "AP", without entity, is gone:
+
+<!-- generated:example:acronyms -->
+
+Text (French):
+
+> La sclérose en plaques (SEP) touche le cerveau. La SEP est chronique. L'apprentissage profond (AP) aide le diagnostic.
+
+Input annotations:
+
+| Annotated text | Label | Preferred form | Score |
+|---|---|---|---|
+| sclérose en plaques | `long` | sclérose en plaques | 1.00 |
+| SEP *(#1)* | `maladie` | — | 1.00 |
+| SEP *(#1)* | `short` | sclérose en plaques | 1.00 |
+| SEP *(#2)* | `short` | sclérose en plaques | 1.00 |
+| apprentissage profond | `long` | apprentissage profond | 1.00 |
+| AP | `short` | apprentissage profond | 1.00 |
+
+Default parameters.
+
+Output annotations:
+
+| Annotated text | Label | Score | Properties |
+|---|---|---|---|
+| sclérose en plaques | `maladie` | 1.00 | `canonical_form`: sclérose en plaques<br>`entity_group`: g1<br>`family`: maladie<br>`mention_type`: name |
+| SEP *(#1)* | `maladie` | 1.00 | `canonical_form`: sclérose en plaques<br>`entity_group`: g1<br>`family`: maladie<br>`mention_type`: name |
+| SEP *(#2)* | `maladie` | 1.00 | `canonical_form`: sclérose en plaques<br>`entity_group`: g1<br>`family`: maladie<br>`mention_type`: name |
+
+<!-- /generated:example:acronyms -->
+
 ## Known limitations
 
 - **A `PER` label is not recognized as a person by default.** Only the labels whose name ends with "person" are. With `PER` annotations, "Macron" does not join "Emmanuel Macron" as long as **Label Families** does not map `PER` to `person`. Once declared, it groups them:
@@ -255,3 +293,6 @@ Output annotations:
 - **A title missing from the list is part of the name.** "Général Martin" is not reduced to "Martin"; it is grouped with "Martin" by the partial-name rule, but the canonical form of the group then becomes "Général Martin".
 - **A label belongs to one family only.** Declared with `organization`, a `loc_org` never joins a `location` of the same form.
 - **Mentions of labels excluded by Labels receive nothing**, not even a group of their own.
+- **An acronym form only joins an entity at exactly the same position.** If the entity covers "la sclérose en plaques" and the acronym "sclérose en plaques", the acronym does not find it.
+- **An acronym is identified by its short form.** One short form standing for two things in a document ("MS" for *multiple sclerosis* and *mass spectrometry*) makes a single entity.
+- **Contradicting labels of the entity annotator stay.** An entity on an acronym form keeps its label, even when it is not the one chosen for the acronym: it then forms its own group.

{pyprocessors_coreference-1.6.26 → pyprocessors_coreference-1.6.29}/docs/sherpa/coreference.fr.md

@@ -18,6 +18,7 @@ Regroupe les mentions d'une même entité dans un document : « Emmanuel Macron
 | Prérequis | Obligatoire | Pourquoi |
 |---|---|---|
 | Annotations d'entités | **Oui** | Le processeur ne regroupe que des annotations existantes. Un document sans annotation est rendu tel quel. |
+| Annotateur Acronymes (`acronyms`), ou processeur Liste des acronymes (`acronyms_list`) avec **Drop Annotations** désactivé | Non | Ses formes courtes et développées deviennent des mentions de l'entité trouvée sur l'une d'elles. Placé avant ce processeur. |
 
 <!-- generated:languages -->
 
@@ -29,7 +30,7 @@ La comparaison des noms ne dépend pas de la langue, mais la liste par défaut d
 
 ## Ce qu'il produit
 
-Le processeur ne crée ni ne supprime d'annotation. Il ajoute des **propriétés** à chaque annotation qu'il regroupe :
+Le processeur ne crée aucune annotation, et ne retire que des annotations d'acronymes (voir **Fonctionnement**). Il ajoute des **propriétés** à chaque annotation qu'il regroupe :
 
 | Propriété | Contenu | Exemple |
 |---|---|---|
@@ -61,6 +62,10 @@ Deux mentions vont dans le même groupe dans les cas suivants :
 1. **Même forme et même famille de labels.** La comparaison ignore les majuscules et les variantes d'apostrophe : « Airbus » et « AIRBUS » sont regroupés. Un label dont le nom finit par un autre label regroupé est de sa famille : un « Washington » annoté `location` par un modèle et `afplocation` par un lexique forme un seul groupe, comme `organization` et `afporganization`.
 2. **Même famille de personnes.** Tous les labels de personnes comptent comme un seul, quel que soit leur nom : un « George Lucas » annoté `person` par un modèle et `afpperson` par un lexique forme un seul groupe.
 3. **Nom partiel, pour les personnes seulement.** Un nom qui termine un nom plus long rejoint ce nom, qu'il apparaisse avant ou après lui dans le document : « Macron » et « M. Macron » rejoignent « Emmanuel Macron ». Les civilités de **Honorifics** sont ignorées pour comparer.
+4. **Formes d'un même acronyme.** Quand l'annotateur Acronymes est passé avant, la forme courte (« SEP ») et la forme développée (« sclérose en plaques ») d'un acronyme rejoignent l'entité trouvée exactement sur l'une d'elles, partout dans le document :
+   - elles prennent son label, le plus fréquent si les entités de leurs formes en ont plusieurs ;
+   - une forme déjà annotée par une entité n'est pas dupliquée : l'annotation de l'acronyme est retirée ;
+   - un acronyme sans aucune entité sur ses formes disparaît de la sortie, ses annotations courtes et développées comprises.
 
 Ne sont **jamais** regroupés :
 
@@ -223,6 +228,39 @@ Annotations en sortie :
 
 <!-- /generated:example:labels -->
 
+### 6. Les formes d'un acronyme
+
+Seule la première « SEP » est une entité `maladie` : elle porte en entrée deux annotations, l'entité et la forme courte de l'acronyme. La forme développée et la seconde « SEP » la rejoignent ; l'acronyme « AP », sans entité, disparaît :
+
+<!-- generated:example:acronyms -->
+
+Texte (français) :
+
+> La sclérose en plaques (SEP) touche le cerveau. La SEP est chronique. L'apprentissage profond (AP) aide le diagnostic.
+
+Annotations en entrée :
+
+| Texte annoté | Label | Forme préférée | Score |
+|---|---|---|---|
+| sclérose en plaques | `long` | sclérose en plaques | 1,00 |
+| SEP *(n°1)* | `maladie` | — | 1,00 |
+| SEP *(n°1)* | `short` | sclérose en plaques | 1,00 |
+| SEP *(n°2)* | `short` | sclérose en plaques | 1,00 |
+| apprentissage profond | `long` | apprentissage profond | 1,00 |
+| AP | `short` | apprentissage profond | 1,00 |
+
+Paramètres par défaut.
+
+Annotations en sortie :
+
+| Texte annoté | Label | Score | Propriétés |
+|---|---|---|---|
+| sclérose en plaques | `maladie` | 1,00 | `canonical_form` : sclérose en plaques<br>`entity_group` : g1<br>`family` : maladie<br>`mention_type` : name |
+| SEP *(n°1)* | `maladie` | 1,00 | `canonical_form` : sclérose en plaques<br>`entity_group` : g1<br>`family` : maladie<br>`mention_type` : name |
+| SEP *(n°2)* | `maladie` | 1,00 | `canonical_form` : sclérose en plaques<br>`entity_group` : g1<br>`family` : maladie<br>`mention_type` : name |
+
+<!-- /generated:example:acronyms -->
+
 ## Limites à connaître
 
 - **Un label `PER` n'est pas reconnu comme personne par défaut.** Seuls les labels dont le nom finit par « person » le sont. Avec des annotations `PER`, « Macron » ne rejoint pas « Emmanuel Macron » tant que **Label Families** n'associe pas `PER` à `person`. Déclaré, il les regroupe :
@@ -255,3 +293,6 @@ Annotations en sortie :
 - **Une civilité absente de la liste fait partie du nom.** « Général Martin » ne se réduit pas à « Martin » ; il est regroupé avec « Martin » par la règle du nom partiel, mais la forme canonique du groupe devient alors « Général Martin ».
 - **Un label n'appartient qu'à une famille.** Déclaré avec `organization`, un `loc_org` ne rejoint plus jamais un `location` de même forme.
 - **Les mentions des labels exclus par Labels ne reçoivent rien**, pas même un groupe à elles seules.
+- **Une forme d'acronyme ne rejoint qu'une entité de même position exacte.** Si l'entité couvre « la sclérose en plaques » et l'acronyme « sclérose en plaques », l'acronyme ne la trouve pas.
+- **Un acronyme est identifié par sa forme courte.** Une même forme courte qui désigne deux choses dans un document (« MS » pour *multiple sclerosis* et *mass spectrometry*) ne fait qu'une entité.
+- **Les étiquettes contradictoires de l'annotateur d'entités restent.** Une entité posée sur une forme d'acronyme garde son label, même s'il n'est pas celui retenu pour l'acronyme : elle forme alors son propre groupe.

{pyprocessors_coreference-1.6.26 → pyprocessors_coreference-1.6.29}/src/pyprocessors_coreference/__init__.py

@@ -1,3 +1,3 @@
 """Processor grouping the mentions of the same entity"""
 
-__version__ = "1.6.26"
+__version__ = "1.6.29"

{pyprocessors_coreference-1.6.26 → pyprocessors_coreference-1.6.29}/src/pyprocessors_coreference/coreference.py

@@ -1,6 +1,6 @@
 import re
 import unicodedata
-from collections import defaultdict
+from collections import Counter, defaultdict
 from typing import cast
 
 from pydantic import BaseModel, Field
@@ -21,6 +21,10 @@ FAMILY = "family"
 # Only on an ambiguous partial name: the groups it may belong to.
 ENTITY_GROUP_CANDIDATES = "entity_group_candidates"
 
+# Lexicon of the terms pyannotators_acronyms writes on the short and expanded forms of
+# an acronym, identified by "short#long": the link between them.
+ACRONYMS = "acronyms"
+
 # Labels of one family are compared as one: the NER's "location" and the AFP
 # lexicon's "afplocation" annotate the same span, and must land in the same group.
 # All person labels form one family, whatever their name.
@@ -77,7 +81,10 @@ class CoreferenceProcessor(ProcessorBase):
     - a first name alone never joins ("Emmanuel" stays on its own);
     - an ambiguous partial name ("Macron" with both Emmanuel and Brigitte Macron)
       keeps a group of its own, and lists the possible groups in
-      `entity_group_candidates` for the linking step to decide.
+      `entity_group_candidates` for the linking step to decide;
+    - acronyms (pyannotators_acronyms, linked by their term in the lexicon "acronyms"):
+      the short and expanded forms of an acronym join the entity found on any of them,
+      and take its label. A form without entity is dropped.
     """
 
     def process(self, documents: list[Document], parameters: ProcessorParameters) -> list[Document]:
@@ -94,6 +101,7 @@ class CoreferenceProcessor(ProcessorBase):
 
 def group_document(document: Document, params: CoreferenceParameters, honorifics: set[str]) -> None:
     text = document.text or ""
+    links = resolve_acronyms(document)
     mentions = [a for a in (document.annotations or []) if a.labelName and (not params.labels or a.labelName in params.labels)]
     if not mentions:
         return
@@ -101,11 +109,13 @@ def group_document(document: Document, params: CoreferenceParameters, honorifics
     # 1. Same label family, same normalized surface: one surface group.
     families = label_families({a.labelName for a in mentions}, params)
     surfaces: dict[tuple[str, tuple[str, ...]], list[Annotation]] = defaultdict(list)
+    surface_key: dict[int, tuple[str, tuple[str, ...]]] = {}
     for a in sorted(mentions, key=lambda a: (a.start, a.end)):
         family = families[a.labelName]
         tokens = name_tokens(surface_of(a, text), honorifics if family == PERSON_FAMILY else set())
         if tokens:
             surfaces[(family, tokens)].append(a)
+            surface_key[id(a)] = (family, tokens)
 
     # 2. Person labels: a surface that is a proper suffix of longer surfaces joins
     # them when they are all one entity. Longest first, so that "Emmanuel Macron" has
@@ -118,6 +128,12 @@ def group_document(document: Document, params: CoreferenceParameters, honorifics
             key = parent[key]
         return key
 
+    # The short and expanded forms of one acronym are one entity ("AD", "Alzheimer's disease").
+    for link in links:
+        keys = [root(surface_key[id(a)]) for a in link if id(a) in surface_key]
+        for key in keys[1:]:
+            parent[root(key)] = root(keys[0])
+
     ambiguous: dict[tuple, set] = {}
     for key in sorted(surfaces, key=lambda k: -len(k[1])):
         family, tokens = key
@@ -153,6 +169,48 @@ def group_document(document: Document, params: CoreferenceParameters, honorifics
             a.properties = properties
 
 
+def resolve_acronyms(document: Document) -> list[list[Annotation]]:
+    """The forms of an acronym (the annotations whose term in the lexicon "acronyms" has its short form)
+    take the label most found among the entities of exactly their spans. A form whose span
+    already has an entity is dropped as a duplicate, the others take the label and lose
+    their acronym term; an acronym without entity is dropped. Returns, per acronym, the
+    mentions to group together."""
+    entities: dict[tuple[int, int], list[Annotation]] = defaultdict(list)
+    acronyms: dict[str, list[Annotation]] = defaultdict(list)
+    dropped: set[int] = set()
+    for a in document.annotations or []:
+        # The acronym is its short form: its expansions vary in spelling ("blood-brain
+        # barrier", "blood brain barrier"), and a propagated short form lists them all.
+        # ponytail: a short form with two meanings in one document (MS) makes one entity.
+        shorts = {t.identifier.split("#", 1)[0] for t in a.terms or [] if t.lexicon == ACRONYMS}
+        if not shorts:
+            if a.labelName:
+                entities[(a.start, a.end)].append(a)
+            continue
+        dropped.add(id(a))
+        acronyms[min(shorts)].append(a)
+    if not dropped:
+        return []
+
+    links = []
+    for forms in acronyms.values():
+        found = [e for f in forms for e in entities.get((f.start, f.end), [])]
+        if not found:
+            continue
+        label = Counter(e.labelName for e in found).most_common(1)[0][0]
+        model = next(e for e in found if e.labelName == label)
+        link = [e for e in found if e.labelName == label]
+        for f in forms:
+            if (f.start, f.end) not in entities:
+                f.labelName, f.label = label, model.label
+                f.terms = [t for t in f.terms or [] if t.lexicon != ACRONYMS] or None
+                dropped.discard(id(f))
+                link.append(f)
+        links.append(link)
+    document.annotations = [a for a in document.annotations or [] if id(a) not in dropped]
+    return links
+
+
 def label_families(labels: set[str], params: CoreferenceParameters) -> dict[str, str]:
     """Label → family, ignoring case: its value for a label declared in `label_families`
     (a value is its own family, so that "organization" joins the labels mapped to it),