Package: xmen
✖️MENxMEN is an extensible toolkit for Cross-lingual (x)MedicalEntityNormalization.
Through its compatibility with theBigBIO (BigScience Biomedical)framework, it can be used out-of-the box to run experiments with many open biomedical datasets. It can also be easily integrated with existing Named Entity Recognition (NER) pipelines.InstallationxMEN is available throughPyPi:pip install xmenDevelopmentWe usePoetryfor building, testing and dependency management (seepyproject.toml).🚀 Getting StartedA very simple pipeline highlighting the main components of xMEN can be found innotebooks/00_Getting_Started.ipynb🎓 ExamplesFor more advanced use cases, check out theexamplesfolder.📂 Data LoadingUsually, BigBIO-compatible datasets can just be loaded from the Hugging Face Hub:fromdatasetsimportload_datasetdataset=load_dataset("distemist","distemist_linking_bigbio_kb")Integration with NER ToolsTo use xMEN with existing NER pipelines, you can also create a dataset at runtime.spaCyfromxmen.dataimportfrom_spacydocs=...#  list of spaCy docs with entity spansdataset=from_spacy(docs)for an example, see:examples/02_spaCy_German.ipynbSpanMarkerfromspan_markerimportSpanMarkerModelsentences=...# list of sentencesmodel=SpanMarkerModel.from_pretrained(...)preds=model.predict(sentences)fromxmen.dataimportfrom_spansdataset=from_spans(preds,sentences)🔧 Configuration and CLIxMEN provides a convenient command line interface to prepare entity linking pipelines by creating target dictionaries and pre-computing indices to link to concepts in them.Runxmen helpto get an overview of the available commands.Configuration is done through.yamlfiles. For examples, see the/examples/conffolder.📕 Creating DictionariesRunxmen dictto create dictionaries to link against. Although the most common use case is to create subsets of the UMLS, it also supports passing custom parser scripts for non-UMLS dictionaries.Note: Creating UMLS subsets requires a local installation of theUMLS metathesaurus(not only MRCONSO.RRF). In the examples, we assume that the environment variable$UMLS_HOMEpoints to the installation path. You can either set this variable, or replace the path with your local installation.UMLS SubsetsExample configuration forMedmentions:name:medmentionsdict:umls:lang:-enmeta_path:${oc.env:UMLS_HOME}/2017AA/METAversion:2017AAsemantic_types:-T005-T007-T017-T022-T031-T033-T037-T038-T058-T062-T074-T082-T091-T092-T097-T098-T103-T168-T170-T201-T204sabs:-CPT-FMA-GO-HGNC-HPO-ICD10-ICD10CM-ICD9CM-MDR-MSH-MTH-NCBI-NCI-NDDF-NDFRT-OMIM-RXNORM-SNOMEDCT_USRunningxmen --dict examples/conf/medmentions.yamlcreates a.jsonlfile from the described UMLS subset.Using Custom DictionariesParsing scripts for custom dictionaries can be provided with the--codeoption (examples can be found in thedictsfolder).Example configuration forDisTEMIST:name:distemistdict:custom:lang:-esdistemist_path:local_files/dictionary_distemist.tsvRunningxmen dict examples/conf/distemist.yaml --code examples/dicts/distemist.pycreates a.jsonlfile from the custom DisTEMIST gazetteer (which you can download fromZenodoand put into any folder, e.g.,local_files).🔎 Candidate GenerationThexmen indexcommand is used to compute term indices from a dictionary created through thedictcommand.
If an index already exists, you will be prompted to overwrite the existing file (or pass--overwrite).xMEN provides implementations of different neural and non-neural candidate generatorsTF-IDF Weighted Character N-gramsBased on the implementation fromscispaCy.Runxmen index my_config.yaml --ngramorxmen index my_config.yaml --allto create the index.To use the linker at runtime, pass the index folder as an argument:fromxmen.linkersimportTFIDFNGramLinkerngram_linker=TFIDFNGramLinker(index_base_path="/path/to/my/index/ngram",k=100)predictions=ngram_linker.predict_batch(dataset)SapBERTDense Retrieval based onSapBERTembeddings.YAML file (optional, if you want to configure another Transformer model):linker:candidate_generation:sapbert:model_name:cambridgeltl/SapBERT-UMLS-2020AB-all-lang-from-XLMRRunxmen index my_config.yaml --sapbertorxmen index my_config.yaml --allto create theFAISSindex.To use the linker at runtime, pass the index folder as an argument. To make predictions on a batch of documents, you have to pass a batch size, as the SapBERT linker runs on the GPU by default:fromxmen.linkersimportSapBERTLinkersapbert_linker=SapBERTLinker(index_base_path="/path/to/my/index/sapbert",k=1000)predictions=sapbert_linker.predict_batch(dataset,batch_size=128)If you have loaded a yaml-config as a dictionary-like object, you may also just pass it as kwargs:sapbert_linker=SapBERTLinker(**config)By default, SapBERT assumes a CUDA device is available. If you want to disable cuda, passcuda=Falseto the constructor.EnsembleDifferent candidate generators often work well for different kinds of entity mentions, and it can be helpful to combine their predictions.In xMEN, this can be easily achieved with anEnsembleLinker:fromxmen.linkersimportEnsembleLinkerensemble_linker=EnsembleLinker()ensemble_linker.add_linker('sapbert',sapbert_linker,k=10)ensemble_linker.add_linker('ngram',ngram_linker,k=10)or (as a shortcut for the combination ofTFIDFNGramLinkerandSapBERTLinker):fromxmen.linkersimportdefault_ensembleensemble_linker=default_ensemble("/path/to/my/index/")You can callpredict_batchon theEnsembleLinkerjust as with any other linker.Sometimes, you want to compare the ensemble performance to individual linkers and already have the candidate lists. To avoid recomputation, you can use thereuse_predsargument:prediction=ensemble_linker.predict_batch(dataset,128,100,reuse_preds={'sapbert':predictions_sap,'ngram':predictions_ngram'})🌀 Entity RankersCross-encoder Re-rankerWhen labelled training data is available, a trainable re-ranker can improve ranking of candidate lists a lot.To train a cross-encoder model, first create a dataset of mention / candidate pairs:fromxmen.reranking.cross_encoderimportCrossEncoderReranker,CrossEncoderTrainingArgsfromxmenimportload_kb# Load a KB from a pre-computed dictionary (jsonl) to obtain synonyms for concept encodingkb=load_kb('path/to/my/dictionary.jsonl')# Obtain prediction from candidate generator (see above)candidates=linker.predict_batch(dataset)ce_dataset=CrossEncoderReranker.prepare_data(candidates,dataset,kb)Then you can use this dataset to train a supervised reranking model:# Number of epochs to trainn_epochs=10# Any BERT model, potentially language-specificcross_encoder_model='bert-base-multilingual-cased'args=CrossEncoderTrainingArgs(n_epochs,cross_encoder_model)rr=CrossEncoderReranker()# Fit the modelrr.fit(args,ce_dataset['train'].dataset,ce_dataset['validation'].dataset)# Predict on test setprediction=rr.rerank_batch(candidates['test'],ce_dataset['test'])Note on Memory UsageIn most examples and benchmarks, we use 64 candidates as a batch size for the cross-encoder, which usually fit into 48GB of GPU memory.
If you encounter memory issues, you can try reducing this number and/or using a smaller BERT model. See:Issue #22Pre-trained Cross-encodersWe provide pre-trained models, based on automatically translated versions of MedMentions (seenotebooks/01_Translation.ipynb).Instead of fitting the cross-encoder model, you can just load a pre-trained model, e.g., for French:rr=CrossEncoderReranker.load('phlobo/xmen-fr-ce-medmentions',device=0)Models are available on the Hugging Face Hub:https://huggingface.co/models?library=xmen💡 Pre- and Post-processingWe support various optional components for transforming input data and result sets inxmen.data:SamplingAbbrevation expansionFiltering by UMLS semantic groupsFiltering by UMLS semantic typesReplacement of retired CUIS📊 EvaluationxMEN provides implementations of common entity linking metrics (e.g., a wrapper forneleval) and utilities for error analysis.fromxmen.evaluationimportevaluate,error_analysis# Runs the evaluationeval_results=evaluate(ground_truth,predictions)# Performs error analysiserror_dataframe=error_analysis(ground_truth,predictions))CitationIf you use xMEN in your work, please cite the following paper:Florian Borchert, Ignacio Llorca, Roland Roller, Bert Arnrich, and Matthieu-P Schapranow.xMEN: A Modular Toolkit for Cross-Lingual Medical Entity Normalization.
arXiv preprint arXiv:2310.11275 (2023).http://arxiv.org/abs/2310.11275.BibTeX:@article{borchert2023xmen,title={{xMEN}: A Modular Toolkit for Cross-Lingual Medical Entity Normalization},author={Florian Borchert and Ignacio Llorca and Roland Roller and Bert Arnrich and Matthieu-P. Schapranow},year={2023},url={https://arxiv.org/abs/2310.11275},journal={arXiv preprint arXiv:2310.11275}}