medkit.text.ner.umls_matcher#

Classes:

UMLSMatcher(umls_dir, cache_dir, language[, ...])

Entity annotator identifying UMLS concepts using the simstring fuzzy matching algorithm (http://chokkan.org/software/simstring/).
class UMLSMatcher(umls_dir, cache_dir, language, threshold=0.9, min_length=3, max_length=50, similarity='jaccard', lowercase=True, normalize_unicode=False, spacy_tokenization=False, semgroups=('ANAT', 'CHEM', 'DEVI', 'DISO', 'PHYS', 'PROC'), blacklist=None, same_beginning=False, output_labels_by_semgroup=None, attrs_to_copy=None, name=None, uid=None)[source]#

Entity annotator identifying UMLS concepts using the simstring fuzzy matching algorithm (http://chokkan.org/software/simstring/).

This operation is heavily inspired by the QuickUMLS library (https://github.com/Georgetown-IR-Lab/QuickUMLS).

By default, only terms belonging to the ANAT (anatomy), CHEM (Chemicals & Drugs), DEVI (Devices), DISO (Disorders), PHYS (Physiology) and PROC (Procedures) semgroups will be considered. This behavior can be changed with the semgroups parameter.

Note that setting spacy_tokenization_language to True might reduce the number of false positives. This requires the spacy optional dependency, which can be installed with pip install medkit-lib[spacy].

Parameters

  • umls_dir (Union[str, Path]) – Path to the UMLS directory containing the MRCONSO.RRF and MRSTY.RRF files.

  • cache_dir (Union[str, Path]) – Path to the directory into which the umls database will be cached. If it doesn’t exist yet, the database will be automatically generated (it can take a long time) and stored there, ready to be reused on further instantiations. If it already exists, a check will be done to make sure the params used when the database was generated are consistent with the params of the current instance. If you want to rebuild the database with new params using the same cache dir, you will have to manually delete it first.

  • language (str) – Language to consider as found in the MRCONSO.RRF file. Example: “FRE”. Will trigger a regeneration of the database if changed.

  • min_length (int) – Minimum number of chars in matched entities.

  • max_length (int) – Maximum number of chars in matched entities.

  • threshold (float) – Minimum similarity threshold (between 0.0 and 1.0) between a UMLS term and the text of a matched entity.

  • similarity (Literal['cosine', 'dice', 'jaccard', 'overlap']) – Similarity metric to use.

  • same_beginning (bool) – Ignore all matches that start with a different character than the term of the rule. This can be convenient to get rid of false positives on words that are very similar but have opposite meanings because of a preposition, for instance “activation” and “inactivation”.

  • lowercase (bool) – Whether to use lowercased versions of UMLS terms and input entities (except for acronyms for which the uppercase term is always used). Will trigger a regeneration of the database if changed.

  • normalize_unicode (bool) – Whether to use ASCII-only versions of UMLS terms and input entities (non-ASCII chars replaced by closest ASCII chars). Will trigger a regeneration of the database if changed.

  • spacy_tokenization (bool) – If True, spacy will be used to tokenize input segments and filter out some tokens based on their part-of-speech tags, such as determinants, conjunctions and prepositions. If None, a simple regexp based tokenization will be used, which is faster but might give more false positives.

  • semgroups (Optional[Sequence[str]]) – Ids of UMLS semantic groups that matched concepts should belong to. cf https://lhncbc.nlm.nih.gov/semanticnetwork/download/sg_archive/SemGroups-v04.txt The default value is [“ANAT”,”CHEM”, “DEVI”, “DISO”, “PHYS”,”PROC”]. If set to None, all concepts can be matched. Will trigger a regeneration of the database if changed.

  • blacklist (Optional[List[str]]) – Optional list of exact terms to ignore.

  • output_labels_by_semgroup (Union[str, Dict[str, str], None]) – By default, ~`medkit.text.ner.umls.SEMGROUP_LABELS` will be used as entity labels. Use this parameter to override them. Example: {“DISO”: “problem”, “PROC”: “test}. If output_labels_by_semgroup is a string, all entities will use this string as label instead. Will trigger a regeneration of the database if changed.

  • attrs_to_copy (Optional[List[str]]) – Labels of the attributes that should be copied from the source segment to the created entity. Useful for propagating context attributes (negation, antecedent, etc)

  • name (Optional[str]) – Name describing the matcher (defaults to the class name).

  • uid (str) – Identifier of the matcher.

Attributes:

description

Contains all the operation init parameters.

Methods:

run(segments)

Return entities (with optional normalization attributes) matched in segments

set_prov_tracer(prov_tracer)

Enable provenance tracing.
property description: medkit.core.operation_desc.OperationDescription#

Contains all the operation init parameters.

Return type

OperationDescription

run(segments)#

Return entities (with optional normalization attributes) matched in segments

Parameters

segments (List[Segment]) – List of segments into which to look for matches

Return type

List[Entity]

Returns

entities (List[Entity]:) – Entities found in segments (with optional normalization attributes)

set_prov_tracer(prov_tracer)#

Enable provenance tracing.

Parameters

prov_tracer (ProvTracer) – The provenance tracer used to trace the provenance.