Skip to content

Reference

Annotation

Class that holds a single annotation entry.

Annotation entries are of the type "term[modifier1,modifier2]".

Source code in src/annotations/annotations.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
class Annotation:
    """Class that holds a single annotation entry.

    Annotation entries are of the type "term[modifier1,modifier2]".
    """
    term: str
    modifiers: "frozenset[str]"

    def __init__(self, annotation_string: str | None):
        """Create an annotation entry object.

        Args:
            annotation_string: An annotation string of the form
                "term[modifier1,modifier2]".
        """
        if annotation_string is None:
            self.term = None
            self.modifiers = frozenset()
        else:
            m = ANNOT_STRING_RE.match(annotation_string)
            if not m:
                raise ValueError(
                    f"Not a valid annotation string: '{annotation_string}'.")

            self.term = str(m['term'])
            if m['modifiers'] is None:
                self.modifiers = frozenset()
            else:
                self.modifiers = frozenset(sorted(m['modifiers'].split(',')))

    def __repr__(self):
        r = f"{self.term}"
        if self.modifiers:
            r += f"[{','.join(sorted(self.modifiers))}]"
        return r

    def __eq__(self, other: str | "Annotation"):
        if isinstance(other, str):
            return self == Annotation(other)
        return (
            (self.term == other.term) and
            (self.modifiers == other.modifiers)
        )

    def _match_term(self, term: str):
        return self.term == term

    def match(
        self,
        term: str,
        require_modifiers: set[str] | None,
        exclude_modifiers: set[str] | None,
        *args, **kwargs,
    ):
        """Returns whether this annotation matches the given term. Optionally
        allows specifying modifiers that need to be present or cannot be
        present for a positive match.

        Args:
            term: Annotation term to match.
            require_modifiers: Set of modifiers that need to be present for a
                positive match. No required modifiers assumed if `None`.
            exclude_modifiers: Set of modifiers that lead to a negative match
                if any of them are present.
        """
        if not self._match_term(term, *args, **kwargs):
            return False

        if require_modifiers is None:
            require_modifiers = self.modifiers
        else:
            require_modifiers = set(require_modifiers)
        if exclude_modifiers is None:
            exclude_modifiers = set()
        else:
            exclude_modifiers = set(exclude_modifiers)

        if (
            (
                require_modifiers and
                self.modifiers.isdisjoint(require_modifiers)
            ) or
            not self.modifiers.isdisjoint(exclude_modifiers)
        ):
            return False
        return True

    def strip_modifiers(self, modifiers: set[str] | None = None):
        """Returns a new `Annotation` with the given modifiers removed (if
        present), or all modifiers removed if `modifiers` is None.

        Args:
            modifiers: Set of modifiers to be removed, or `None` if all should
                be removed.
        """
        new_annotation = self.__class__(None)
        new_annotation.term = self.term
        if modifiers is None:
            new_annotation.modifiers = frozenset()
        else:
            new_annotation.modifiers = self.modifiers - modifiers
        return new_annotation

    def __hash__(self):
        return hash((self.term, self.modifiers))

__init__(annotation_string)

Create an annotation entry object.

Parameters:

Name Type Description Default
annotation_string str | None

An annotation string of the form "term[modifier1,modifier2]".

 required
Source code in src/annotations/annotations.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(self, annotation_string: str | None):
    """Create an annotation entry object.

    Args:
        annotation_string: An annotation string of the form
            "term[modifier1,modifier2]".
    """
    if annotation_string is None:
        self.term = None
        self.modifiers = frozenset()
    else:
        m = ANNOT_STRING_RE.match(annotation_string)
        if not m:
            raise ValueError(
                f"Not a valid annotation string: '{annotation_string}'.")

        self.term = str(m['term'])
        if m['modifiers'] is None:
            self.modifiers = frozenset()
        else:
            self.modifiers = frozenset(sorted(m['modifiers'].split(',')))

match(term, require_modifiers, exclude_modifiers, *args, **kwargs)

Returns whether this annotation matches the given term. Optionally allows specifying modifiers that need to be present or cannot be present for a positive match.

Parameters:

Name Type Description Default
term str

