medkit.text.context.family_detector

Classes

FamilyDetectorRule	Regexp-based rule to use with FamilyDetector.
FamilyMetadata	Metadata dict added to family attributes with True value.
FamilyDetector	Annotator for creating family attributes.

Module Contents

class medkit.text.context.family_detector.FamilyDetectorRule

Regexp-based rule to use with FamilyDetector.

Input text may be converted before detecting rule.

Parameters:

regexpstr

The regexp pattern used to match a family reference

exclusion_regexpslist of str, optional

Optional exclusion patterns

idstr, optional

Unique identifier of the rule to store in the metadata of the entities

case_sensitivebool, default=False

Whether to consider case when running regexp and `exclusion_regexs

unicode_sensitivebool, default=False

If True, rule matches are searched on unicode text. So, regexp and exclusion_regexps shall not contain non-ASCII chars because they would never be matched. If False, rule matches are searched on closest ASCII text when possible. (cf. FamilyDetector)

regexp: str

exclusion_regexps: list[str]

id: str | None = None

case_sensitive: bool = False

unicode_sensitive: bool = False

__post_init__()

class medkit.text.context.family_detector.FamilyMetadata

Bases: typing_extensions.TypedDict

Metadata dict added to family attributes with True value.

Parameters:

rule_idstr or int

Identifier of the rule used to detect a family reference. If the rule has no id, then the index of the rule in the list of rules is used instead.

rule_id: str | int

class medkit.text.context.family_detector.FamilyDetector(output_label: str, rules: list[FamilyDetectorRule] | None = None, uid: str | None = None)

Bases: medkit.core.text.ContextOperation

Annotator for creating family attributes.

Annotator creating family attributes with boolean values indicating if a family reference has been detected.

Because family attributes will be attached to whole annotations, each input annotation should be “local”-enough rather than a big chunk of text (ie a sentence or a syntagma).

For detecting family references, the module uses rules that may be sensitive to unicode or not. When the rule is not sensitive to unicode, we try to convert unicode chars to the closest ascii chars. However, some characters need to be pre-processed before (e.g., n° -> number). So, if the text lengths are different, we fall back on initial unicode text for detection even if rule is not unicode-sensitive. In this case, a warning is logged for recommending to pre-process data.

Note that for better results, family detection should be run at the sentence level (ie on sentence segments) rather than at the syntagma level [1].

Parameters:

output_labelstr

The label of the created attributes

ruleslist of FamilyDetectorRule, optional

The set of rules to use when detecting family references. If none provided, the rules in “family_detector_default_rules.yml” will be used

uidstr, optional

Identifier of the detector

References

[1] Garcelon, N., Neuraz, A., Benoit, V., Salomon, R., & Burgun, A. (2017).

Improving a full-text search engine: the importance of negation detection and family history context to identify cases in a biomedical data warehouse. Journal of the American Medical Informatics Association : JAMIA, 24(3), 607-613. https://doi.org/10.1093/jamia/ocw144

init_args

output_label

rules

_non_empty_text_pattern

_patterns

_exclusion_patterns

_has_non_unicode_sensitive_rule

run(segments: list[medkit.core.text.Segment])

Run the operation.

Add a family attribute to each segment with a boolean value indicating if a family reference has been detected.

Family attributes with a True value have a metadata dict with fields described in FamilyMetadata.

Parameters:

segmentslist of Segment

List of segments to detect as being family references or not

_detect_family_ref_in_segment(segment: medkit.core.text.Segment) → medkit.core.Attribute | None

_find_matching_rule(text: str) → str | int | None

static load_rules(path_to_rules: pathlib.Path, encoding: str | None = None) → list[FamilyDetectorRule]

Load all rules stored in a yml file.

Parameters:

path_to_rulesPath

Path to a yml file containing a list of mappings with the same structure as FamilyDetectorRule

encodingstr, optional

Encoding of the file to open

Returns:

list of FamilyDetectorRule

List of all the rules in path_to_rules, can be used to init a FamilyDetector

static check_rules_sanity(rules: list[FamilyDetectorRule])

Check consistency of a set of rules.

static save_rules(rules: list[FamilyDetectorRule], path_to_rules: pathlib.Path, encoding: str | None = None)

Store rules in a YAML file.

Parameters:

ruleslist of FamilyDetectorRule

The rules to save

path_to_rulesPath

Path to a .yml file that will contain the rules

encodingstr, optional

Encoding of the .yml file