From 39fe3f5187d73b6e561b5acabd0ba59611ee3aee Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Wed, 10 Aug 2022 18:53:13 +0900 Subject: [PATCH 01/16] Add experimental coref docs --- website/docs/api/architectures.md | 91 +++++++- website/docs/api/coref.md | 355 +++++++++++++++++++++++++++++ website/docs/api/span-resolver.md | 358 ++++++++++++++++++++++++++++++ 3 files changed, 798 insertions(+), 6 deletions(-) create mode 100644 website/docs/api/coref.md create mode 100644 website/docs/api/span-resolver.md diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index 2537faff68d..9e1afb85ae3 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -587,8 +587,8 @@ consists of either two or three subnetworks: run once for each batch. - **lower**: Construct a feature-specific vector for each `(token, feature)` pair. This is also run once for each batch. Constructing the state - representation is then a matter of summing the component features and - applying the non-linearity. + representation is then a matter of summing the component features and applying + the non-linearity. - **upper** (optional): A feed-forward network that predicts scores from the state representation. If not present, the output from the lower model is used as action scores directly. @@ -628,8 +628,8 @@ same signature, but the `use_upper` argument was `True` by default. > ``` Build a tagger model, using a provided token-to-vector component. The tagger -model adds a linear layer with softmax activation to predict scores given -the token vectors. +model adds a linear layer with softmax activation to predict scores given the +token vectors. | Name | Description | | ----------- | ------------------------------------------------------------------------------------------ | @@ -920,5 +920,84 @@ A function that reads an existing `KnowledgeBase` from file. A function that takes as input a [`KnowledgeBase`](/api/kb) and a [`Span`](/api/span) object denoting a named entity, and returns a list of plausible [`Candidate`](/api/kb/#candidate) objects. The default -`CandidateGenerator` uses the text of a mention to find its potential -aliases in the `KnowledgeBase`. Note that this function is case-dependent. +`CandidateGenerator` uses the text of a mention to find its potential aliases in +the `KnowledgeBase`. Note that this function is case-dependent. + +## Coreference Architectures {#coref-architectures tag="experimental" new="3.4"} + +A [`CoreferenceResolver`](/api/coref) component identifies tokens that refer to +the same entity. A [`SpanResolver`](/api/span-resolver) component infers spans +from single tokens. Together these components can be used to reproduce +traditional coreference models. You can also omit the `SpanResolver` if working +with only token-level clusters is acceptable. + +### spacy.Coref.v1 {#Coref tag="experimental"} + +> #### Example Config +> +> ```ini +> +> [model] +> @architectures = "spacy.Coref.v1" +> distance_embedding_size = 20 +> dropout = 0.3 +> hidden_size = 1024 +> depth = 2 +> antecedent_limit = 50 +> antecedent_batch_size = 512 +> +> [model.tok2vec] +> @architectures = "spacy-transformers.TransformerListener.v1" +> grad_factor = 1.0 +> upstream = "transformer" +> pooling = {"@layers":"reduce_mean.v1"} +> ``` + +The `Coref` model architecture is a Thinc `Model`. + +| Name | Description | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `tok2vec` | The [`tok2vec`](#tok2vec) layer of the model. ~~Model~~ | +| `distance_embedding_size` | A representation of the distance between candidates. ~~int~~ | +| `dropout` | The dropout to use internally. Unlike some Thinc models, this has separate dropout for the internal PyTorch layers. ~~float~~ | +| `hidden_size` | Size of the main internal layers. ~~int~~ | +| `depth` | Depth of the internal network. ~~int~~ | +| `antecedent_limit` | How many candidate antecedents to keep after rough scoring. This has a significant effect on memory usage. Typical values would be 50 to 200, or higher for very long documents. ~~int~~ | +| `antecedent_batch_size` | Internal batch size. ~~int~~ | +| **CREATES** | The model using the architecture. ~~Model[List[Doc], Floats2d]~~ | + +### spacy.SpanResolver.v1 {#SpanResolver tag="experimental"} + +> #### Example Config +> +> ```ini +> +> [model] +> @architectures = "spacy.SpanResolver.v1" +> hidden_size = 1024 +> distance_embedding_size = 64 +> conv_channels = 4 +> window_size = 1 +> max_distance = 128 +> prefix = "coref_head_clusters" +> +> [model.tok2vec] +> @architectures = "spacy-transformers.TransformerListener.v1" +> grad_factor = 1.0 +> upstream = "transformer" +> pooling = {"@layers":"reduce_mean.v1"} +> ``` + +The `SpanResolver` model architecture is a Thinc `Model`. + +| Name | Description | +| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `tok2vec` | The [`tok2vec`](#tok2vec) layer of the model. ~~Model~~ | +| `distance_embedding_size` | A representation of the distance between two candidates. ~~int~~ | +| `dropout` | The dropout to use internally. Unlike some Thinc models, this has separate dropout for the internal PyTorch layers. ~~float~~ | +| `hidden_size` | Size of the main internal layers. ~~int~~ | +| `conv_channels` | The number of channels in the internal CNN. ~~int~~ | +| `window_size` | The number of neighboring tokens to consider in the internal CNN. `1` means consider one token on each side. ~~int~~ | +| `max_distance` | The longest possible length of a predicted span. ~~int~~ | +| `prefix` | The prefix that indicates spans to use for input data. ~~string~~ | +| **CREATES** | The model using the architecture. ~~Model[List[Doc], TupleFloats2d]~~ | diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md new file mode 100644 index 00000000000..9bed9a1517e --- /dev/null +++ b/website/docs/api/coref.md @@ -0,0 +1,355 @@ +--- +title: CoreferenceResolver +tag: class,experimental +source: spacy-experimental/coref/coref_component.py +new: 3.4 +teaser: 'Pipeline component for word-level coreference resolution' +api_base_class: /api/pipe +api_string_name: coref +api_trainable: true +--- + +> #### Installation +> +> ```bash +> $ pip install -U spacy-experimental +> ``` + + + +This component not yet integrated into spaCy core, and is available via the +extension package +[`spacy-experimental`](https://github.com/explosion/spacy-transformers). It +exposes the component via entry points, so if you have the package installed, +using `factory = "coref"` in your [training config](/usage/training#config) or +`nlp.add_pipe("coref")` will work out-of-the-box. + + + +A `CoreferenceResolver` component groups tokens into clusters that refer to the +same thing. Clusters are represented as SpanGroups that start with a prefix +(`coref_clusters_` by default). + +A `CoreferenceResolver` component can be paired with a +[`SpanPredictor`](/api/spanpredictor) to expand single tokens to spans. + +## Assigned Attributes {#assigned-attributes} + +Predictions will be saved to `Doc.spans` as a [`SpanGroup`](/api/spangroup). The +span key will be a prefix plus a serial number referring to the coreference +cluster, starting from zero. + +The span key prefix defaults to `"coreference_clusters"`, but can be passed as a +parameter. + +| Location | Value | +| ------------------------------------------ | ------------------------------------------------------------------------- | +| `Doc.spans[prefix + "_" + cluster_number]` | One coreference cluster, represented as single-token spans. ~~SpanGroup~~ | + +## Config and implementation {#config} + +The default config is defined by the pipeline component factory and describes +how the component should be configured. You can override its settings via the +`config` argument on [`nlp.add_pipe`](/api/language#add_pipe) or in your +[`config.cfg` for training](/usage/training#config). See the +[model architectures](/api/architectures) documentation for details on the +architectures and their arguments and hyperparameters. + +> #### Example +> +> ```python +> from spacy.pipeline.coref import DEFAULT_COREF_MODEL +> config={ +> "model": DEFAULT_COREF_MODEL, +> "span_cluster_prefix": DEFAULT_CLUSTER_PREFIX, +> }, +> nlp.add_pipe("coref", config=config) +> ``` + +| Setting | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [Coref](/api/architectures#Coref). ~~Model~~ | +| `span_cluster_prefix` | The prefix for the keys for clusters saved to `doc.spans`. Defaults to `coref_clusters`. ~~str~~ | + +```python +%%GITHUB_SPACY/spacy/pipeline/coref.py +``` + +## CoreferenceResolver.\_\_init\_\_ {#init tag="method"} + +> #### Example +> +> ```python +> # Construction via add_pipe with default model +> coref = nlp.add_pipe("coref") +> +> # Construction via add_pipe with custom model +> config = {"model": {"@architectures": "my_coref.v1"}} +> coref = nlp.add_pipe("coref", config=config) +> +> # Construction from class +> from spacy.pipeline import CoreferenceResolver +> coref = CoreferenceResolver(nlp.vocab, model) +> ``` + +Create a new pipeline instance. In your application, you would normally use a +shortcut for this and instantiate the component using its string name and +[`nlp.add_pipe`](/api/language#add_pipe). + +| Name | Description | +| --------------------- | --------------------------------------------------------------------------------------------------- | +| `vocab` | The shared vocabulary. ~~Vocab~~ | +| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model~~ | +| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ | +| _keyword-only_ | | +| `span_cluster_prefix` | The prefix for the key for saving clusters of spans. ~~bool~~ | + +## CoreferenceResolver.\_\_call\_\_ {#call tag="method"} + +Apply the pipe to one document. The document is modified in place and returned. +This usually happens under the hood when the `nlp` object is called on a text +and all pipeline components are applied to the `Doc` in order. Both +[`__call__`](/api/coref#call) and [`pipe`](/api/coref#pipe) delegate to the +[`predict`](/api/coref#predict) and +[`set_annotations`](/api/coref#set_annotations) methods. + +> #### Example +> +> ```python +> doc = nlp("This is a sentence.") +> coref = nlp.add_pipe("coref") +> # This usually happens under the hood +> processed = coref(doc) +> ``` + +| Name | Description | +| ----------- | -------------------------------- | +| `doc` | The document to process. ~~Doc~~ | +| **RETURNS** | The processed document. ~~Doc~~ | + +## CoreferenceResolver.pipe {#pipe tag="method"} + +Apply the pipe to a stream of documents. This usually happens under the hood +when the `nlp` object is called on a text and all pipeline components are +applied to the `Doc` in order. Both [`__call__`](/api/coref#call) and +[`pipe`](/api/coref#pipe) delegate to the [`predict`](/api/coref#predict) and +[`set_annotations`](/api/coref#set_annotations) methods. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> for doc in coref.pipe(docs, batch_size=50): +> pass +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------- | +| `stream` | A stream of documents. ~~Iterable[Doc]~~ | +| _keyword-only_ | | +| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ | +| **YIELDS** | The processed documents in order. ~~Doc~~ | + +## CoreferenceResolver.initialize {#initialize tag="method"} + +Initialize the component for training. `get_examples` should be a function that +returns an iterable of [`Example`](/api/example) objects. The data examples are +used to **initialize the model** of the component and can either be the full +training data or a representative sample. Initialization includes validating the +network, +[inferring missing shapes](https://thinc.ai/docs/usage-models#validation) and +setting up the label scheme based on the data. This method is typically called +by [`Language.initialize`](/api/language#initialize). + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> coref.initialize(lambda: [], nlp=nlp) +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ | +| _keyword-only_ | | +| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ | + +## CoreferenceResolver.predict {#predict tag="method"} + +Apply the component's model to a batch of [`Doc`](/api/doc) objects, without +modifying them. Clusters are returned as a list of `MentionClusters`, one for +each input `Doc`. A `MentionClusters` instance is just a list of lists of pairs +of `int`s, where each item corresponds to a cluster, and the `int`s correspond +to token indices. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> clusters = coref.predict([doc1, doc2]) +> ``` + +| Name | Description | +| ----------- | ---------------------------------------------------------------------------- | +| `docs` | The documents to predict. ~~Iterable[Doc]~~ | +| **RETURNS** | The predicted coreference clusters for the `docs`. ~~List[MentionClusters]~~ | + +## CoreferenceResolver.set_annotations {#set_annotations tag="method"} + +Modify a batch of documents, saving coreference clusters in `Doc.spans`. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> clusters = coref.predict([doc1, doc2]) +> coref.set_annotations([doc1, doc2], clusters) +> ``` + +| Name | Description | +| ---------- | ---------------------------------------------------------------------------- | +| `docs` | The documents to modify. ~~Iterable[Doc]~~ | +| `clusters` | The predicted coreference clusters for the `docs`. ~~List[MentionClusters]~~ | + +## CoreferenceResolver.update {#update tag="method"} + +Learn from a batch of [`Example`](/api/example) objects. Delegates to +[`predict`](/api/coref#predict). + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> optimizer = nlp.initialize() +> losses = coref.update(examples, sgd=optimizer) +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `examples` | A batch of [`Example`](/api/example) objects to learn from. ~~Iterable[Example]~~ | +| _keyword-only_ | | +| `drop` | The dropout rate. ~~float~~ | +| `sgd` | An optimizer. Will be created via [`create_optimizer`](#create_optimizer) if not set. ~~Optional[Optimizer]~~ | +| `losses` | Optional record of the loss during training. Updated using the component name as the key. ~~Optional[Dict[str, float]]~~ | +| **RETURNS** | The updated `losses` dictionary. ~~Dict[str, float]~~ | + +## CoreferenceResolver.create_optimizer {#create_optimizer tag="method"} + +Create an optimizer for the pipeline component. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> optimizer = coref.create_optimizer() +> ``` + +| Name | Description | +| ----------- | ---------------------------- | +| **RETURNS** | The optimizer. ~~Optimizer~~ | + +## CoreferenceResolver.use_params {#use_params tag="method, contextmanager"} + +Modify the pipe's model, to use the given parameter values. At the end of the +context, the original parameters are restored. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> with coref.use_params(optimizer.averages): +> coref.to_disk("/best_model") +> ``` + +| Name | Description | +| -------- | -------------------------------------------------- | +| `params` | The parameter values to use in the model. ~~dict~~ | + +## CoreferenceResolver.to_disk {#to_disk tag="method"} + +Serialize the pipe to disk. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> coref.to_disk("/path/to/coref") +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `path` | A path to a directory, which will be created if it doesn't exist. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | + +## CoreferenceResolver.from_disk {#from_disk tag="method"} + +Load the pipe from disk. Modifies the object in place and returns it. + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> coref.from_disk("/path/to/coref") +> ``` + +| Name | Description | +| -------------- | ----------------------------------------------------------------------------------------------- | +| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | +| **RETURNS** | The modified `CoreferenceResolver` object. ~~CoreferenceResolver~~ | + +## CoreferenceResolver.to_bytes {#to_bytes tag="method"} + +> #### Example +> +> ```python +> coref = nlp.add_pipe("coref") +> coref_bytes = coref.to_bytes() +> ``` + +Serialize the pipe to a bytestring, including the `KnowledgeBase`. + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------- | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | +| **RETURNS** | The serialized form of the `CoreferenceResolver` object. ~~bytes~~ | + +## CoreferenceResolver.from_bytes {#from_bytes tag="method"} + +Load the pipe from a bytestring. Modifies the object in place and returns it. + +> #### Example +> +> ```python +> coref_bytes = coref.to_bytes() +> coref = nlp.add_pipe("coref") +> coref.from_bytes(coref_bytes) +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------- | +| `bytes_data` | The data to load from. ~~bytes~~ | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | +| **RETURNS** | The `CoreferenceResolver` object. ~~CoreferenceResolver~~ | + +## Serialization fields {#serialization-fields} + +During serialization, spaCy will export several data fields used to restore +different aspects of the object. If needed, you can exclude them from +serialization by passing in the string names via the `exclude` argument. + +> #### Example +> +> ```python +> data = coref.to_disk("/path", exclude=["vocab"]) +> ``` + +| Name | Description | +| ------- | -------------------------------------------------------------- | +| `vocab` | The shared [`Vocab`](/api/vocab). | +| `cfg` | The config file. You usually don't want to exclude this. | +| `model` | The binary model data. You usually don't want to exclude this. | diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md new file mode 100644 index 00000000000..6af0e71838e --- /dev/null +++ b/website/docs/api/span-resolver.md @@ -0,0 +1,358 @@ +--- +title: SpanResolver +tag: class,experimental +source: spacy-experimental/coref/span_resolver_component.py +new: 3.4 +teaser: 'Pipeline component for resolving tokens into spans' +api_base_class: /api/pipe +api_string_name: span_resolver +api_trainable: true +--- + +> #### Installation +> +> ```bash +> $ pip install -U spacy-experimental +> ``` + + + +This component not yet integrated into spaCy core, and is available via the +extension package +[`spacy-experimental`](https://github.com/explosion/spacy-transformers). It +exposes the component via entry points, so if you have the package installed, +using `factory = "span_resolver"` in your +[training config](/usage/training#config) or `nlp.add_pipe("span_resolver")` +will work out-of-the-box. + + + +A `SpanResolver` component takes in tokens (represented as `Span`s of length + +1. and resolves them into `Span`s of arbitrary length. The initial use case is + as a post-processing step on word-level [coreference resolution](/api/coref). + The input and output keys used to store `Span`s are configurable. + +## Assigned Attributes {#assigned-attributes} + +Predictions will be saved to `Doc.spans` as [`SpanGroup`s](/api/spangroup). + +Input token spans will be read in using an input prefix, by default +`"coref_head_clusters"`, and output spans will be saved using an output prefix +(default `"coref_clusters"`) plus a serial number starting from zero. The +prefixes are configurable. + +| Location | Value | +| ------------------------------------------------- | ------------------------------------------- | +| `Doc.spans[output_prefix + "_" + cluster_number]` | One group of predicted spans. ~~SpanGroup~~ | + +## Config and implementation {#config} + +The default config is defined by the pipeline component factory and describes +how the component should be configured. You can override its settings via the +`config` argument on [`nlp.add_pipe`](/api/language#add_pipe) or in your +[`config.cfg` for training](/usage/training#config). See the +[model architectures](/api/architectures) documentation for details on the +architectures and their arguments and hyperparameters. + +> #### Example +> +> ```python +> from spacy.pipeline.span_resolver import DEFAULT_span_resolver_MODEL +> config={ +> "model": DEFAULT_span_resolver_MODEL, +> "span_cluster_prefix": DEFAULT_CLUSTER_PREFIX, +> }, +> nlp.add_pipe("span_resolver", config=config) +> ``` + +| Setting | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [SpanResolver](/api/architectures#SpanResolver). ~~Model~~ | +| `input_prefix` | The prefix to use for input `SpanGroup`s. Defaults to `coref_head_clusters`. ~~str~~ | +| `output_prefix` | The prefix for predicted `SpanGroup`s. Defaults to `coref_clusters`. ~~str~~ | + +```python +%%GITHUB_SPACY/spacy/pipeline/span_resolver.py +``` + +## SpanResolver.\_\_init\_\_ {#init tag="method"} + +> #### Example +> +> ```python +> # Construction via add_pipe with default model +> span_resolver = nlp.add_pipe("span_resolver") +> +> # Construction via add_pipe with custom model +> config = {"model": {"@architectures": "my_span_resolver.v1"}} +> span_resolver = nlp.add_pipe("span_resolver", config=config) +> +> # Construction from class +> from spacy.pipeline import SpanResolver +> span_resolver = SpanResolver(nlp.vocab, model) +> ``` + +Create a new pipeline instance. In your application, you would normally use a +shortcut for this and instantiate the component using its string name and +[`nlp.add_pipe`](/api/language#add_pipe). + +| Name | Description | +| --------------- | --------------------------------------------------------------------------------------------------- | +| `vocab` | The shared vocabulary. ~~Vocab~~ | +| `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. ~~Model~~ | +| `name` | String name of the component instance. Used to add entries to the `losses` during training. ~~str~~ | +| _keyword-only_ | | +| `input_prefix` | The prefix to use for input `SpanGroup`s. Defaults to `coref_head_clusters`. ~~str~~ | +| `output_prefix` | The prefix for predicted `SpanGroup`s. Defaults to `coref_clusters`. ~~str~~ | + +## SpanResolver.\_\_call\_\_ {#call tag="method"} + +Apply the pipe to one document. The document is modified in place and returned. +This usually happens under the hood when the `nlp` object is called on a text +and all pipeline components are applied to the `Doc` in order. Both +[`__call__`](#call) and [`pipe`](#pipe) delegate to the [`predict`](#predict) +and [`set_annotations`](#set_annotations) methods. + +> #### Example +> +> ```python +> doc = nlp("This is a sentence.") +> span_resolver = nlp.add_pipe("span_resolver") +> # This usually happens under the hood +> processed = span_resolver(doc) +> ``` + +| Name | Description | +| ----------- | -------------------------------- | +| `doc` | The document to process. ~~Doc~~ | +| **RETURNS** | The processed document. ~~Doc~~ | + +## SpanResolver.pipe {#pipe tag="method"} + +Apply the pipe to a stream of documents. This usually happens under the hood +when the `nlp` object is called on a text and all pipeline components are +applied to the `Doc` in order. Both [`__call__`](/api/span-resolver#call) and +[`pipe`](/api/span-resolver#pipe) delegate to the +[`predict`](/api/span-resolver#predict) and +[`set_annotations`](/api/span-resolver#set_annotations) methods. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> for doc in span_resolver.pipe(docs, batch_size=50): +> pass +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------- | +| `stream` | A stream of documents. ~~Iterable[Doc]~~ | +| _keyword-only_ | | +| `batch_size` | The number of documents to buffer. Defaults to `128`. ~~int~~ | +| **YIELDS** | The processed documents in order. ~~Doc~~ | + +## SpanResolver.initialize {#initialize tag="method"} + +Initialize the component for training. `get_examples` should be a function that +returns an iterable of [`Example`](/api/example) objects. The data examples are +used to **initialize the model** of the component and can either be the full +training data or a representative sample. Initialization includes validating the +network, +[inferring missing shapes](https://thinc.ai/docs/usage-models#validation) and +setting up the label scheme based on the data. This method is typically called +by [`Language.initialize`](/api/language#initialize). + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver.initialize(lambda: [], nlp=nlp) +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ | +| _keyword-only_ | | +| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ | + +## SpanResolver.predict {#predict tag="method"} + +Apply the component's model to a batch of [`Doc`](/api/doc) objects, without +modifying them. Predictions are returned as a list of `MentionClusters`, one for +each input `Doc`. A `MentionClusters` instance is just a list of lists of pairs +of `int`s, where each item corresponds to an input `SpanGroup`, and the `int`s +correspond to token indices. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> spans = span_resolver.predict([doc1, doc2]) +> ``` + +| Name | Description | +| ----------- | ------------------------------------------------------------- | +| `docs` | The documents to predict. ~~Iterable[Doc]~~ | +| **RETURNS** | The predicted spans for the `Doc`s. ~~List[MentionClusters]~~ | + +## SpanResolver.set_annotations {#set_annotations tag="method"} + +Modify a batch of documents, saving predictions using the output prefix in +`Doc.spans`. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> spans = span_resolver.predict([doc1, doc2]) +> span_resolver.set_annotations([doc1, doc2], spans) +> ``` + +| Name | Description | +| ------- | ------------------------------------------------------------- | +| `docs` | The documents to modify. ~~Iterable[Doc]~~ | +| `spans` | The predicted spans for the `docs`. ~~List[MentionClusters]~~ | + +## SpanResolver.update {#update tag="method"} + +Learn from a batch of [`Example`](/api/example) objects. Delegates to +[`predict`](/api/span-resolver#predict). + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> optimizer = nlp.initialize() +> losses = span_resolver.update(examples, sgd=optimizer) +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `examples` | A batch of [`Example`](/api/example) objects to learn from. ~~Iterable[Example]~~ | +| _keyword-only_ | | +| `drop` | The dropout rate. ~~float~~ | +| `sgd` | An optimizer. Will be created via [`create_optimizer`](#create_optimizer) if not set. ~~Optional[Optimizer]~~ | +| `losses` | Optional record of the loss during training. Updated using the component name as the key. ~~Optional[Dict[str, float]]~~ | +| **RETURNS** | The updated `losses` dictionary. ~~Dict[str, float]~~ | + +## SpanResolver.create_optimizer {#create_optimizer tag="method"} + +Create an optimizer for the pipeline component. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> optimizer = span_resolver.create_optimizer() +> ``` + +| Name | Description | +| ----------- | ---------------------------- | +| **RETURNS** | The optimizer. ~~Optimizer~~ | + +## SpanResolver.use_params {#use_params tag="method, contextmanager"} + +Modify the pipe's model, to use the given parameter values. At the end of the +context, the original parameters are restored. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> with span_resolver.use_params(optimizer.averages): +> span_resolver.to_disk("/best_model") +> ``` + +| Name | Description | +| -------- | -------------------------------------------------- | +| `params` | The parameter values to use in the model. ~~dict~~ | + +## SpanResolver.to_disk {#to_disk tag="method"} + +Serialize the pipe to disk. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver.to_disk("/path/to/span_resolver") +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `path` | A path to a directory, which will be created if it doesn't exist. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | + +## SpanResolver.from_disk {#from_disk tag="method"} + +Load the pipe from disk. Modifies the object in place and returns it. + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver.from_disk("/path/to/span_resolver") +> ``` + +| Name | Description | +| -------------- | ----------------------------------------------------------------------------------------------- | +| `path` | A path to a directory. Paths may be either strings or `Path`-like objects. ~~Union[str, Path]~~ | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | +| **RETURNS** | The modified `SpanResolver` object. ~~SpanResolver~~ | + +## SpanResolver.to_bytes {#to_bytes tag="method"} + +> #### Example +> +> ```python +> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver_bytes = span_resolver.to_bytes() +> ``` + +Serialize the pipe to a bytestring. + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------- | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | +| **RETURNS** | The serialized form of the `SpanResolver` object. ~~bytes~~ | + +## SpanResolver.from_bytes {#from_bytes tag="method"} + +Load the pipe from a bytestring. Modifies the object in place and returns it. + +> #### Example +> +> ```python +> span_resolver_bytes = span_resolver.to_bytes() +> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver.from_bytes(span_resolver_bytes) +> ``` + +| Name | Description | +| -------------- | ------------------------------------------------------------------------------------------- | +| `bytes_data` | The data to load from. ~~bytes~~ | +| _keyword-only_ | | +| `exclude` | String names of [serialization fields](#serialization-fields) to exclude. ~~Iterable[str]~~ | +| **RETURNS** | The `SpanResolver` object. ~~SpanResolver~~ | + +## Serialization fields {#serialization-fields} + +During serialization, spaCy will export several data fields used to restore +different aspects of the object. If needed, you can exclude them from +serialization by passing in the string names via the `exclude` argument. + +> #### Example +> +> ```python +> data = span_resolver.to_disk("/path", exclude=["vocab"]) +> ``` + +| Name | Description | +| ------- | -------------------------------------------------------------- | +| `vocab` | The shared [`Vocab`](/api/vocab). | +| `cfg` | The config file. You usually don't want to exclude this. | +| `model` | The binary model data. You usually don't want to exclude this. | From c7c269b539a0fd73b6e9624222b06a1d0f2b1063 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Wed, 10 Aug 2022 19:08:39 +0900 Subject: [PATCH 02/16] Docs cleanup --- website/docs/api/architectures.md | 3 ++- website/docs/api/coref.md | 10 +++++----- website/docs/api/span-resolver.md | 8 ++++---- website/meta/sidebars.json | 2 ++ 4 files changed, 13 insertions(+), 10 deletions(-) diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index 9e1afb85ae3..66d12d0a1ae 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -11,6 +11,7 @@ menu: - ['Text Classification', 'textcat'] - ['Span Classification', 'spancat'] - ['Entity Linking', 'entitylinker'] + - ['Coreference', 'coref-architectures'] --- A **model architecture** is a function that wires up a @@ -923,7 +924,7 @@ plausible [`Candidate`](/api/kb/#candidate) objects. The default `CandidateGenerator` uses the text of a mention to find its potential aliases in the `KnowledgeBase`. Note that this function is case-dependent. -## Coreference Architectures {#coref-architectures tag="experimental" new="3.4"} +## Coreference {#coref-architectures tag="experimental" new="3.4"} A [`CoreferenceResolver`](/api/coref) component identifies tokens that refer to the same entity. A [`SpanResolver`](/api/span-resolver) component infers spans diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index 9bed9a1517e..7e38ccf8986 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -28,7 +28,7 @@ using `factory = "coref"` in your [training config](/usage/training#config) or A `CoreferenceResolver` component groups tokens into clusters that refer to the same thing. Clusters are represented as SpanGroups that start with a prefix -(`coref_clusters_` by default). +(`coref_clusters` by default). A `CoreferenceResolver` component can be paired with a [`SpanPredictor`](/api/spanpredictor) to expand single tokens to spans. @@ -39,12 +39,12 @@ Predictions will be saved to `Doc.spans` as a [`SpanGroup`](/api/spangroup). The span key will be a prefix plus a serial number referring to the coreference cluster, starting from zero. -The span key prefix defaults to `"coreference_clusters"`, but can be passed as a +The span key prefix defaults to `"coref_clusters"`, but can be passed as a parameter. -| Location | Value | -| ------------------------------------------ | ------------------------------------------------------------------------- | -| `Doc.spans[prefix + "_" + cluster_number]` | One coreference cluster, represented as single-token spans. ~~SpanGroup~~ | +| Location | Value | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- | +| `Doc.spans[prefix + "_" + cluster_number]` | One coreference cluster, represented as single-token spans. Cluster numbers start from 1. ~~SpanGroup~~ | ## Config and implementation {#config} diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 6af0e71838e..3b8bc7390ff 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -39,12 +39,12 @@ Predictions will be saved to `Doc.spans` as [`SpanGroup`s](/api/spangroup). Input token spans will be read in using an input prefix, by default `"coref_head_clusters"`, and output spans will be saved using an output prefix -(default `"coref_clusters"`) plus a serial number starting from zero. The +(default `"coref_clusters"`) plus a serial number starting from one. The prefixes are configurable. -| Location | Value | -| ------------------------------------------------- | ------------------------------------------- | -| `Doc.spans[output_prefix + "_" + cluster_number]` | One group of predicted spans. ~~SpanGroup~~ | +| Location | Value | +| ------------------------------------------------- | ------------------------------------------------------------------------- | +| `Doc.spans[output_prefix + "_" + cluster_number]` | One group of predicted spans. Cluster number starts from 1. ~~SpanGroup~~ | ## Config and implementation {#config} diff --git a/website/meta/sidebars.json b/website/meta/sidebars.json index 1b743636cda..8f527e824e9 100644 --- a/website/meta/sidebars.json +++ b/website/meta/sidebars.json @@ -95,6 +95,7 @@ "label": "Pipeline", "items": [ { "text": "AttributeRuler", "url": "/api/attributeruler" }, + { "text": "CoreferenceResolver", "url": "/api/coref" }, { "text": "DependencyParser", "url": "/api/dependencyparser" }, { "text": "EditTreeLemmatizer", "url": "/api/edittreelemmatizer" }, { "text": "EntityLinker", "url": "/api/entitylinker" }, @@ -105,6 +106,7 @@ { "text": "SentenceRecognizer", "url": "/api/sentencerecognizer" }, { "text": "Sentencizer", "url": "/api/sentencizer" }, { "text": "SpanCategorizer", "url": "/api/spancategorizer" }, + { "text": "SpanResolver", "url": "/api/span-resolver" }, { "text": "SpanRuler", "url": "/api/spanruler" }, { "text": "Tagger", "url": "/api/tagger" }, { "text": "TextCategorizer", "url": "/api/textcategorizer" }, From fbceea1296c482aa43b7620ee15f7b3b004ca3b9 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Mon, 15 Aug 2022 14:17:31 +0900 Subject: [PATCH 03/16] Apply suggestions from code review Co-authored-by: Sofie Van Landeghem --- website/docs/api/coref.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index 7e38ccf8986..e393a34df81 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -17,7 +17,7 @@ api_trainable: true -This component not yet integrated into spaCy core, and is available via the +This component is not yet integrated into spaCy core, and is available via the extension package [`spacy-experimental`](https://github.com/explosion/spacy-transformers). It exposes the component via entry points, so if you have the package installed, From 8b2b11f3be9b75398932b6b0e3afb743b0952629 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Mon, 15 Aug 2022 14:24:08 +0900 Subject: [PATCH 04/16] Apply changes from code review --- website/docs/api/coref.md | 20 +++++++++----------- website/docs/api/span-resolver.md | 15 ++++++--------- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index e393a34df81..ff6491a1219 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -19,10 +19,12 @@ api_trainable: true This component is not yet integrated into spaCy core, and is available via the extension package -[`spacy-experimental`](https://github.com/explosion/spacy-transformers). It -exposes the component via entry points, so if you have the package installed, -using `factory = "coref"` in your [training config](/usage/training#config) or -`nlp.add_pipe("coref")` will work out-of-the-box. +[`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting +in version 0.6.0. It exposes the component via +[entry points](/usage/saving-loading/#entry-points), so if you have the package +installed, using `factory = "coref"` in your +[training config](/usage/training#config) or `nlp.add_pipe("coref")` will work +out-of-the-box. @@ -31,7 +33,7 @@ same thing. Clusters are represented as SpanGroups that start with a prefix (`coref_clusters` by default). A `CoreferenceResolver` component can be paired with a -[`SpanPredictor`](/api/spanpredictor) to expand single tokens to spans. +[`SpanResolver`](/api/span-resolver) to expand single tokens to spans. ## Assigned Attributes {#assigned-attributes} @@ -52,8 +54,8 @@ The default config is defined by the pipeline component factory and describes how the component should be configured. You can override its settings via the `config` argument on [`nlp.add_pipe`](/api/language#add_pipe) or in your [`config.cfg` for training](/usage/training#config). See the -[model architectures](/api/architectures) documentation for details on the -architectures and their arguments and hyperparameters. +[model architectures](/api/architectures#coref-architectures) documentation for +details on the architectures and their arguments and hyperparameters. > #### Example > @@ -71,10 +73,6 @@ architectures and their arguments and hyperparameters. | `model` | The [`Model`](https://thinc.ai/docs/api-model) powering the pipeline component. Defaults to [Coref](/api/architectures#Coref). ~~Model~~ | | `span_cluster_prefix` | The prefix for the keys for clusters saved to `doc.spans`. Defaults to `coref_clusters`. ~~str~~ | -```python -%%GITHUB_SPACY/spacy/pipeline/coref.py -``` - ## CoreferenceResolver.\_\_init\_\_ {#init tag="method"} > #### Example diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 3b8bc7390ff..8112820deb4 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -19,9 +19,10 @@ api_trainable: true This component not yet integrated into spaCy core, and is available via the extension package -[`spacy-experimental`](https://github.com/explosion/spacy-transformers). It -exposes the component via entry points, so if you have the package installed, -using `factory = "span_resolver"` in your +[`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting +in version 0.6.0. It exposes the component via +[entry points](/usage/saving-loading/#entry-points), so if you have the package +installed, using `factory = "span_resolver"` in your [training config](/usage/training#config) or `nlp.add_pipe("span_resolver")` will work out-of-the-box. @@ -52,8 +53,8 @@ The default config is defined by the pipeline component factory and describes how the component should be configured. You can override its settings via the `config` argument on [`nlp.add_pipe`](/api/language#add_pipe) or in your [`config.cfg` for training](/usage/training#config). See the -[model architectures](/api/architectures) documentation for details on the -architectures and their arguments and hyperparameters. +[model architectures](/api/architectures#coref-architectures) documentation for +details on the architectures and their arguments and hyperparameters. > #### Example > @@ -72,10 +73,6 @@ architectures and their arguments and hyperparameters. | `input_prefix` | The prefix to use for input `SpanGroup`s. Defaults to `coref_head_clusters`. ~~str~~ | | `output_prefix` | The prefix for predicted `SpanGroup`s. Defaults to `coref_clusters`. ~~str~~ | -```python -%%GITHUB_SPACY/spacy/pipeline/span_resolver.py -``` - ## SpanResolver.\_\_init\_\_ {#init tag="method"} > #### Example From e74c009c096ce005a1d95c0fbd258156f8b3a1bf Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Mon, 15 Aug 2022 14:44:38 +0900 Subject: [PATCH 05/16] Fix prettier formatting It seems a period after a number made this think it was a list? --- website/docs/api/span-resolver.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 8112820deb4..32476a78cee 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -28,11 +28,10 @@ will work out-of-the-box. -A `SpanResolver` component takes in tokens (represented as `Span`s of length - -1. and resolves them into `Span`s of arbitrary length. The initial use case is - as a post-processing step on word-level [coreference resolution](/api/coref). - The input and output keys used to store `Span`s are configurable. +A `SpanResolver` component takes in tokens (represented as `Span`s of length 1) +and resolves them into `Span`s of arbitrary length. The initial use case is as a +post-processing step on word-level [coreference resolution](/api/coref). The +input and output keys used to store `Span`s are configurable. ## Assigned Attributes {#assigned-attributes} From 8d0faa2ebc825981584c1d226d2a82ccd38d646c Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 16 Aug 2022 14:41:21 +0900 Subject: [PATCH 06/16] Update docs on examples for initialize --- website/docs/api/coref.md | 20 ++++++++++---------- website/docs/api/span-resolver.md | 20 ++++++++++---------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index ff6491a1219..e36f4b8eb18 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -151,10 +151,10 @@ applied to the `Doc` in order. Both [`__call__`](/api/coref#call) and ## CoreferenceResolver.initialize {#initialize tag="method"} Initialize the component for training. `get_examples` should be a function that -returns an iterable of [`Example`](/api/example) objects. The data examples are -used to **initialize the model** of the component and can either be the full -training data or a representative sample. Initialization includes validating the -network, +returns an iterable of [`Example`](/api/example) objects. **At least one example +should be supplied.** The data examples are used to **initialize the model** of +the component and can either be the full training data or a representative +sample. Initialization includes validating the network, [inferring missing shapes](https://thinc.ai/docs/usage-models#validation) and setting up the label scheme based on the data. This method is typically called by [`Language.initialize`](/api/language#initialize). @@ -163,14 +163,14 @@ by [`Language.initialize`](/api/language#initialize). > > ```python > coref = nlp.add_pipe("coref") -> coref.initialize(lambda: [], nlp=nlp) +> coref.initialize(lambda: examples, nlp=nlp) > ``` -| Name | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ | -| _keyword-only_ | | -| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ | +| Name | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. Must contain at least one `Example`. ~~Callable[[], Iterable[Example]]~~ | +| _keyword-only_ | | +| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ | ## CoreferenceResolver.predict {#predict tag="method"} diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 32476a78cee..157ba595978 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -151,10 +151,10 @@ applied to the `Doc` in order. Both [`__call__`](/api/span-resolver#call) and ## SpanResolver.initialize {#initialize tag="method"} Initialize the component for training. `get_examples` should be a function that -returns an iterable of [`Example`](/api/example) objects. The data examples are -used to **initialize the model** of the component and can either be the full -training data or a representative sample. Initialization includes validating the -network, +returns an iterable of [`Example`](/api/example) objects. **At least one example +should be supplied.** The data examples are used to **initialize the model** of +the component and can either be the full training data or a representative +sample. Initialization includes validating the network, [inferring missing shapes](https://thinc.ai/docs/usage-models#validation) and setting up the label scheme based on the data. This method is typically called by [`Language.initialize`](/api/language#initialize). @@ -163,14 +163,14 @@ by [`Language.initialize`](/api/language#initialize). > > ```python > span_resolver = nlp.add_pipe("span_resolver") -> span_resolver.initialize(lambda: [], nlp=nlp) +> span_resolver.initialize(lambda: examples, nlp=nlp) > ``` -| Name | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. ~~Callable[[], Iterable[Example]]~~ | -| _keyword-only_ | | -| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ | +| Name | Description | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `get_examples` | Function that returns gold-standard annotations in the form of [`Example`](/api/example) objects. Must contain at least one `Example`. ~~Callable[[], Iterable[Example]]~~ | +| _keyword-only_ | | +| `nlp` | The current `nlp` object. Defaults to `None`. ~~Optional[Language]~~ | ## SpanResolver.predict {#predict tag="method"} From 6560a01e8245cf6b9e58bc91e3432452187c4e90 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 16 Aug 2022 16:02:44 +0900 Subject: [PATCH 07/16] Add docs for coref scorers --- website/docs/api/scorer.md | 59 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/website/docs/api/scorer.md b/website/docs/api/scorer.md index 8dbe3b27674..ca3462aa94c 100644 --- a/website/docs/api/scorer.md +++ b/website/docs/api/scorer.md @@ -270,3 +270,62 @@ Compute micro-PRF and per-entity PRF scores. | Name | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ | + +## score_coref_clusters {#score_coref_clusters tag="experimental"} + +Returns LEA ([Moosavi and Strube, 2016](https://aclanthology.org/P16-1060/)) PRF +scores for coreference clusters. + + + +Note this scoring function is not yet included in spaCy core - for details, see +the [CoreferenceResolver](/api/coref) docs. + + + +> #### Example +> +> ```python +> scores = score_coref_clusters( +> examples, +> span_cluster_prefix="coref_clusters", +> ) +> print(scores["coref_f"]) +> ``` + +| Name | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------------- | +| `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ | +| _keyword-only_ | | +| `span_cluster_prefix` | The prefix used for spans representing coreference clusters. ~~str~~ | +| **RETURNS** | A dictionary containing the scores. ~~Dict[str, Optional[float]]~~ | + +## score_span_predictions {#score_span_predictions tag="experimental"} + +Return accuracy for reconstructions of spans from single tokens. Only exactly +correct predictions are counted as correct, there is no partial credit for near +answers. Used by the [SpanResolver](/api/span-resolver). + + + +Note this scoring function is not yet included in spaCy core - for details, see +the [SpanResolver](/api/span-resolver) docs. + + + +> #### Example +> +> ```python +> scores = score_span_predictions( +> examples, +> output_prefix="coref_clusters", +> ) +> print(scores["span_coref_clusters_accuracy"]) +> ``` + +| Name | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------- | +| `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ | +| _keyword-only_ | | +| `output_prefix` | The prefix used for spans representing the final predicted spans. ~~str~~ | +| **RETURNS** | A dictionary containing the scores. ~~Dict[str, Optional[float]]~~ | From f032fa3816bc42fb34c5ca6ea9fd9c0807516474 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 18 Aug 2022 18:54:28 +0900 Subject: [PATCH 08/16] Remove 3.4 notes from coref There won't be a "new" tag until it's in core. --- website/docs/api/architectures.md | 2 +- website/docs/api/coref.md | 1 - website/docs/api/span-resolver.md | 1 - 3 files changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index 66d12d0a1ae..fe9a398ede9 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -924,7 +924,7 @@ plausible [`Candidate`](/api/kb/#candidate) objects. The default `CandidateGenerator` uses the text of a mention to find its potential aliases in the `KnowledgeBase`. Note that this function is case-dependent. -## Coreference {#coref-architectures tag="experimental" new="3.4"} +## Coreference {#coref-architectures tag="experimental"} A [`CoreferenceResolver`](/api/coref) component identifies tokens that refer to the same entity. A [`SpanResolver`](/api/span-resolver) component infers spans diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index e36f4b8eb18..0b83775ab08 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -2,7 +2,6 @@ title: CoreferenceResolver tag: class,experimental source: spacy-experimental/coref/coref_component.py -new: 3.4 teaser: 'Pipeline component for word-level coreference resolution' api_base_class: /api/pipe api_string_name: coref diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 157ba595978..5647612df58 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -2,7 +2,6 @@ title: SpanResolver tag: class,experimental source: spacy-experimental/coref/span_resolver_component.py -new: 3.4 teaser: 'Pipeline component for resolving tokens into spans' api_base_class: /api/pipe api_string_name: span_resolver From 77b7d64461aee66e17b82af2ff51d8414808877e Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Wed, 14 Sep 2022 14:50:28 +0900 Subject: [PATCH 09/16] Add docs for span cleaner --- website/docs/api/pipeline-functions.md | 31 ++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/website/docs/api/pipeline-functions.md b/website/docs/api/pipeline-functions.md index 1b7017ca7e0..83dde515d8c 100644 --- a/website/docs/api/pipeline-functions.md +++ b/website/docs/api/pipeline-functions.md @@ -153,3 +153,34 @@ whole pipeline has run. | `attrs` | A dict of the `Doc` attributes and the values to set them to. Defaults to `{"tensor": None, "_.trf_data": None}` to clean up after `tok2vec` and `transformer` components. ~~dict~~ | | `silent` | If `False`, show warnings if attributes aren't found or can't be set. Defaults to `True`. ~~bool~~ | | **RETURNS** | The modified `Doc` with the modified attributes. ~~Doc~~ | + +## span_cleaner {#span_cleaner tag="function,experimental"} + +Remove `SpanGroup`s from `doc.spans` based on a key prefix. This is used to +clean up after the [`CoreferenceResolver`](/api/coref) when it's paired with a +[`SpanResolver`](/api/span-resolver). + + + +This pipeline function is not yet integrated into spaCy core, and is available +via the extension package +[`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting +in version 0.6.0. It exposes the component via +[entry points](/usage/saving-loading/#entry-points), so if you have the package +installed, using `factory = "span_cleaner"` in your +[training config](/usage/training#config) or `nlp.add_pipe("span_cleaner")` will +work out-of-the-box. + +> #### Example +> +> ```python +> config = {"prefix": "coref_head_clusters"} +> nlp.add_pipe("span_cleaner", config=config) +> doc = nlp("text") +> assert "coref_head_clusters_1" not in doc.spans +> ``` + +| Setting | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------- | +| `prefix` | A prefix to check `SpanGroup` keys for. Any matching groups will be removed. Defaults to `"coref_head_clusters"`. ~~str~~ | +| **RETURNS** | The modified `Doc` with the modified attributes. ~~Doc~~ | From 212791c3f1bc738c0bf90d1250db6c7bfd6ad788 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Wed, 14 Sep 2022 15:21:05 +0900 Subject: [PATCH 10/16] Fix docs --- website/docs/api/pipeline-functions.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/docs/api/pipeline-functions.md b/website/docs/api/pipeline-functions.md index 83dde515d8c..9ecd65257f2 100644 --- a/website/docs/api/pipeline-functions.md +++ b/website/docs/api/pipeline-functions.md @@ -169,7 +169,9 @@ in version 0.6.0. It exposes the component via [entry points](/usage/saving-loading/#entry-points), so if you have the package installed, using `factory = "span_cleaner"` in your [training config](/usage/training#config) or `nlp.add_pipe("span_cleaner")` will -work out-of-the-box. +work out-of-the-box. + + > #### Example > @@ -183,4 +185,4 @@ work out-of-the-box. | Setting | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | `prefix` | A prefix to check `SpanGroup` keys for. Any matching groups will be removed. Defaults to `"coref_head_clusters"`. ~~str~~ | -| **RETURNS** | The modified `Doc` with the modified attributes. ~~Doc~~ | +| **RETURNS** | The modified `Doc` with any matching spans removed. ~~Doc~~ | From cd1d8ec383fe998b2a4821b23031ba5d6dfc997d Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 15 Sep 2022 13:26:08 +0900 Subject: [PATCH 11/16] Fix docs to match spacy-experimental These weren't properly updated when the code was moved out of spacy core. --- website/docs/api/architectures.md | 26 ++++++++--------- website/docs/api/coref.md | 41 +++++++++++++-------------- website/docs/api/span-resolver.md | 46 ++++++++++++++++--------------- 3 files changed, 58 insertions(+), 55 deletions(-) diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index fe9a398ede9..7c65a4ad254 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -989,16 +989,16 @@ The `Coref` model architecture is a Thinc `Model`. > pooling = {"@layers":"reduce_mean.v1"} > ``` -The `SpanResolver` model architecture is a Thinc `Model`. - -| Name | Description | -| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `tok2vec` | The [`tok2vec`](#tok2vec) layer of the model. ~~Model~~ | -| `distance_embedding_size` | A representation of the distance between two candidates. ~~int~~ | -| `dropout` | The dropout to use internally. Unlike some Thinc models, this has separate dropout for the internal PyTorch layers. ~~float~~ | -| `hidden_size` | Size of the main internal layers. ~~int~~ | -| `conv_channels` | The number of channels in the internal CNN. ~~int~~ | -| `window_size` | The number of neighboring tokens to consider in the internal CNN. `1` means consider one token on each side. ~~int~~ | -| `max_distance` | The longest possible length of a predicted span. ~~int~~ | -| `prefix` | The prefix that indicates spans to use for input data. ~~string~~ | -| **CREATES** | The model using the architecture. ~~Model[List[Doc], TupleFloats2d]~~ | +The `SpanResolver` model architecture is a Thinc `Model`. Note that +`MentionClusters` is `List[List[Tuple[int, int]]]`. + +| Name | Description | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `tok2vec` | The [`tok2vec`](#tok2vec) layer of the model. ~~Model~~ | +| `hidden_size` | Size of the main internal layers. ~~int~~ | +| `distance_embedding_size` | A representation of the distance between two candidates. ~~int~~ | +| `conv_channels` | The number of channels in the internal CNN. ~~int~~ | +| `window_size` | The number of neighboring tokens to consider in the internal CNN. `1` means consider one token on each side. ~~int~~ | +| `max_distance` | The longest possible length of a predicted span. ~~int~~ | +| `prefix` | The prefix that indicates spans to use for input data. ~~string~~ | +| **CREATES** | The model using the architecture. ~~Model[List[Doc], List[MentionClusters]]~~ | diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index 0b83775ab08..983fb545bb3 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -21,9 +21,9 @@ extension package [`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting in version 0.6.0. It exposes the component via [entry points](/usage/saving-loading/#entry-points), so if you have the package -installed, using `factory = "coref"` in your -[training config](/usage/training#config) or `nlp.add_pipe("coref")` will work -out-of-the-box. +installed, using `factory = "experimental_coref"` in your +[training config](/usage/training#config) or +`nlp.add_pipe("experimental_coref")` will work out-of-the-box. @@ -59,12 +59,13 @@ details on the architectures and their arguments and hyperparameters. > #### Example > > ```python -> from spacy.pipeline.coref import DEFAULT_COREF_MODEL +> from spacy_experimental.coref.coref_component import DEFAULT_COREF_MODEL +> from spacy_experimental.coref.coref_util import DEFAULT_CLUSTER_PREFIX > config={ > "model": DEFAULT_COREF_MODEL, > "span_cluster_prefix": DEFAULT_CLUSTER_PREFIX, > }, -> nlp.add_pipe("coref", config=config) +> nlp.add_pipe("experimental_coref", config=config) > ``` | Setting | Description | @@ -78,14 +79,14 @@ details on the architectures and their arguments and hyperparameters. > > ```python > # Construction via add_pipe with default model -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > > # Construction via add_pipe with custom model > config = {"model": {"@architectures": "my_coref.v1"}} -> coref = nlp.add_pipe("coref", config=config) +> coref = nlp.add_pipe("experimental_coref", config=config) > > # Construction from class -> from spacy.pipeline import CoreferenceResolver +> from spacy_experimental.coref.coref_component import CoreferenceResolver > coref = CoreferenceResolver(nlp.vocab, model) > ``` @@ -114,7 +115,7 @@ and all pipeline components are applied to the `Doc` in order. Both > > ```python > doc = nlp("This is a sentence.") -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > # This usually happens under the hood > processed = coref(doc) > ``` @@ -135,7 +136,7 @@ applied to the `Doc` in order. Both [`__call__`](/api/coref#call) and > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > for doc in coref.pipe(docs, batch_size=50): > pass > ``` @@ -161,7 +162,7 @@ by [`Language.initialize`](/api/language#initialize). > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > coref.initialize(lambda: examples, nlp=nlp) > ``` @@ -182,7 +183,7 @@ to token indices. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > clusters = coref.predict([doc1, doc2]) > ``` @@ -198,7 +199,7 @@ Modify a batch of documents, saving coreference clusters in `Doc.spans`. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > clusters = coref.predict([doc1, doc2]) > coref.set_annotations([doc1, doc2], clusters) > ``` @@ -216,7 +217,7 @@ Learn from a batch of [`Example`](/api/example) objects. Delegates to > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > optimizer = nlp.initialize() > losses = coref.update(examples, sgd=optimizer) > ``` @@ -237,7 +238,7 @@ Create an optimizer for the pipeline component. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > optimizer = coref.create_optimizer() > ``` @@ -253,7 +254,7 @@ context, the original parameters are restored. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > with coref.use_params(optimizer.averages): > coref.to_disk("/best_model") > ``` @@ -269,7 +270,7 @@ Serialize the pipe to disk. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > coref.to_disk("/path/to/coref") > ``` @@ -286,7 +287,7 @@ Load the pipe from disk. Modifies the object in place and returns it. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > coref.from_disk("/path/to/coref") > ``` @@ -302,7 +303,7 @@ Load the pipe from disk. Modifies the object in place and returns it. > #### Example > > ```python -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > coref_bytes = coref.to_bytes() > ``` @@ -322,7 +323,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it. > > ```python > coref_bytes = coref.to_bytes() -> coref = nlp.add_pipe("coref") +> coref = nlp.add_pipe("experimental_coref") > coref.from_bytes(coref_bytes) > ``` diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 5647612df58..dfdf3e67361 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -21,9 +21,9 @@ extension package [`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting in version 0.6.0. It exposes the component via [entry points](/usage/saving-loading/#entry-points), so if you have the package -installed, using `factory = "span_resolver"` in your -[training config](/usage/training#config) or `nlp.add_pipe("span_resolver")` -will work out-of-the-box. +installed, using `factory = "experimental_span_resolver"` in your +[training config](/usage/training#config) or +`nlp.add_pipe("experimental_span_resolver")` will work out-of-the-box. @@ -57,12 +57,14 @@ details on the architectures and their arguments and hyperparameters. > #### Example > > ```python -> from spacy.pipeline.span_resolver import DEFAULT_span_resolver_MODEL +> from spacy_experimental.coref.span_resolver_component import DEFAULT_SPAN_RESOLVER_MODEL +> from spacy_experimental.coref.coref_util import DEFAULT_CLUSTER_PREFIX, DEFAULT_CLUSTER_HEAD_PREFIX > config={ -> "model": DEFAULT_span_resolver_MODEL, -> "span_cluster_prefix": DEFAULT_CLUSTER_PREFIX, +> "model": DEFAULT_SPAN_RESOLVER_MODEL, +> "input_prefix": DEFAULT_CLUSTER_HEAD_PREFIX, +> "output_prefix": DEFAULT_CLUSTER_PREFIX, > }, -> nlp.add_pipe("span_resolver", config=config) +> nlp.add_pipe("experimental_span_resolver", config=config) > ``` | Setting | Description | @@ -77,14 +79,14 @@ details on the architectures and their arguments and hyperparameters. > > ```python > # Construction via add_pipe with default model -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > > # Construction via add_pipe with custom model > config = {"model": {"@architectures": "my_span_resolver.v1"}} -> span_resolver = nlp.add_pipe("span_resolver", config=config) +> span_resolver = nlp.add_pipe("experimental_span_resolver", config=config) > > # Construction from class -> from spacy.pipeline import SpanResolver +> from spacy_experimental.coref.span_resolver_component import SpanResolver > span_resolver = SpanResolver(nlp.vocab, model) > ``` @@ -113,7 +115,7 @@ and [`set_annotations`](#set_annotations) methods. > > ```python > doc = nlp("This is a sentence.") -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > # This usually happens under the hood > processed = span_resolver(doc) > ``` @@ -135,7 +137,7 @@ applied to the `Doc` in order. Both [`__call__`](/api/span-resolver#call) and > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > for doc in span_resolver.pipe(docs, batch_size=50): > pass > ``` @@ -161,7 +163,7 @@ by [`Language.initialize`](/api/language#initialize). > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > span_resolver.initialize(lambda: examples, nlp=nlp) > ``` @@ -182,7 +184,7 @@ correspond to token indices. > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > spans = span_resolver.predict([doc1, doc2]) > ``` @@ -199,7 +201,7 @@ Modify a batch of documents, saving predictions using the output prefix in > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > spans = span_resolver.predict([doc1, doc2]) > span_resolver.set_annotations([doc1, doc2], spans) > ``` @@ -217,7 +219,7 @@ Learn from a batch of [`Example`](/api/example) objects. Delegates to > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > optimizer = nlp.initialize() > losses = span_resolver.update(examples, sgd=optimizer) > ``` @@ -238,7 +240,7 @@ Create an optimizer for the pipeline component. > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > optimizer = span_resolver.create_optimizer() > ``` @@ -254,7 +256,7 @@ context, the original parameters are restored. > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > with span_resolver.use_params(optimizer.averages): > span_resolver.to_disk("/best_model") > ``` @@ -270,7 +272,7 @@ Serialize the pipe to disk. > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > span_resolver.to_disk("/path/to/span_resolver") > ``` @@ -287,7 +289,7 @@ Load the pipe from disk. Modifies the object in place and returns it. > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > span_resolver.from_disk("/path/to/span_resolver") > ``` @@ -303,7 +305,7 @@ Load the pipe from disk. Modifies the object in place and returns it. > #### Example > > ```python -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > span_resolver_bytes = span_resolver.to_bytes() > ``` @@ -323,7 +325,7 @@ Load the pipe from a bytestring. Modifies the object in place and returns it. > > ```python > span_resolver_bytes = span_resolver.to_bytes() -> span_resolver = nlp.add_pipe("span_resolver") +> span_resolver = nlp.add_pipe("experimental_span_resolver") > span_resolver.from_bytes(span_resolver_bytes) > ``` From 41651849b11eba0c8bf00338c8068ec83380c16a Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 15 Sep 2022 13:30:42 +0900 Subject: [PATCH 12/16] More doc fixes --- website/docs/api/architectures.md | 4 ++-- website/docs/api/span-resolver.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index 7c65a4ad254..3019ff23967 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -939,7 +939,7 @@ with only token-level clusters is acceptable. > ```ini > > [model] -> @architectures = "spacy.Coref.v1" +> @architectures = "spacy-experimental.Coref.v1" > distance_embedding_size = 20 > dropout = 0.3 > hidden_size = 1024 @@ -974,7 +974,7 @@ The `Coref` model architecture is a Thinc `Model`. > ```ini > > [model] -> @architectures = "spacy.SpanResolver.v1" +> @architectures = "spacy-experimental.SpanResolver.v1" > hidden_size = 1024 > distance_embedding_size = 64 > conv_channels = 4 diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index dfdf3e67361..b684f5392e1 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -27,10 +27,10 @@ installed, using `factory = "experimental_span_resolver"` in your -A `SpanResolver` component takes in tokens (represented as `Span`s of length 1) -and resolves them into `Span`s of arbitrary length. The initial use case is as a +A `SpanResolver` component takes in tokens (represented as `Span` objects of length 1) +and resolves them into `Span` objects of arbitrary length. The initial use case is as a post-processing step on word-level [coreference resolution](/api/coref). The -input and output keys used to store `Span`s are configurable. +input and output keys used to store `Span` objects are configurable. ## Assigned Attributes {#assigned-attributes} From a4cdb7601c6a6cb1260cf220ac3f4bf2ac65b7c3 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 15 Sep 2022 13:31:18 +0900 Subject: [PATCH 13/16] Formatting --- website/docs/api/span-resolver.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index b684f5392e1..43be40cb568 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -27,10 +27,11 @@ installed, using `factory = "experimental_span_resolver"` in your -A `SpanResolver` component takes in tokens (represented as `Span` objects of length 1) -and resolves them into `Span` objects of arbitrary length. The initial use case is as a -post-processing step on word-level [coreference resolution](/api/coref). The -input and output keys used to store `Span` objects are configurable. +A `SpanResolver` component takes in tokens (represented as `Span` objects of +length 1) and resolves them into `Span` objects of arbitrary length. The initial +use case is as a post-processing step on word-level +[coreference resolution](/api/coref). The input and output keys used to store +`Span` objects are configurable. ## Assigned Attributes {#assigned-attributes} From b6106ebd224c3facd4284295126768d1bd7334a9 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Fri, 16 Sep 2022 12:09:39 +0900 Subject: [PATCH 14/16] Update architectures --- website/docs/api/architectures.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index 3019ff23967..4c5447f7542 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -932,7 +932,7 @@ from single tokens. Together these components can be used to reproduce traditional coreference models. You can also omit the `SpanResolver` if working with only token-level clusters is acceptable. -### spacy.Coref.v1 {#Coref tag="experimental"} +### spacy-experimental.Coref.v1 {#Coref tag="experimental"} > #### Example Config > @@ -967,7 +967,7 @@ The `Coref` model architecture is a Thinc `Model`. | `antecedent_batch_size` | Internal batch size. ~~int~~ | | **CREATES** | The model using the architecture. ~~Model[List[Doc], Floats2d]~~ | -### spacy.SpanResolver.v1 {#SpanResolver tag="experimental"} +### spacy-experimental.SpanResolver.v1 {#SpanResolver tag="experimental"} > #### Example Config > From 54e6f326d0543fcb63f2c4cd4db73c5d19c682f6 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 27 Sep 2022 13:34:57 +0900 Subject: [PATCH 15/16] Fix links --- website/docs/api/coref.md | 2 +- website/docs/api/span-resolver.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/api/coref.md b/website/docs/api/coref.md index 983fb545bb3..8f54422d642 100644 --- a/website/docs/api/coref.md +++ b/website/docs/api/coref.md @@ -18,7 +18,7 @@ api_trainable: true This component is not yet integrated into spaCy core, and is available via the extension package -[`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting +[`spacy-experimental`](https://github.com/explosion/spacy-experimental) starting in version 0.6.0. It exposes the component via [entry points](/usage/saving-loading/#entry-points), so if you have the package installed, using `factory = "experimental_coref"` in your diff --git a/website/docs/api/span-resolver.md b/website/docs/api/span-resolver.md index 43be40cb568..3e992cd0378 100644 --- a/website/docs/api/span-resolver.md +++ b/website/docs/api/span-resolver.md @@ -18,7 +18,7 @@ api_trainable: true This component not yet integrated into spaCy core, and is available via the extension package -[`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting +[`spacy-experimental`](https://github.com/explosion/spacy-experimental) starting in version 0.6.0. It exposes the component via [entry points](/usage/saving-loading/#entry-points), so if you have the package installed, using `factory = "experimental_span_resolver"` in your From 18bfe734b72bd82ad0d07b671cbe294afa1f4495 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 27 Sep 2022 18:02:47 +0900 Subject: [PATCH 16/16] Fix another link --- website/docs/api/pipeline-functions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/pipeline-functions.md b/website/docs/api/pipeline-functions.md index 9ecd65257f2..0702927824f 100644 --- a/website/docs/api/pipeline-functions.md +++ b/website/docs/api/pipeline-functions.md @@ -164,7 +164,7 @@ clean up after the [`CoreferenceResolver`](/api/coref) when it's paired with a This pipeline function is not yet integrated into spaCy core, and is available via the extension package -[`spacy-experimental`](https://github.com/explosion/spacy-transformers) starting +[`spacy-experimental`](https://github.com/explosion/spacy-experimental) starting in version 0.6.0. It exposes the component via [entry points](/usage/saving-loading/#entry-points), so if you have the package installed, using `factory = "span_cleaner"` in your