Annotation term to match.

 required
require_modifiers set[str] | None

Set of modifiers that need to be present for a positive match. No required modifiers assumed if None.

 required
exclude_modifiers set[str] | None

Set of modifiers that lead to a negative match if any of them are present.

 required
Source code in src/annotations/annotations.py 
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def match(
    self,
    term: str,
    require_modifiers: set[str] | None,
    exclude_modifiers: set[str] | None,
    *args, **kwargs,
):
    """Returns whether this annotation matches the given term. Optionally
    allows specifying modifiers that need to be present or cannot be
    present for a positive match.

    Args:
        term: Annotation term to match.
        require_modifiers: Set of modifiers that need to be present for a
            positive match. No required modifiers assumed if `None`.
        exclude_modifiers: Set of modifiers that lead to a negative match
            if any of them are present.
    """
    if not self._match_term(term, *args, **kwargs):
        return False

    if require_modifiers is None:
        require_modifiers = self.modifiers
    else:
        require_modifiers = set(require_modifiers)
    if exclude_modifiers is None:
        exclude_modifiers = set()
    else:
        exclude_modifiers = set(exclude_modifiers)

    if (
        (
            require_modifiers and
            self.modifiers.isdisjoint(require_modifiers)
        ) or
        not self.modifiers.isdisjoint(exclude_modifiers)
    ):
        return False
    return True

strip_modifiers(modifiers=None)

Returns a new Annotation with the given modifiers removed (if present), or all modifiers removed if modifiers is None.

Parameters:

Name Type Description Default
modifiers set[str] | None

Set of modifiers to be removed, or None if all should be removed.

 None
Source code in src/annotations/annotations.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def strip_modifiers(self, modifiers: set[str] | None = None):
    """Returns a new `Annotation` with the given modifiers removed (if
    present), or all modifiers removed if `modifiers` is None.

    Args:
        modifiers: Set of modifiers to be removed, or `None` if all should
            be removed.
    """
    new_annotation = self.__class__(None)
    new_annotation.term = self.term
    if modifiers is None:
        new_annotation.modifiers = frozenset()
    else:
        new_annotation.modifiers = self.modifiers - modifiers
    return new_annotation

AnnotationCollection

Bases: Set

Object that parses and processes localisation (or other) annotation strings of the form ".

