spaCy/website/docs/api/spangroup.md
Adriane Boyd b65d652881
Override SpanGroups.setdefault to provide default SpanGroup (#10772)
* Fix mistake in SpanGroup API docs

* Restrict SpanGroups.setdefault to SpanGroup only

* Refactor to support default span iterable
2022-05-12 10:06:25 +02:00

9.9 KiB

title tag source new
SpanGroup class spacy/tokens/span_group.pyx 3

A group of arbitrary, potentially overlapping Span objects that all belong to the same Doc object. The group can be named, and you can attach additional attributes to it. Span groups are generally accessed via the Doc.spans attribute, which will convert lists of spans into a SpanGroup object for you automatically on assignment. SpanGroup objects behave similar to lists, so you can append Span objects to them or access a member at a given index.

SpanGroup.__init__

Create a SpanGroup.

Example

doc = nlp("Their goi ng home")
spans = [doc[0:1], doc[1:3]]

# Construction 1
from spacy.tokens import SpanGroup

group = SpanGroup(doc, name="errors", spans=spans, attrs={"annotator": "matt"})
doc.spans["errors"] = group

# Construction 2
doc.spans["errors"] = spans
assert isinstance(doc.spans["errors"], SpanGroup)
Name Description
doc The document the span group belongs to. Doc
keyword-only
name The name of the span group. If the span group is created automatically on assignment to doc.spans, the key name is used. Defaults to "". str
attrs Optional JSON-serializable attributes to attach to the span group. Dict[str, Any]
spans The spans to add to the span group. Iterable[Span]

SpanGroup.doc

The Doc object the span group is referring to.

When a Doc object is garbage collected, any related SpanGroup object won't be functional anymore, as these objects use a weakref to refer to the document. An error will be raised as the internal doc object will be None. To avoid this, make sure that the original Doc objects are still available in the scope of your function.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
assert doc.spans["errors"].doc == doc
Name Description
RETURNS The reference document. Doc

SpanGroup.has_overlap

Check whether the span group contains overlapping spans.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
assert not doc.spans["errors"].has_overlap
doc.spans["errors"].append(doc[2:4])
assert doc.spans["errors"].has_overlap
Name Description
RETURNS Whether the span group contains overlaps. bool

SpanGroup.__len__

Get the number of spans in the group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
assert len(doc.spans["errors"]) == 2
Name Description
RETURNS The number of spans in the group. int

SpanGroup.__getitem__

Get a span from the group. Note that a copy of the span is returned, so if any changes are made to this span, they are not reflected in the corresponding member of the span group. The item or group will need to be reassigned for changes to be reflected in the span group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
span = doc.spans["errors"][1]
assert span.text == "goi ng"
span.label_ = 'LABEL'
assert doc.spans["errors"][1].label_ != 'LABEL' # The span within the group was not updated
Name Description
i The item index. int
RETURNS The span at the given index. Span

SpanGroup.__setitem__

Set a span in the span group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
span = doc[0:2]
doc.spans["errors"][0] = span
assert doc.spans["errors"][0].text == "Their goi"
Name Description
i The item index. int
span The new value. Span

SpanGroup.__delitem__

Delete a span from the span group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
del doc.spans[0]
assert len(doc.spans["errors"]) == 1
Name Description
i The item index. int

SpanGroup.__add__

Concatenate the current span group with another span group and return the result in a new span group. Any attrs from the first span group will have precedence over attrs in the second.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
doc.spans["other"] = [doc[0:2], doc[2:4]]
span_group = doc.spans["errors"] + doc.spans["other"]
assert len(span_group) == 4
Name Description
other The span group or spans to concatenate. Union[SpanGroup, Iterable[Span]]
RETURNS The new span group. SpanGroup

SpanGroup.__iadd__

Append an iterable of spans or the content of a span group to the current span group. Any attrs in the other span group will be added for keys that are not already present in the current span group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
doc.spans["errors"] += [doc[3:4], doc[2:3]]
assert len(doc.spans["errors"]) == 4
Name Description
other The span group or spans to append. Union[SpanGroup, Iterable[Span]]
RETURNS The span group. SpanGroup

SpanGroup.append

Add a Span object to the group. The span must refer to the same Doc object as the span group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1]]
doc.spans["errors"].append(doc[1:3])
assert len(doc.spans["errors"]) == 2
Name Description
span The span to append. Span

SpanGroup.extend

Add multiple Span objects or contents of another SpanGroup to the group. All spans must refer to the same Doc object as the span group.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = []
doc.spans["errors"].extend([doc[1:3], doc[0:1]])
assert len(doc.spans["errors"]) == 2
span_group = SpanGroup(doc, spans=[doc[1:4], doc[0:3]])
doc.spans["errors"].extend(span_group)
Name Description
spans The spans to add. Union[SpanGroup, Iterable["Span"]]

SpanGroup.copy

Return a copy of the span group.

Example

from spacy.tokens import SpanGroup

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[1:3], doc[0:3]]
new_group = doc.spans["errors"].copy()
Name Description
RETURNS A copy of the SpanGroup object. SpanGroup

SpanGroup.to_bytes

Serialize the span group to a bytestring.

Example

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
group_bytes = doc.spans["errors"].to_bytes()
Name Description
RETURNS The serialized SpanGroup. bytes

SpanGroup.from_bytes

Load the span group from a bytestring. Modifies the object in place and returns it.

Example

from spacy.tokens import SpanGroup

doc = nlp("Their goi ng home")
doc.spans["errors"] = [doc[0:1], doc[1:3]]
group_bytes = doc.spans["errors"].to_bytes()
new_group = SpanGroup()
new_group.from_bytes(group_bytes)
Name Description
bytes_data The data to load from. bytes
RETURNS The SpanGroup object. SpanGroup