medkit.io.brat ============== .. py:module:: medkit.io.brat Classes ------- .. autoapisummary:: medkit.io.brat.BratInputConverter medkit.io.brat.BratOutputConverter Module Contents --------------- .. py:class:: BratInputConverter(detect_cuis_in_notes: bool = True, notes_label: str = 'brat_note', uid: str | None = None) Bases: :py:obj:`medkit.core.InputConverter` Class in charge of converting brat annotations. :Parameters: **detect_cuis_in_notes** : bool, default=True If `True`, strings looking like CUIs in annotator notes of entities will be converted to UMLS normalization attributes rather than creating an :class:`~.core.Attribute` with the whole note text as value. **notes_label** : str, default="brat_note", Label to use for attributes created from annotator notes. **uid** : str, optional Identifier of the converter. :Attributes: **description** : str Description of the operation .. !! processed by numpydoc !! .. py:property:: description :type: medkit.core.OperationDescription .. py:method:: set_prov_tracer(prov_tracer: medkit.core.ProvTracer) .. py:method:: load(dir_path: str | pathlib.Path, ann_ext: str = ANN_EXT, text_ext: str = TEXT_EXT) -> list[medkit.core.text.TextDocument] Load brat annotations as text documents. Create a list of TextDocuments from a folder containing text files and associated brat annotations files. :Parameters: **dir_path** : str or Path The path to the directory containing the text files and the annotation files (.ann) **ann_ext** : str, optional The extension of the brat annotation file (e.g. .ann) **text_ext** : str, optional The extension of the text file (e.g. .txt) :Returns: list of TextDocument The list of TextDocuments .. !! processed by numpydoc !! .. py:method:: load_doc(ann_path: str | pathlib.Path, text_path: str | pathlib.Path) -> medkit.core.text.TextDocument Load a brat annotation and text file combo as a text document. Create a TextDocument from a .ann file and its associated .txt file. :Parameters: **ann_path** : str or Path The path to the brat annotation file. **text_path** : str or Path The path to the text document file. :Returns: TextDocument The document containing the text and the annotations .. !! processed by numpydoc !! .. py:method:: load_annotations(ann_file: str | pathlib.Path) -> list[medkit.core.text.TextAnnotation] Load a brat annotation file as a list of annotations. Load a .ann file and return a list of :class:`~medkit.core.text.annotation.Annotation` objects. :Parameters: **ann_file** : str or Path Path to the .ann file. :Returns: list of TextAnnotation The list of text annotations .. !! processed by numpydoc !! .. py:class:: BratOutputConverter(anns_labels: list[str] | None = None, attrs: list[str] | None = None, notes_label: str = 'brat_note', ignore_segments: bool = True, convert_cuis_to_notes: bool = True, create_config: bool = True, top_values_by_attr: int = 50, uid: str | None = None) Bases: :py:obj:`medkit.core.OutputConverter` Class for converting text documents to a brat collection file. .. hint:: BRAT checks for coherence between span and text for each annotation. This converter adjusts the text and spans to get the right visualization and ensure compatibility. :Parameters: **anns_labels** : list of str, optional Labels of medkit annotations to convert into Brat annotations. If `None` (default) all the annotations will be converted **attrs** : list of str, optional Labels of medkit attributes to add in the annotations that will be included. If `None` (default) all medkit attributes found in the segments or relations will be converted to Brat attributes **notes_label** : str, default="brat_note" Label of attributes that will be converted to annotator notes. **ignore_segments** : bool, default=True If `True` medkit segments will be ignored. Only entities, attributes and relations will be converted to Brat annotations. If `False` the medkit segments will be converted to Brat annotations as well. **convert_cuis_to_notes** : bool, default=True If `True`, UMLS normalization attributes will be converted to annotator notes rather than attributes. For entities with multiple UMLS attributes, CUIs will be separated by spaces (ex: "C0011849 C0004096"). **create_config** : bool, default=True Whether to create a configuration file for the generated collection. This file defines the types of annotations generated, it is necessary for the correct visualization on Brat. **top_values_by_attr** : int, default=50 Defines the number of most common values by attribute to show in the configuration. This is useful when an attribute has a large number of values, only the 'top' ones will be in the config. By default, the top 50 of values by attr will be in the config. **uid** : str, optional Identifier of the converter :Attributes: **description** : str Description for the operation .. !! processed by numpydoc !! .. py:property:: description :type: medkit.core.OperationDescription .. py:method:: save(docs: list[medkit.core.text.TextDocument], dir_path: str | pathlib.Path, doc_names: list[str] | None = None) Save text documents as brat files. Convert and save a collection or list of TextDocuments into a Brat collection. For each collection or list of documents, a folder is created with '.txt' and '.ann' files. A file named 'annotation.conf' may also be saved if required. :Parameters: **docs** : list of TextDocument List of medkit doc objects to convert **dir_path** : str or Path String or path object to save the generated files **doc_names** : list of str, optional Optional list with the names for the generated files. If 'None', 'uid' will be used as the name. Where 'uid.txt' has the raw text of the document and 'uid.ann' the Brat annotation file. .. !! processed by numpydoc !! .. py:method:: _convert_medkit_anns_to_brat(segments: list[medkit.core.text.Segment], relations: list[medkit.core.text.Relation], config: medkit.io._brat_utils.BratAnnConfiguration, raw_text: str) -> list[medkit.io._brat_utils.BratEntity | medkit.io._brat_utils.BratAttribute | medkit.io._brat_utils.BratRelation | medkit.io._brat_utils.BratNote] Convert Segments, Relations and Attributes into brat data structures. :Parameters: **segments** : list of Segment Medkit segments to convert **relations** : list of Relation Medkit relations to convert **config** : BratAnnConfiguration Optional `BratAnnConfiguration` structure, this object is updated with the types of the generated Brat annotations. **raw_text** : str Text of reference to get the original text of the annotations :Returns: list of BratEntity or BratAttribute or BratRelation or BratNote A list of brat annotations .. !! processed by numpydoc !! .. py:method:: _ensure_text_and_spans(segment: medkit.core.text.Segment, raw_text: str) -> tuple[str, list[tuple[int, int]]] :staticmethod: Ensure consistency between the segment and the raw text. The text of a BRAT annotation can't contain multiple white spaces (including a newline character). This method cleans the fragments' text and adjust its spans to point to the same location in the raw text. :Parameters: **segment** : Segment Segment to ensure **raw_text** : str Text of reference :Returns: **text** : str The cleaned text **spans** : list of tuple The adjusted spans .. !! processed by numpydoc !! .. py:method:: _convert_segment_to_brat(segment: medkit.core.text.Segment, nb_segment: int, raw_text: str) -> medkit.io._brat_utils.BratEntity Get a brat entity from a medkit segment. :Parameters: **segment** : Segment A medkit segment to convert into brat format **nb_segment** : int The current counter of brat segments **raw_text** : str Text of reference to get the original text of the segment :Returns: BratEntity The equivalent brat entity of the medkit segment .. !! processed by numpydoc !! .. py:method:: _convert_relation_to_brat(relation: medkit.core.text.Relation, nb_relation: int, brat_entities_by_segment_id: dict[str, medkit.io._brat_utils.BratEntity]) -> tuple[medkit.io._brat_utils.BratRelation, medkit.io._brat_utils.RelationConf] :staticmethod: Get a brat relation from a medkit relation. :Parameters: **relation** : Relation A medkit relation to convert into brat format **nb_relation** : int The current counter of brat relations **brat_entities_by_segment_id** : dict of str to BratEntity A dict to map medkit ID to brat annotation :Returns: **relation** : BratRelation The equivalent brat relation of the medkit relation **config** : RelationConf Configuration of the brat attribute :Raises: ValueError When the source or target was not found in the mapping object .. !! processed by numpydoc !! .. py:method:: _convert_attribute_to_brat(label: str, value: str | None, nb_attribute: int, target_brat_id: str, is_from_entity: bool) -> tuple[medkit.io._brat_utils.BratAttribute, medkit.io._brat_utils.AttributeConf] :staticmethod: Get a brat attribute from a medkit attribute. :Parameters: **label** : str Attribute label to convert into brat format **value** : str, optional Attribute value **nb_attribute** : int The current counter of brat attributes **target_brat_id** : str Corresponding target brat ID :Returns: **attribute** : BratAttribute The equivalent brat attribute of the medkit attribute **config** : AttributeConf Configuration of the brat attribute .. !! processed by numpydoc !! .. py:method:: _convert_umls_attributes_to_brat_note(cuis: list[str], nb_note: int, target_brat_id: str) -> medkit.io._brat_utils.BratNote :staticmethod: Get a brat note from a medkit umls norm attribute. :Parameters: **cuis** : list of str CUI to convert to brat note **nb_note** : int The current counter of brat notes **target_brat_id** : str Corresponding target brat ID :Returns: BratNote The equivalent brat note of the medkit umls attribute .. !! processed by numpydoc !! .. py:method:: _convert_attributes_to_brat_note(values: list[Any], nb_note: int, target_brat_id: str) -> medkit.io._brat_utils.BratNote :staticmethod: Get a brat note from medkit attribute values. :Parameters: **values** : list of Any Attribute values **nb_note** : int The current counter of brat notes **target_brat_id** : str Corresponding target brat ID :Returns: BratNote The equivalent brat note of the medkit attribute values .. !! processed by numpydoc !!