Source code in src/annotations/annotations.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
class AnnotationCollection(Set):
    """Object that parses and processes localisation (or other) annotation
    strings of the form ".
    """
    _annotations: frozenset[Annotation]

    def __init__(
        self,
        annotations_string: str,
        annotation_factory: Callable[[str], Annotation] = (
            _annotation_factory
        ),
        annotation_factory_extra_args: tuple = (),
    ):
        """Creates a new `AnnotationCollection` from the given annotation
        string.

        Typical usage example:
            annotation = AnnotationCollection("cytoplasm[points,weak],nucleoplasm")

        Args:
            annotations_string: Annotation string of the form
                "cytoplasm[points,weak],nucleoplasm".
            annotation_factory: Optional. A way to specify the function to
                call to produce a single annotation entry in the collection.
        """
        if annotations_string != "":
            self._annotations = frozenset([
                annotation_factory(a_str, *annotation_factory_extra_args)
                for a_str in ANNOT_SPLIT_RE.split(annotations_string)
            ])
        else:
            self._annotations = frozenset([])

        self._annotation_factory = annotation_factory
        self._annotation_factory_extra_args = annotation_factory_extra_args

    def __contains__(self, item: str | Annotation):
        """Returns whether the annotation collection contains the given
        annotation entry.

        Args:
            item: Either a string of the form "term[modifier1,modifier2]" or
                an `Annotation` object. If a string was given, it will be
                converted to an `Annotation` object.
        """
        if isinstance(item, str):
            annot = self._annotation_factory(
                item, *self._annotation_factory_extra_args)
        else:
            annot = item
        term_re = re.compile(annot.term)
        for entry in self:
            if (
                term_re.match(entry.term) and
                entry.modifiers.issuperset(annot.modifiers)
            ):
                return True
        return False

    def __repr__(self):
        return ','.join(sorted([repr(entry) for entry in self]))

    def __iter__(self):
        return iter(self._annotations)

    def __len__(self):
        return len(self._annotations)

    def new_from_collection(self, annotations: Collection[Annotation]):
        """Returns a new AnnotationCollection from the given list of
        `Annotation` objects."""
        new = self.__class__("")
        new._annotations = frozenset(annotations)
        return new

    def filter_by_modifiers(
        self,
        require_modifiers: set[str] | None = None,
        exclude_modifiers: set[str] | None = None,
    ):
        """Returns a new `AnnotationCollection` containing the `Annotation`
        objects that fulfill the given criteria.

        Args:
            require_modifiers: Set of modifiers that need to be present. No
                required modifiers assumed if `None`.
            exclude_modifiers: Set of modifiers that cannot be present.
        """
        matches = [
            annot
            for annot in self
            if annot.match(
                annot.term,
                require_modifiers=require_modifiers,
                exclude_modifiers=exclude_modifiers,
            )
        ]
        return self.new_from_collection(matches)

    def match(
        self,
        term: str,
        require_modifiers: set[str] | None = None,
        exclude_modifiers: set[str] | None = None,
        *args, **kwargs,
    ):
        """Returns whether any `Annotation` in the collection matches the given
        term. Optionally allows specifying modifiers that need to be present
        or cannot be present for a positive match.

        Internally, this calls `Annotation.match` on each of the `Annotation`
        objects in the collection until it finds a positive match.

        Args:
            term: Annotation term to match.
            require_modifiers: Set of modifiers that need to be present for a
                positive match. No required modifiers assumed if `None`.
            exclude_modifiers: Set of modifiers that lead to a negative match
                if any of them are present.
        """
        for annot in self:
            if annot.match(
                term,
                require_modifiers,
                exclude_modifiers,
                *args, **kwargs
            ):
                return True
        return False

    def strip_modifiers(self, modifiers: set[str] | None = None):
        """Returns a new `AnnotationCollection` with the given modifiers
        removed from the Annotations. Removes all modifiers if `modifiers` is
        `None`.

        Args:
            modifiers: Set of modifiers to be removed, or `None` if all should
                be removed.
        """
        return self.new_from_collection([
            annotation.strip_modifiers(modifiers)
            for annotation in self
        ])

__contains__(item)

Returns whether the annotation collection contains the given annotation entry.

Parameters:

Name Type Description Default
item str | Annotation

Either a string of the form "term[modifier1,modifier2]" or an Annotation object. If a string was given, it will be converted to an Annotation object.

 required
Source code in src/annotations/annotations.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def __contains__(self, item: str | Annotation):
    """Returns whether the annotation collection contains the given
    annotation entry.

    Args:
        item: Either a string of the form "term[modifier1,modifier2]" or
            an `Annotation` object. If a string was given, it will be
            converted to an `Annotation` object.
    """
    if isinstance(item, str):
        annot = self._annotation_factory(
            item, *self._annotation_factory_extra_args)
    else:
        annot = item
    term_re = re.compile(annot.term)
    for entry in self:
        if (
            term_re.match(entry.term) and
            entry.modifiers.issuperset(annot.modifiers)
        ):
            return True
    return False

__init__(annotations_string, annotation_factory=_annotation_factory, annotation_factory_extra_args=())

Creates a new AnnotationCollection from the given annotation string.

Typical usage example

annotation = AnnotationCollection("cytoplasm[points,weak],nucleoplasm")

Parameters:

Name Type Description Default
annotations_string str

Annotation string of the form "cytoplasm[points,weak],nucleoplasm".

 required
annotation_factory Callable[[str], Annotation]

Optional. A way to specify the function to call to produce a single annotation entry in the collection.

 _annotation_factory
Source code in src/annotations/annotations.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def __init__(
    self,
    annotations_string: str,
    annotation_factory: Callable[[str], Annotation] = (
        _annotation_factory
    ),
    annotation_factory_extra_args: tuple = (),
):
    """Creates a new `AnnotationCollection` from the given annotation
    string.

    Typical usage example:
        annotation = AnnotationCollection("cytoplasm[points,weak],nucleoplasm")

    Args:
        annotations_string: Annotation string of the form
            "cytoplasm[points,weak],nucleoplasm".
        annotation_factory: Optional. A way to specify the function to
            call to produce a single annotation entry in the collection.
    """
    if annotations_string != "":
        self._annotations = frozenset([
            annotation_factory(a_str, *annotation_factory_extra_args)
            for a_str in ANNOT_SPLIT_RE.split(annotations_string)
        ])
    else:
        self._annotations = frozenset([])

    self._annotation_factory = annotation_factory
    self._annotation_factory_extra_args = annotation_factory_extra_args

filter_by_modifiers(require_modifiers=None, exclude_modifiers=None)

Returns a new AnnotationCollection containing the Annotation objects that fulfill the given criteria.

Parameters:

Name Type Description Default
require_modifiers set[str] | None

Set of modifiers that need to be present. No required modifiers assumed if None.

 None
exclude_modifiers set[str] | None

Set of modifiers that cannot be present.

 None
Source code in src/annotations/annotations.py 
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
def filter_by_modifiers(
    self,
    require_modifiers: set[str] | None = None,
    exclude_modifiers: set[str] | None = None,
):
    """Returns a new `AnnotationCollection` containing the `Annotation`
    objects that fulfill the given criteria.

    Args:
        require_modifiers: Set of modifiers that need to be present. No
            required modifiers assumed if `None`.
        exclude_modifiers: Set of modifiers that cannot be present.
    """
    matches = [
        annot
        for annot in self
        if annot.match(
            annot.term,
            require_modifiers=require_modifiers,
            exclude_modifiers=exclude_modifiers,
        )
    ]
    return self.new_from_collection(matches)

match(term, require_modifiers=None, exclude_modifiers=None, *args, **kwargs)

Returns whether any Annotation in the collection matches the given term. Optionally allows specifying modifiers that need to be present or cannot be present for a positive match.

Internally, this calls Annotation.match on each of the Annotation objects in the collection until it finds a positive match.

Parameters:

Name Type Description Default
term str

Annotation term to match.

 required
require_modifiers set[str] | None

Set of modifiers that need to be present for a positive match. No required modifiers assumed if None.

 None
exclude_modifiers set[str] | None

Set of modifiers that lead to a negative match if any of them are present.

 None
Source code in src/annotations/annotations.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
def match(
    self,
    term: str,
    require_modifiers: set[str] | None = None,
    exclude_modifiers: set[str] | None = None,
    *args, **kwargs,
):
    """Returns whether any `Annotation` in the collection matches the given
    term. Optionally allows specifying modifiers that need to be present
    or cannot be present for a positive match.

    Internally, this calls `Annotation.match` on each of the `Annotation`
    objects in the collection until it finds a positive match.

    Args:
        term: Annotation term to match.
        require_modifiers: Set of modifiers that need to be present for a
            positive match. No required modifiers assumed if `None`.
        exclude_modifiers: Set of modifiers that lead to a negative match
            if any of them are present.
    """
    for annot in self:
        if annot.match(
            term,
            require_modifiers,
            exclude_modifiers,
            *args, **kwargs
        ):
            return True
    return False

new_from_collection(annotations)

Returns a new AnnotationCollection from the given list of Annotation objects.

Source code in src/annotations/annotations.py 
196
197
198
199
200
201
def new_from_collection(self, annotations: Collection[Annotation]):
    """Returns a new AnnotationCollection from the given list of
    `Annotation` objects."""
    new = self.__class__("")
    new._annotations = frozenset(annotations)
    return new

strip_modifiers(modifiers=None)

Returns a new AnnotationCollection with the given modifiers removed from the Annotations. Removes all modifiers if modifiers is None.

Parameters:

Name Type Description Default
modifiers set[str] | None

Set of modifiers to be removed, or None if all should be removed.

 None
Source code in src/annotations/annotations.py 
258
259
260
261
262
263
264
265
266
267
268
269
270
def strip_modifiers(self, modifiers: set[str] | None = None):
    """Returns a new `AnnotationCollection` with the given modifiers
    removed from the Annotations. Removes all modifiers if `modifiers` is
    `None`.

    Args:
        modifiers: Set of modifiers to be removed, or `None` if all should
            be removed.
    """
    return self.new_from_collection([
        annotation.strip_modifiers(modifiers)
        for annotation in self
    ])

Ontology

Describes an Annotation ontology tree.

Source code in src/annotations/ontology.py 
80
81
82
83
84
85
86
87
88
89
90
91
class Ontology:
    """Describes an Annotation ontology tree.
    """
    root_entries: list[OntologyEntry]
    """The root entries of the ontology."""
    entries: dict[str, OntologyEntry]
    """Name to entry mapping of all ontology entries."""

    def __init__(self):
        """Create a new `Ontology` object."""
        self.root_entries = []
        self.entries = {}

entries = {} instance-attribute

Name to entry mapping of all ontology entries.

root_entries = [] instance-attribute

The root entries of the ontology.

__init__()

Create a new Ontology object.

Source code in src/annotations/ontology.py 
88
89
90
91
def __init__(self):
    """Create a new `Ontology` object."""
    self.root_entries = []
    self.entries = {}

OntologyAnnotation

Bases: Annotation

Annotation object that is connected to an annotation ontology.

Source code in src/annotations/ontology.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class OntologyAnnotation(Annotation):
    """Annotation object that is connected to an annotation ontology."""
    def __init__(self, annotation_string: str, ontology: Ontology):
        """Create an annotation entry object.

        Args:
            annotation_string: An annotation string of the form
                "term[modifier1,modifier2]".
            ontology: Ontology to use for the annotation.
        """
        super().__init__(annotation_string)
        self.ontology_entry = ontology.entries[self.term]

    def _match_term(self, term, recursive: bool = True):
        return self.ontology_entry.match_term(term, recursive=recursive)

__init__(annotation_string, ontology)

Create an annotation entry object.

Parameters:

Name Type Description Default
annotation_string str

An annotation string of the form "term[modifier1,modifier2]".

 required
ontology Ontology

Ontology to use for the annotation.

 required
Source code in src/annotations/ontology.py 
 96
 97
 98
 99
100
101
102
103
104
105
def __init__(self, annotation_string: str, ontology: Ontology):
    """Create an annotation entry object.

    Args:
        annotation_string: An annotation string of the form
            "term[modifier1,modifier2]".
        ontology: Ontology to use for the annotation.
    """
    super().__init__(annotation_string)
    self.ontology_entry = ontology.entries[self.term]

OntologyAnnotationCollection

Bases: AnnotationCollection

Annotation collection that is connected to an annotation ontology.

Source code in src/annotations/ontology.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
class OntologyAnnotationCollection(AnnotationCollection):
    """Annotation collection that is connected to an annotation ontology.
    """
    def __init__(self, annotations_string: str, ontology: Ontology):
        """Create an annotation entry object.

        Args:
            annotations_string: Annotation string of the form
                "cytoplasm[points,weak],nucleoplasm".
            ontology: Ontology to use for the annotations.
        """
        self.ontology = ontology
        super().__init__(
            annotations_string,
            _ontology_annotation_factory,
            (ontology,),
        )

    def __and__(self, other: OntologyAnnotationCollection):
        intersection = self._annotations & other._annotations
        result = OntologyAnnotationCollection("", self.ontology)
        result._annotations = intersection
        return result

    def __or__(self, other: OntologyAnnotationCollection):
        union = self._annotations | other._annotations
        result = OntologyAnnotationCollection("", self.ontology)
        result._annotations = union
        return result

    def match(
        self,
        term: str,
        require_modifiers: set[str] | None = None,
        exclude_modifiers: set[str] | None = None,
        recursive: bool = True,
        *args, **kwargs,
    ):
        """Returns whether any `Annotation` in the collection matches the given
        term. Optionally allows specifying modifiers that need to be present
        or cannot be present for a positive match. This also matches any
        children of the given ontology term recursively if `recursive` is
        `True` (the default).

        Internally, this calls `Annotation.match` on each of the `Annotation`
        objects in the collection until it finds a positive match.

        Args:
            term: Annotation term to match.
            require_modifiers: Set of modifiers that need to be present for a
                positive match. No required modifiers assumed if `None`.
            exclude_modifiers: Set of modifiers that lead to a negative match
                if any of them are present.
            recursive: Whether to match the children of the given ontology
                term as well.
        """
        return super().match(
            term,
            require_modifiers=require_modifiers,
            exclude_modifiers=exclude_modifiers,
            recursive=recursive,
            *args, **kwargs,
        )

    def new_from_collection(
        self,
        annotations: Collection[OntologyAnnotation],
    ):
        """Returns a new OntologyAnnotationCollection from the given list of
        `OntologyAnnotation` objects."""
        new = OntologyAnnotationCollection("", self.ontology)
        new._annotations = frozenset(annotations)
        return new

__init__(annotations_string, ontology)

Create an annotation entry object.

Parameters:

Name Type Description Default
annotations_string str

Annotation string of the form "cytoplasm[points,weak],nucleoplasm".

 required
ontology Ontology

Ontology to use for the annotations.

 required
Source code in src/annotations/ontology.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def __init__(self, annotations_string: str, ontology: Ontology):
    """Create an annotation entry object.

    Args:
        annotations_string: Annotation string of the form
            "cytoplasm[points,weak],nucleoplasm".
        ontology: Ontology to use for the annotations.
    """
    self.ontology = ontology
    super().__init__(
        annotations_string,
        _ontology_annotation_factory,
        (ontology,),
    )

match(term, require_modifiers=None, exclude_modifiers=None, recursive=True, *args, **kwargs)

Returns whether any Annotation in the collection matches the given term. Optionally allows specifying modifiers that need to be present or cannot be present for a positive match. This also matches any children of the given ontology term recursively if recursive is True (the default).

Internally, this calls Annotation.match on each of the Annotation objects in the collection until it finds a positive match.

Parameters:

Name Type Description Default
term str

Annotation term to match.

 required
require_modifiers set[str] | None

Set of modifiers that need to be present for a positive match. No required modifiers assumed if None.

 None
exclude_modifiers set[str] | None

Set of modifiers that lead to a negative match if any of them are present.

 None
recursive bool

Whether to match the children of the given ontology term as well.

 True
Source code in src/annotations/ontology.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
def match(
    self,
    term: str,
    require_modifiers: set[str] | None = None,
    exclude_modifiers: set[str] | None = None,
    recursive: bool = True,
    *args, **kwargs,
):
    """Returns whether any `Annotation` in the collection matches the given
    term. Optionally allows specifying modifiers that need to be present
    or cannot be present for a positive match. This also matches any
    children of the given ontology term recursively if `recursive` is
    `True` (the default).

    Internally, this calls `Annotation.match` on each of the `Annotation`
    objects in the collection until it finds a positive match.

    Args:
        term: Annotation term to match.
        require_modifiers: Set of modifiers that need to be present for a
            positive match. No required modifiers assumed if `None`.
        exclude_modifiers: Set of modifiers that lead to a negative match
            if any of them are present.
        recursive: Whether to match the children of the given ontology
            term as well.
    """
    return super().match(
        term,
        require_modifiers=require_modifiers,
        exclude_modifiers=exclude_modifiers,
        recursive=recursive,
        *args, **kwargs,
    )

new_from_collection(annotations)

Returns a new OntologyAnnotationCollection from the given list of OntologyAnnotation objects.

Source code in src/annotations/ontology.py 
179
180
181
182
183
184
185
186
187
def new_from_collection(
    self,
    annotations: Collection[OntologyAnnotation],
):
    """Returns a new OntologyAnnotationCollection from the given list of
    `OntologyAnnotation` objects."""
    new = OntologyAnnotationCollection("", self.ontology)
    new._annotations = frozenset(annotations)
    return new

OntologyEntry

Describes an entry / level of an annotation ontology.

Source code in src/annotations/ontology.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class OntologyEntry:
    """Describes an entry / level of an annotation ontology.
    """
    name: str
    synonyms: tuple[str]
    comment: str | None
    ident: str | None
    goterm: str | None
    children: set[OntologyEntry]
    parent: OntologyEntry | None
    examples: list[str]

    def __init__(
        self,
        name: str,
        synonyms: tuple[str] | None = None,
        comment: str | None = None,
        ident: str | None = None,
        goterm: str | None = None,
        examples: list[str] | None = None,
    ):
        """Create a new ontology entry.

        Args:
            name: Name of the entry.
            synonyms: Tuple of synonyms of the entry.
            comment: Comment associated with the entry.
            ident: N/A
            goterm: GO term identifier.
            examples: List of examples that can be associated with this entry.
        """
        self.name = name
        if synonyms is not None:
            self.synonyms = tuple(synonyms)
        else:
            self.synonyms = tuple()
        self.comment = comment
        self.ident = ident
        self.goterm = goterm
        self.children = set()
        self.parent = None
        if examples is not None:
            self.examples = examples
        else:
            self.examples = []

    def set_parent(self, parent: OntologyEntry):
        """Set this entry's parent ontology entry."""
        self.parent = parent

    def add_child(self, child: OntologyEntry):
        """Add a child ontology entry to this entry."""
        self.children.add(child)

    def __hash__(self):
        return hash((self.__class__, self.name))

    def match_term(self, term: str, recursive: bool = True) -> bool:
        """Returns whether the given term matches the entry's name. Returns
        `True` if any of the entries descendents match if `recursive` is
        `True`

        Args:
            term: Term to check then name against.
            recursive: Whether to recursively check the entries children.
        """
        if self.name == term:
            return True
        if recursive and self.parent is not None:
            return self.parent.match_term(term, recursive=True)
        return False

__init__(name, synonyms=None, comment=None, ident=None, goterm=None, examples=None)

Create a new ontology entry.

Parameters:

Name Type Description Default
name str

Name of the entry.

 required
synonyms tuple[str] | None

Tuple of synonyms of the entry.

 None
comment str | None

Comment associated with the entry.

 None
ident str | None

N/A

 None
goterm str | None

GO term identifier.

 None
examples list[str] | None

List of examples that can be associated with this entry.

 None
Source code in src/annotations/ontology.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(
    self,
    name: str,
    synonyms: tuple[str] | None = None,
    comment: str | None = None,
    ident: str | None = None,
    goterm: str | None = None,
    examples: list[str] | None = None,
):
    """Create a new ontology entry.

    Args:
        name: Name of the entry.
        synonyms: Tuple of synonyms of the entry.
        comment: Comment associated with the entry.
        ident: N/A
        goterm: GO term identifier.
        examples: List of examples that can be associated with this entry.
    """
    self.name = name
    if synonyms is not None:
        self.synonyms = tuple(synonyms)
    else:
        self.synonyms = tuple()
    self.comment = comment
    self.ident = ident
    self.goterm = goterm
    self.children = set()
    self.parent = None
    if examples is not None:
        self.examples = examples
    else:
        self.examples = []

add_child(child)

Add a child ontology entry to this entry.

Source code in src/annotations/ontology.py 
57
58
59
def add_child(self, child: OntologyEntry):
    """Add a child ontology entry to this entry."""
    self.children.add(child)

match_term(term, recursive=True)

Returns whether the given term matches the entry's name. Returns True if any of the entries descendents match if recursive is True

Parameters:

Name Type Description Default
term str

Term to check then name against.

 required
recursive bool

Whether to recursively check the entries children.

 True
Source code in src/annotations/ontology.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def match_term(self, term: str, recursive: bool = True) -> bool:
    """Returns whether the given term matches the entry's name. Returns
    `True` if any of the entries descendents match if `recursive` is
    `True`

    Args:
        term: Term to check then name against.
        recursive: Whether to recursively check the entries children.
    """
    if self.name == term:
        return True
    if recursive and self.parent is not None:
        return self.parent.match_term(term, recursive=True)
    return False

set_parent(parent)

Set this entry's parent ontology entry.

Source code in src/annotations/ontology.py 
53
54
55
def set_parent(self, parent: OntologyEntry):
    """Set this entry's parent ontology entry."""
    self.parent = parent